sievemin 0.1.1__tar.gz

sievemin-0.1.1/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.1 (2026-10-31)
+
+- First release on PyPI: `pip install sievemin`. Packaging metadata, a `music21` extra, and a publish workflow. No change to the solver.
+
+## 0.1.0 (2026-10-30)
+
+- First release: exact minimisation of Xenakis sieves (`minimize_union`, `minimize_dnf`, `minimize_general`, `minimize_union_tolerant`), CLI, benchmarks and report.

sievemin-0.1.1/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "sievemin: exact minimisation of Xenakis sieves"
+type: software
+authors:
+  - family-names: Bentley
+    given-names: Duncan
+    orcid: "https://orcid.org/0009-0006-9443-5129"
+version: 0.1.1
+date-released: 2026-10-31
+doi: 10.5281/zenodo.23816540
+license: BSD-3-Clause
+repository-code: "https://github.com/DuncanBentley/sievemin"
+url: "https://github.com/DuncanBentley/sievemin"
+keywords:
+  - Xenakis
+  - sieve theory
+  - music theory
+  - set cover
+  - integer linear programming
+  - music21

sievemin-0.1.1/LICENSE

@@ -0,0 +1,26 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Duncan Bentley
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sievemin-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md CITATION.cff REPORT.md
+recursive-include tests *.py
+exclude music21-issue-draft.md music21-feature-proposal.md *.patch

sievemin-0.1.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: sievemin
+Version: 0.1.1
+Summary: Exact (provably minimal) Xenakis sieve formulas for integer sets
+Author: Duncan Bentley
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/DuncanBentley/sievemin
+Project-URL: Repository, https://github.com/DuncanBentley/sievemin
+Project-URL: Issues, https://github.com/DuncanBentley/sievemin/issues
+Project-URL: Changelog, https://github.com/DuncanBentley/sievemin/blob/main/CHANGELOG.md
+Project-URL: DOI, https://doi.org/10.5281/zenodo.23816540
+Keywords: Xenakis,sieve theory,music theory,set cover,integer linear programming,music21,computational musicology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy>=1.9
+Provides-Extra: music21
+Requires-Dist: music21; extra == "music21"
+Provides-Extra: bench
+Requires-Dist: music21; extra == "bench"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: music21; extra == "test"
+Dynamic: license-file
+
+# sievemin
+
+`sievemin` finds the shortest Xenakis sieve that produces a given set of integers, and proves nothing shorter exists in the formula shape you asked for. Against music21's greedy compressor it is shorter on 928 of 1,000 random segments, and it shortens several published Xenakis sieves.
+
+[![CI](https://github.com/DuncanBentley/sievemin/actions/workflows/ci.yml/badge.svg)](https://github.com/DuncanBentley/sievemin/actions) [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/DuncanBentley/sievemin/blob/main/LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/DuncanBentley/sievemin/blob/main/pyproject.toml) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23816540.svg)](https://doi.org/10.5281/zenodo.23816540)
+
+A sieve is a formula built from residue classes `m@r` (every n with n mod m = r), joined with union `|`, intersection `&` and complement `-`. The output uses music21's sieve syntax, so you can paste it into `music21.sieve.Sieve`.
+
+I make metal and produce records. Sieves are a tidy way to write down a scale or a rhythm that doesn't repeat every octave or every bar. I wanted to know whether the formulas people publish, and the ones music21 generates, are actually the short ones. Mostly they're close. Sometimes they aren't.
+
+## Key findings
+
+| finding | numbers | where |
+|---|---|---|
+| music21's greedy is already optimal on its own small examples | 12 of 12 music21 test segments match the exact class count | [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) section 3 |
+| It loses on bigger sets (z = 0..99, music21's modulus limit) | Psappha 20 classes down to 15, Nomos Alpha 8 to 7, À R. 17 to 14, Nekuïa 11 to 8 | [bench/results.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/results.md), Table 1 |
+| It loses on random segments of 5 to 100 points | 928 of 1,000 shorter, 22.4% fewer classes on average, max 40.5%, never longer | [bench/random_segments.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_segments.md) |
+| Smaller period | median period 70 against 21,162,960 for music21, at the price of 34.5 classes on average | [bench/random_segments.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_segments.md) |
+| Published Xenakis formulas are not all minimal, even with the composer's own moduli | Nomos Alpha size 23 to 21, Psappha (Flint) 59 to 36, À R. 99 to 88, Jonchaies already minimal | [bench/results.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/results.md), Table 2 |
+| Complement makes formulas shorter | the major scale goes from 18 to 10 (any modulus); on 251 small random segments, `&` and `-` beat the best union on 180 | [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) section 3 |
+| The gain is smaller on structured material | 100 random Xenakis-style sieves: 37 shorter, 11.4% on average, median 0% | [bench/random_study.csv](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_study.csv) |
+| Error-tolerant mode (formula plus k wrong notes) | recovers a planted sieve with 1, 2, 3 flipped notes in 100%, 96%, 95% of 150 trials each (cost 1) | [bench/tolerant_study.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/tolerant_study.md) |
+
+Random point sets are where the greedy does worst. Real material is more structured, and there the gain is smaller.
+
+## Install
+
+```bash
+pip install sievemin
+```
+
+or with uv:
+
+```bash
+uv add sievemin
+```
+
+`pip install "sievemin[music21]"` also installs music21, so you can check the output with `music21.sieve.Sieve`. sievemin itself only needs numpy and scipy.
+
+## Quick start
+
+```bash
+sievemin 0 2 4 5 7 9 11 --period 12
+# (-(12@1|12@3|12@6|12@8|12@10))
+# size 10 (leaves 5, operators 5); optimal: True; ...
+```
+
+That takes a few seconds, mostly Python start-up. The solve itself is tens of milliseconds.
+
+```python
+from sievemin import Domain, parse, evaluate, minimize_dnf, to_music21
+
+nomos = '(-(13@3|13@5|13@7|13@9)&11@2)|(-(11@4|11@8)&13@9)|(13@0|13@1|13@6)'
+dom = Domain.periodic(143)
+r = minimize_dnf(evaluate(parse(nomos), dom), dom, max_modulus=13, max_neg=4)
+r.text, r.size, r.optimal
+# ('11@2&-(13@3|13@5|13@7)|13@0|13@1|13@6|13@9&-(11@4|11@8)', 21, True)
+to_music21(r.formula)   # bracketed, see the music21 note below
+```
+
+`Domain.window(z)` matches exactly on the points of `z`, which is how music21 works. Pass `max_modulus=len(z) - 1` to stay inside the moduli music21 itself would try. `Domain.periodic(P)` matches on every integer.
+
+For unions you can choose what "shortest" means: `minimize_union(..., objective='leaves' | 'chars' | 'period')`.
+
+`minimize_union_tolerant(points, dom, max_edits=2, edit_cost=1)` returns a formula plus the notes to add and the notes to remove.
+
+One music21 note: music21 10.5.2 crashes on an unbracketed intersection with a complemented class, for example `Sieve('3@1&-4@2')`. `to_music21()` puts brackets around the formula to avoid it.
+
+## Reproduce everything
+
+```bash
+git clone https://github.com/DuncanBentley/sievemin
+cd sievemin
+pip install -e ".[test]"          # adds pytest and music21
+python -m pytest                  # 127 tests
+python bench/reproduce.py         # benchmark and tolerant study, a few minutes
+python bench/reproduce.py --all   # adds the 1,000 random segments, 1 to 2 hours
+```
+
+`bench/reproduce.py` writes `bench/results.md` and `results.csv`, plus `bench/tolerant_study.md` and `tolerant_study.csv`. With `--all` it also writes `bench/random_segments.md` and `random_segments.csv`. The 100 random Xenakis-style sieves are in `bench/random_study.csv`. Seeds are fixed (2026), so the optimal values reproduce exactly. Runtimes depend on the machine. Mine is a Ryzen 9 8940HX laptop, where the 1,000-segment run took 1 hour 54 minutes.
+
+## What it guarantees
+
+| function | what it searches | what is proven |
+|---|---|---|
+| `minimize_union` | unions of residue classes, the form music21's `CompressionSegment` outputs | the fewest classes, the shortest string, or the smallest period, by exact ILP over every candidate class |
+| `minimize_dnf` | unions of terms `P & -(N1\|...\|Nk)`, the shape of Xenakis's published sieves | the smallest formula of that shape, for a given cap on k and, optionally, on the moduli |
+| `minimize_general` | formulas of any shape | the smallest formula there is, by exhaustive search, for domains of up to 14 points |
+| `minimize_union_tolerant` | a union of classes plus up to k notes added or removed | the smallest formula size + λ × exceptions |
+
+Size means leaves plus operators, so a union of n classes has size 2n - 1. Every result says whether the solver proved it optimal. I also ran every published result in this repo back through music21's own `Sieve` and checked it gives the same set.
+
+## Method
+
+Unions are an exact set cover, solved as an ILP with HiGHS through scipy. The candidate list is every residue class that stays inside the target, so the minimum is global. Terms with complement are enumerated per positive class, then another set cover picks the cheapest union. The any-shape search is dynamic programming over all subsets of up to 14 points. [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) has the details, the benchmarks and the prior-work notes.
+
+## Limits / what this does not show
+
+`minimize_dnf` is only optimal within its own shape. A formula nested differently can be shorter. With moduli up to 4, the major scale has a size 16 formula, and the best union of terms is 17. Only `minimize_general` covers every shape, and it runs out of room past 14 points.
+
+A result on a window only holds on that window, as with music21. If the formula has to hold on every integer, use `Domain.periodic(P)`. A window formula can use moduli no composer would pick, like `41@24`.
+
+Exact set cover is NP-hard. Most sets solve in milliseconds, but some 100-point windows take tens of seconds, and the slowest random segment took 248 s.
+
+The error-tolerant mode only works with unions, and its answer depends on the exception cost λ, which you choose. That it finds structure in Xenakis's sets is not evidence that he edited notes by hand.
+
+On music21's own 12 test segments the greedy is already optimal. The 1,000 random segments have no structure, so 22.4% is not what to expect on a real scale or rhythm.
+
+I haven't read *Formalized Music* or Xenakis 1990 directly. The published formulas come from music21's tests and the hmt library, and the value lists I generate match hmt's for Nomos Alpha, Psappha and À R.
+
+Whether a shorter formula is better music is not something this measures.
+
+## Upstream and sources
+
+- music21: <https://github.com/cuthbertLab/music21>. I studied version 10.5.2 ([release](https://github.com/cuthbertLab/music21/releases/tag/v10.5.2)), specifically [`music21/sieve.py`](https://github.com/cuthbertLab/music21/blob/v10.5.2/music21/sieve.py). Docs: <https://www.music21.org/music21docs/moduleReference/moduleSieve.html>.
+- hmt (Rohan Drape, Haskell), a second source for the published sieves: <https://github.com/rd--/hmt>.
+- Ariza, C. 2005. "The Xenakis Sieve as Object: A New Model and a Complete Implementation." *Computer Music Journal* 29(2). DOI 10.1162/0148926054094396. This is the model behind music21's sieve.
+- Xenakis, I. 1990. "Sieves." *Perspectives of New Music* 28(1): <https://doi.org/10.2307/833343>.
+- Bliznets, Nederlof and Szilágyi, "Parameterized Algorithms for Covering by Arithmetic Progressions": <https://arxiv.org/abs/2312.06393>.
+
+No external data is downloaded. The published sieve definitions are re-typed from music21's tests and hmt, and the random sets come from fixed seeds.
+
+## Status of upstream reports
+
+| Report | Status |
+|---|---|
+| music21: crash on `Sieve('3@1&-4@2')` (unbracketed intersection with a complemented class), one-line fix plus test | issue filed: [cuthbertLab/music21#2131](https://github.com/cuthbertLab/music21/issues/2131), fixed and merged in [#2135](https://github.com/cuthbertLab/music21/pull/2135) |
+| music21: opt-in exact compression, `CompressionSegment(..., method='exact')` | to be filed |
+
+## Citation
+
+See [CITATION.cff](https://github.com/DuncanBentley/sievemin/blob/main/CITATION.cff).
+
+```bibtex
+@software{bentley2026_sievemin,
+  author = {Bentley, Duncan},
+  title  = {sievemin: exact minimisation of Xenakis sieves},
+  year   = {2026},
+  url    = {https://github.com/DuncanBentley/sievemin},
+  doi    = {10.5281/zenodo.23816540}
+}
+```
+
+## License
+
+BSD-3-Clause, the same as music21. See [LICENSE](https://github.com/DuncanBentley/sievemin/blob/main/LICENSE). The repo contains no third-party data.
+
+## Acknowledgements
+
+Thanks to Michael Scott Cuthbert and the music21 contributors, whose `sieve.py` I tested against, to Christopher Ariza for the sieve model it implements, and to Rohan Drape for hmt.
+

sievemin-0.1.1/README.md

@@ -0,0 +1,151 @@
+# sievemin
+
+`sievemin` finds the shortest Xenakis sieve that produces a given set of integers, and proves nothing shorter exists in the formula shape you asked for. Against music21's greedy compressor it is shorter on 928 of 1,000 random segments, and it shortens several published Xenakis sieves.
+
+[![CI](https://github.com/DuncanBentley/sievemin/actions/workflows/ci.yml/badge.svg)](https://github.com/DuncanBentley/sievemin/actions) [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/DuncanBentley/sievemin/blob/main/LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/DuncanBentley/sievemin/blob/main/pyproject.toml) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23816540.svg)](https://doi.org/10.5281/zenodo.23816540)
+
+A sieve is a formula built from residue classes `m@r` (every n with n mod m = r), joined with union `|`, intersection `&` and complement `-`. The output uses music21's sieve syntax, so you can paste it into `music21.sieve.Sieve`.
+
+I make metal and produce records. Sieves are a tidy way to write down a scale or a rhythm that doesn't repeat every octave or every bar. I wanted to know whether the formulas people publish, and the ones music21 generates, are actually the short ones. Mostly they're close. Sometimes they aren't.
+
+## Key findings
+
+| finding | numbers | where |
+|---|---|---|
+| music21's greedy is already optimal on its own small examples | 12 of 12 music21 test segments match the exact class count | [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) section 3 |
+| It loses on bigger sets (z = 0..99, music21's modulus limit) | Psappha 20 classes down to 15, Nomos Alpha 8 to 7, À R. 17 to 14, Nekuïa 11 to 8 | [bench/results.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/results.md), Table 1 |
+| It loses on random segments of 5 to 100 points | 928 of 1,000 shorter, 22.4% fewer classes on average, max 40.5%, never longer | [bench/random_segments.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_segments.md) |
+| Smaller period | median period 70 against 21,162,960 for music21, at the price of 34.5 classes on average | [bench/random_segments.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_segments.md) |
+| Published Xenakis formulas are not all minimal, even with the composer's own moduli | Nomos Alpha size 23 to 21, Psappha (Flint) 59 to 36, À R. 99 to 88, Jonchaies already minimal | [bench/results.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/results.md), Table 2 |
+| Complement makes formulas shorter | the major scale goes from 18 to 10 (any modulus); on 251 small random segments, `&` and `-` beat the best union on 180 | [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) section 3 |
+| The gain is smaller on structured material | 100 random Xenakis-style sieves: 37 shorter, 11.4% on average, median 0% | [bench/random_study.csv](https://github.com/DuncanBentley/sievemin/blob/main/bench/random_study.csv) |
+| Error-tolerant mode (formula plus k wrong notes) | recovers a planted sieve with 1, 2, 3 flipped notes in 100%, 96%, 95% of 150 trials each (cost 1) | [bench/tolerant_study.md](https://github.com/DuncanBentley/sievemin/blob/main/bench/tolerant_study.md) |
+
+Random point sets are where the greedy does worst. Real material is more structured, and there the gain is smaller.
+
+## Install
+
+```bash
+pip install sievemin
+```
+
+or with uv:
+
+```bash
+uv add sievemin
+```
+
+`pip install "sievemin[music21]"` also installs music21, so you can check the output with `music21.sieve.Sieve`. sievemin itself only needs numpy and scipy.
+
+## Quick start
+
+```bash
+sievemin 0 2 4 5 7 9 11 --period 12
+# (-(12@1|12@3|12@6|12@8|12@10))
+# size 10 (leaves 5, operators 5); optimal: True; ...
+```
+
+That takes a few seconds, mostly Python start-up. The solve itself is tens of milliseconds.
+
+```python
+from sievemin import Domain, parse, evaluate, minimize_dnf, to_music21
+
+nomos = '(-(13@3|13@5|13@7|13@9)&11@2)|(-(11@4|11@8)&13@9)|(13@0|13@1|13@6)'
+dom = Domain.periodic(143)
+r = minimize_dnf(evaluate(parse(nomos), dom), dom, max_modulus=13, max_neg=4)
+r.text, r.size, r.optimal
+# ('11@2&-(13@3|13@5|13@7)|13@0|13@1|13@6|13@9&-(11@4|11@8)', 21, True)
+to_music21(r.formula)   # bracketed, see the music21 note below
+```
+
+`Domain.window(z)` matches exactly on the points of `z`, which is how music21 works. Pass `max_modulus=len(z) - 1` to stay inside the moduli music21 itself would try. `Domain.periodic(P)` matches on every integer.
+
+For unions you can choose what "shortest" means: `minimize_union(..., objective='leaves' | 'chars' | 'period')`.
+
+`minimize_union_tolerant(points, dom, max_edits=2, edit_cost=1)` returns a formula plus the notes to add and the notes to remove.
+
+One music21 note: music21 10.5.2 crashes on an unbracketed intersection with a complemented class, for example `Sieve('3@1&-4@2')`. `to_music21()` puts brackets around the formula to avoid it.
+
+## Reproduce everything
+
+```bash
+git clone https://github.com/DuncanBentley/sievemin
+cd sievemin
+pip install -e ".[test]"          # adds pytest and music21
+python -m pytest                  # 127 tests
+python bench/reproduce.py         # benchmark and tolerant study, a few minutes
+python bench/reproduce.py --all   # adds the 1,000 random segments, 1 to 2 hours
+```
+
+`bench/reproduce.py` writes `bench/results.md` and `results.csv`, plus `bench/tolerant_study.md` and `tolerant_study.csv`. With `--all` it also writes `bench/random_segments.md` and `random_segments.csv`. The 100 random Xenakis-style sieves are in `bench/random_study.csv`. Seeds are fixed (2026), so the optimal values reproduce exactly. Runtimes depend on the machine. Mine is a Ryzen 9 8940HX laptop, where the 1,000-segment run took 1 hour 54 minutes.
+
+## What it guarantees
+
+| function | what it searches | what is proven |
+|---|---|---|
+| `minimize_union` | unions of residue classes, the form music21's `CompressionSegment` outputs | the fewest classes, the shortest string, or the smallest period, by exact ILP over every candidate class |
+| `minimize_dnf` | unions of terms `P & -(N1\|...\|Nk)`, the shape of Xenakis's published sieves | the smallest formula of that shape, for a given cap on k and, optionally, on the moduli |
+| `minimize_general` | formulas of any shape | the smallest formula there is, by exhaustive search, for domains of up to 14 points |
+| `minimize_union_tolerant` | a union of classes plus up to k notes added or removed | the smallest formula size + λ × exceptions |
+
+Size means leaves plus operators, so a union of n classes has size 2n - 1. Every result says whether the solver proved it optimal. I also ran every published result in this repo back through music21's own `Sieve` and checked it gives the same set.
+
+## Method
+
+Unions are an exact set cover, solved as an ILP with HiGHS through scipy. The candidate list is every residue class that stays inside the target, so the minimum is global. Terms with complement are enumerated per positive class, then another set cover picks the cheapest union. The any-shape search is dynamic programming over all subsets of up to 14 points. [REPORT.md](https://github.com/DuncanBentley/sievemin/blob/main/REPORT.md) has the details, the benchmarks and the prior-work notes.
+
+## Limits / what this does not show
+
+`minimize_dnf` is only optimal within its own shape. A formula nested differently can be shorter. With moduli up to 4, the major scale has a size 16 formula, and the best union of terms is 17. Only `minimize_general` covers every shape, and it runs out of room past 14 points.
+
+A result on a window only holds on that window, as with music21. If the formula has to hold on every integer, use `Domain.periodic(P)`. A window formula can use moduli no composer would pick, like `41@24`.
+
+Exact set cover is NP-hard. Most sets solve in milliseconds, but some 100-point windows take tens of seconds, and the slowest random segment took 248 s.
+
+The error-tolerant mode only works with unions, and its answer depends on the exception cost λ, which you choose. That it finds structure in Xenakis's sets is not evidence that he edited notes by hand.
+
+On music21's own 12 test segments the greedy is already optimal. The 1,000 random segments have no structure, so 22.4% is not what to expect on a real scale or rhythm.
+
+I haven't read *Formalized Music* or Xenakis 1990 directly. The published formulas come from music21's tests and the hmt library, and the value lists I generate match hmt's for Nomos Alpha, Psappha and À R.
+
+Whether a shorter formula is better music is not something this measures.
+
+## Upstream and sources
+
+- music21: <https://github.com/cuthbertLab/music21>. I studied version 10.5.2 ([release](https://github.com/cuthbertLab/music21/releases/tag/v10.5.2)), specifically [`music21/sieve.py`](https://github.com/cuthbertLab/music21/blob/v10.5.2/music21/sieve.py). Docs: <https://www.music21.org/music21docs/moduleReference/moduleSieve.html>.
+- hmt (Rohan Drape, Haskell), a second source for the published sieves: <https://github.com/rd--/hmt>.
+- Ariza, C. 2005. "The Xenakis Sieve as Object: A New Model and a Complete Implementation." *Computer Music Journal* 29(2). DOI 10.1162/0148926054094396. This is the model behind music21's sieve.
+- Xenakis, I. 1990. "Sieves." *Perspectives of New Music* 28(1): <https://doi.org/10.2307/833343>.
+- Bliznets, Nederlof and Szilágyi, "Parameterized Algorithms for Covering by Arithmetic Progressions": <https://arxiv.org/abs/2312.06393>.
+
+No external data is downloaded. The published sieve definitions are re-typed from music21's tests and hmt, and the random sets come from fixed seeds.
+
+## Status of upstream reports
+
+| Report | Status |
+|---|---|
+| music21: crash on `Sieve('3@1&-4@2')` (unbracketed intersection with a complemented class), one-line fix plus test | issue filed: [cuthbertLab/music21#2131](https://github.com/cuthbertLab/music21/issues/2131), fixed and merged in [#2135](https://github.com/cuthbertLab/music21/pull/2135) |
+| music21: opt-in exact compression, `CompressionSegment(..., method='exact')` | to be filed |
+
+## Citation
+
+See [CITATION.cff](https://github.com/DuncanBentley/sievemin/blob/main/CITATION.cff).
+
+```bibtex
+@software{bentley2026_sievemin,
+  author = {Bentley, Duncan},
+  title  = {sievemin: exact minimisation of Xenakis sieves},
+  year   = {2026},
+  url    = {https://github.com/DuncanBentley/sievemin},
+  doi    = {10.5281/zenodo.23816540}
+}
+```
+
+## License
+
+BSD-3-Clause, the same as music21. See [LICENSE](https://github.com/DuncanBentley/sievemin/blob/main/LICENSE). The repo contains no third-party data.
+
+## Acknowledgements
+
+Thanks to Michael Scott Cuthbert and the music21 contributors, whose `sieve.py` I tested against, to Christopher Ariza for the sieve model it implements, and to Rohan Drape for hmt.
+

sievemin-0.1.1/REPORT.md

@@ -0,0 +1,223 @@
+# Exact minimisation of Xenakis sieves
+
+Duncan Bentley, October 2026. Code in `src/sievemin`, 127 tests in `tests/`, benchmarks in `bench/`.
+
+## Summary
+
+music21's `CompressionSegment` turns a point set into a sieve with a greedy rule. It's fast and always correct, but nothing in it claims to find the shortest formula, and it only ever writes unions.
+
+I wrote `sievemin` to find formulas that are provably the shortest. For unions of residue classes (music21's own output form) the result is exact, with no extra bounds. For Xenakis-style unions of `P & -(N1|..|Nk)` terms it is exact within a cap on k and the moduli. For formulas of any shape it is exact on up to 14 points. Every formula in this report went back through music21's own `Sieve` and gave the right set.
+
+What I found:
+
+On music21's own 12 test segments the greedy is already optimal. Adding complement makes 2 of the 12 shorter.
+
+On bigger sets the greedy loses. With music21's own modulus limit on z = 0..99, Nomos Alpha goes from 8 classes to 7, Psappha from 20 to 15 and À R. from 17 to 14. Xenakis's own 20-class union for Nekuïa comes down to 8; music21 gets 11.
+
+Several published formulas aren't minimal, even keeping the composer's moduli. Nomos Alpha goes from size 23 to 21, Psappha (Flint's analysis) from 59 to 36 and À R. from 99 to 88. The major scale from Formalized Music p.197 goes from 18 to 16 with moduli up to 4, and to 10 if 12 is allowed.
+
+How much you gain depends on the material. On 100 random Xenakis-style sieves the size came down 11.4% on average against music21 (median 0%, max 63.6%). On 1,000 random segments of 5 to 100 points, which have no structure at all, the exact union used fewer classes on 928, 22.4% fewer on average. Structured material, which is what people actually compose with, gains less.
+
+There's also an error-tolerant mode: a formula plus up to k notes added or removed, solved exactly. It recovered a planted sieve with 1, 2 or 3 flipped notes in 100%, 96% and 95% of trials at exception cost 1.
+
+My verdict: a correct, small tool with an honest guarantee, and a reasonable thing to offer music21. It isn't a big research result. Covering a set with arithmetic progressions is a known NP-complete problem with known exact methods. What looks new is doing it for sieves with union, intersection and complement, and checking published formulas against the true minimum.
+
+## 1. What music21 does
+
+Source: music21 10.5.2, `music21/sieve.py`, `CompressionSegment._process` and `_find` (Ariza, 2003 and 2010).
+
+1. It takes a sorted point list and a window `z`. By default `z` is `range(min, max+1)`, and every point of `z` that isn't in the list must stay out.
+2. It takes the first uncovered point `n` and tries `m = 1, 2, 3, ...` while `m < len(z)`, so the largest modulus it can use is `len(z) - 1`. It keeps the first class `m@(n mod m)` whose points on `z` all lie in the set. The code checks against both "the remaining points" and "the whole set", but the first is a subset of the second, so only the second check matters.
+3. It removes the covered points and repeats until nothing is left. The output is a sorted union of single classes.
+
+So it's a "first point, smallest modulus" greedy, not even the usual best-coverage greedy for set cover. The docs make no claim about minimality, and the docstring says the result depends on `z`. It never writes intersections or complements. The other compression path, `_cmpIntersection`, only merges intersections it's given, using the Chinese remainder theorem. It tries every modulus from 1 up.
+
+I found a crash on the way. `Sieve('3@1&-4@2')` raises `ResidualException: complemented Residual objects cannot be intersected`, while `Sieve('(3@1&-4@2)')` works. `Sieve._initCompression` calls `_cmpIntersection()` and only catches `TypeError`, but `Residual.__and__` raises `ResidualException`. So any unbracketed formula that intersects a complemented class crashes the constructor. `sievemin.to_music21()` adds brackets to avoid it, and I have a one-line fix and a test ready, to be filed upstream.
+
+One edge case I saw in the code but didn't test: when you pass your own `z` and its first point is in the set but its last isn't, the loop `m < len(z)` may never find a class that isolates the first point, and music21 would raise `SieveException`.
+
+## 2. The problem and the cost
+
+The input is a target set `S` and a domain. The domain is either a window `z`, where the formula has to match exactly on `z` (music21's way), or a period `P`, where it has to match on every integer.
+
+Formulas are residue classes `m@r` joined with `|`, `&` and `-`. The cost is the size of the formula tree: leaves plus binary operators plus complements. A union of k classes costs 2k - 1, and `-(a|b)` costs 4. I report the class count (leaves) as well.
+
+### Unions of classes: `minimize_union`
+
+The candidates are every distinct non-empty class on the domain that lies inside `S`. On a window that means moduli 1 to span+1, since anything bigger only gives single points, which are already there. On a periodic domain it means every divisor of `P`. The candidate list is complete, so the minimum is global. I solve it as exact set cover with an ILP (HiGHS through scipy, gap 0).
+
+There are three objectives, each solved exactly on its own:
+- `leaves`: the fewest classes.
+- `chars`: the shortest music21 string.
+- `period`: the smallest lcm of the moduli. That's the smallest L where every target point sits in a class inside the target whose modulus divides L. On windows I search L up to 200,000; on periodic domains, the divisors of P.
+
+The solve runs in two stages. Stage one proves the primary optimum. Stage two breaks ties (fewer characters, then smaller moduli) with a 2 second limit, and `Result.bounds['tie_break_proven']` says whether it finished. Packing both into one weight was up to 10 times slower on some 100-point sets.
+
+### Unions of `P & -(N1|...|Nk)` terms: `minimize_dnf`
+
+`P` is a residue class, or nothing. If leaf moduli are capped at M, `P` is written as the cheapest intersection of leaves, so `11@2&13@2` stands for `143@2` when M = 13. This is the shape of Ariza's Nomos Alpha formula.
+
+For each `P`, I branch on its first point outside `S` and list every way to cover those outside points with at most k classes, keeping the cheapest cost for each resulting set. A weighted set cover ILP then picks the cheapest union. The search also tries the complement of `S` and wraps that answer in `-(...)`.
+
+This is optimal over every formula of this shape for the given k and M. It isn't optimal over every formula.
+
+### Any formula: `minimize_general`
+
+Dynamic programming over all 2^n subsets of the domain by increasing size, the standard way to find minimum Boolean formulas. It's exact over every formula tree, but it stops at 14 points, which fits one 12-note octave.
+
+### Modulus limits
+
+A modulus bigger than the window gives a class with one point in it, which is "compression" in name only. So every window result here uses music21's own limit, m up to len(z) - 1, and the solver never uses a modulus music21 couldn't. Periodic results only use divisors of the period.
+
+I also tried the stricter limit m up to len(z)/2. It's often impossible: 4 of music21's 12 test segments, including `[3,4,5,6,7,8,13,19]`, can't be written as a union at all under it. Some point lies in no class of that size that stays inside the set. Where it works, the minimum only goes up a little (Nomos Alpha 7 to 8, Nekuïa 8 to 9).
+
+### Checks
+
+The tests check the union solver against brute force on 40 random small windows. They also check general ≤ dnf ≤ union on 40 random periodic sets, and that the smallest period is really minimal on 20 random windows. They check that my Nomos Alpha values match the list hmt publishes. Every benchmark formula was run back through music21.
+
+## 3. Results
+
+Full tables are in `bench/results.md`. Sizes count leaves plus operators. "Same moduli" means leaf moduli no bigger than the largest one in the published formula, with at most 4 complemented classes per term. HiGHS proved every result here optimal.
+
+### Published sieves, periodic (must match on every integer)
+
+| sieve (source) | written size | exact, same moduli | exact, any modulus | exact, any shape |
+|---|---|---|---|---|
+| Major scale, FM p.197 (music21, hmt) | 18 | 17 as terms; 16 any shape, moduli ≤ 4 | 10 | 10 |
+| Nomos Alpha (music21 testSieve, hmt) | 23 | 21 | 21 | n/a |
+| Psappha, after Flint (music21, hmt) | 59 | 36 | 23 | n/a |
+| Jonchaies (hmt; Exarchos p.72) | 15 | 15 | 15 | n/a |
+| À R., after Squibbs 1996 (hmt) | 99 | 88 | 57 | n/a |
+
+The shortest Nomos Alpha with Xenakis's own moduli is `11@2&-(13@3|13@5|13@7)|13@0|13@1|13@6|13@9&-(11@4|11@8)`. It leaves 13@9 out of the first complement, because 13@9 is covered by another term anyway.
+
+The shortest major scale with moduli up to 4 is `-(4@0&3@2|3@0&(4@2|4@3)|3@1&(4@1|4@2))`, size 16. The best union of terms is 17, which is how I know the term shape isn't always optimal.
+
+Jonchaies is already minimal. Its period is 17, a prime, so there's nothing to factor.
+
+### Three ways to measure "short", window z = 0..99, music21's modulus limit
+
+Each exact number is the optimum for that measure on its own.
+
+| set | classes, music21 / exact (with limit len(z)/2) | characters, music21 / exact | period, music21 / exact |
+|---|---|---|---|
+| `[3,4,5,6,7,8,13,19]` (music21 docstring) | 6 / 6 (impossible) | 25 / 25 | 27,720 / 16 |
+| Nomos Alpha | 8 / 7 (8) | 42 / 36 | 4,165,408 / 198 |
+| Psappha | 20 / 15 (15) | 107 / 77 | 5,426,400 / 40 |
+| Jonchaies | 8 / 8 (8) | 42 / 42 | 17 / 17 |
+| À R. | 17 / 14 (14) | 93 / 75 | 4.45 × 10^14 / 88 |
+| Nekuïa (window 0..48) | 11 / 8 (9) | 57 / 40 | 203,490 / 48 |
+| Major scale | 6 / 6 (6) | 28 / 28 | 12 / 12 |
+
+For the docstring example, music21 gives `6@1|7@6|8@5|9@4|10@3|11@8`, and 6 classes is the true minimum. The shortest string is also 25 characters (for example `6@1|7@6|8@5|9@4|11@8|16@3`). The smallest period is 16, which still takes 6 classes but 28 characters: `8@5|16@3|16@4|16@6|16@7|16@8`. The three measures disagree, so I report all three.
+
+Period is where the greedy looks worst. It grabs whatever modulus fits first, so the lcm runs into the millions where 40 would do.
+
+### music21's greedy against the exact minimum, window semantics
+
+| set | points | music21 classes | exact classes | music21 size | exact size with & and - |
+|---|---|---|---|---|---|
+| 12 music21 test segments | 3 to 17 | same as exact on all 12 | | | shorter on 2 of 12, e.g. `[0,2,4,5,7,9,11,12]`: 7 down to 6 with `-(7@1|7@3|7@6)` |
+| testSieve 1 on z = 0..99 | 91 | 4 | 4 | 7 | 2 (`-12@2`) |
+| Nomos Alpha, z = 0..99 | 32 | 8 | 7 | 15 | 13 |
+| Psappha, z = 0..99 | 68 | 20 | 15 | 39 | 23 |
+| À R., z = 0..99 | 49 | 17 | 14 | 33 | 27 |
+| Nekuïa, Xenakis's 20-class union, on its window | 24 | 11 | 8 | 21 | 15 |
+
+### 1,000 random segments
+
+Each segment has k points (k drawn from 5 to 100) taken from 0..S, with S drawn from k to 2k, always including 0 and S. So music21's default window is 0..S and between half and all of it is filled. Seed 2026, music21's own modulus limit, and every formula checked by music21 (`bench/random_segments.md`).
+
+| measure | music21 mean | exact mean | sets where exact is smaller | mean reduction | max reduction |
+|---|---|---|---|---|---|
+| classes | 18.4 | 13.7 | 928 of 1,000 | 22.4% | 40.5% |
+| characters | 96.7 | 70.6 | 931 of 1,000 | 23.1% | 42.1% |
+| period (median) | 21,162,960 | 70 | 996 of 1,000 | | |
+
+The measures fight each other. Optimising for the smallest period drives the median down to 70, but costs 34.5 classes on average against 13.7. Optimising for classes or characters leaves the period in the tens of millions, about where music21 is.
+
+With the stricter limit len(z)/2, 58 of the 1,000 can't be written as a union at all. On the other 942 the minimum goes from 14.18 to 14.31 classes on average.
+
+For the 251 segments with span up to 40, I also ran the full algebra (k ≤ 2). It beat the best union on 180 of them. Mean size: music21 13.1, best union 10.8, with intersection and complement 8.0.
+
+These are the slowest cases. music21 takes 9 ms on average. The exact union averages 2.9 s, and the worst took 248 s, which is set cover being NP-hard. The whole run took 1 hour 54 minutes.
+
+### 100 random Xenakis-style sieves (z = 0..59, seed 2026)
+
+Each target is a random union of 2 to 4 terms, each `m@r` or `m@r & -(n@s|...)`, moduli 2 to 13.
+
+In unions only, music21 was beaten on 22 of 100, by 5.2% fewer classes on average (median 0%, max 40%). With intersection and complement (k ≤ 2) the exact formula was shorter than music21's on 37 of 100, by 11.4% on average (median 0%, max 63.6%). The exact answer was never longer than the formula that generated the set.
+
+### Every 5 to 7 note pitch-class set containing 0 (mod 12)
+
+That's 1,254 sets. Intersection and complement beat the best plain union on 432 of them. Mean size is 7.32 for unions and 6.89 with terms.
+
+### Formula plus exceptions: `minimize_union_tolerant`
+
+Find a union of classes F and at most k exceptions so that F, with those notes added or removed, equals the target. The cost is size(F) + λ × exceptions. It's one exact ILP (`src/sievemin/tolerant.py`): a binary variable per class and per exception, a constraint per target point (covered, or added), a constraint per non-target point a chosen class touches (so it must be removed), and the edit budget.
+
+λ is a choice. At λ = 2 an exception costs the same as one more single-point class, so the cost can never come out higher than the exact formula's, but adding a note never strictly pays. At λ = 1 an exception is a bit cheaper than a class.
+
+To test it I planted a random irredundant union of 2 or 3 classes (moduli 2 to 12) on z = 0..59, flipped e random notes, and ran the solver with k = e. That's 150 trials per cell, seed 2026 (`bench/tolerant_study.md`):
+
+| λ | 1 flip | 2 flips | 3 flips |
+|---|---|---|---|
+| 1 | 100% | 96% | 95% |
+| 2 | 100% | 77% | 49% |
+| 3 | 28% | 13% | 3% |
+
+All 1,350 runs were proven optimal. Every miss was a case where some other formula plus exceptions was strictly cheaper than the planted one. The planted sieve just wasn't the shortest explanation at that λ, so no solver could have picked it. There were no ties and no search failures. Without exceptions the noise is expensive: the exact formula for the noisy set averages size 7.0, 8.7 and 11.0 for 1, 2 and 3 flips, against 4.0 for the planted sieve.
+
+I couldn't get real Xenakis score passages legitimately. The music21 corpus has none, and the scores are under copyright. As a stand-in, I ran the published sets through it (periodic, λ = 1). In unions only, Nomos Alpha drops from cost 35 to 21 with 2 exceptions, removing 48 and 74, which are exactly the points Xenakis's complement terms take out. The major scale becomes `3@2|4@0` with 3 exceptions. That's the mode finding structure. It isn't evidence that Xenakis edited notes by hand; that idea is plausible, but I've no source for it.
+
+### Speed
+
+Periodic cases take 2 to 25 ms. Window cases on z = 0..99 take up to about 2 s (Psappha unions, around 3,000 candidate classes). Random 100-point windows can take tens of seconds, because exact set cover is NP-hard. The full benchmark runs in about 1.5 minutes on my laptop (Ryzen 9 8940HX).
+
+## 4. Limits
+
+`minimize_dnf` is optimal within its shape, for the k and M you give it. Other shapes like `(A|B)&(C|D)` can be shorter with capped moduli. The major scale (16 against 17) is a real example. Only `minimize_general` covers every shape, and only up to 14 points.
+
+Window results depend on `z`, the same as music21's. A window formula can use moduli Xenakis would never pick, like `41@24`. The periodic results are the musically meaningful ones.
+
+Generating terms is exponential in k. There's a cap (2 million terms by default) that raises `OverflowError` rather than quietly returning something non-optimal.
+
+The error-tolerant mode only does unions, and its answer depends on λ. On a periodic domain, an exception is a whole residue mod P, so a pitch class in every octave.
+
+Sources: the published formulas come from music21's tests and the hmt Haskell library (hmt-0.16). For the major scale, Nomos Alpha and Psappha, both give the same formula. I haven't read Formalized Music or Xenakis 1990 directly. The sets my code produces match the value lists hmt publishes for Nomos Alpha (32 values), Psappha (27) and À R. (42).
+
+Not benchmarked: Akea, Mists, Keqrops and the period-88 Nekuïa from Exarchos's thesis. Their formulas are only in images or badly scanned text.
+
+## 5. Prior work
+
+A web search found the sources below. I trust what I found on music21 and hmt most, then Exarchos (I read part 1 of the thesis as extracted text). I trust it least on Ariza 2005, Xenakis 1990, Gibson and Andreatta, which are paywalled; I only saw snippets.
+
+Ariza 2005, Computer Music Journal 29(2), "The Xenakis Sieve as Object", is the model behind music21. Its compression is the greedy described above, and I saw no claim that it's minimal.
+
+Xenakis's own analysis method, from "Sieves" (Perspectives of New Music 28/1, 1990), is described in Exarchos's 2007 Goldsmiths PhD (sections 5.3 and 5.7). It's also greedy. For each point it takes the smallest modulus whose later points stay inside the sieve and that covers a new point. The 1990 final stage adds a rule against "parasitical" points. It works on bounded modules (a start point and a repeat count), not plain residue classes. Exarchos calls Akea's 16-module form "minimal" in the sense that no module is redundant.
+
+hmt (Rohan Drape, Haskell) evaluates, reduces and normalises sieves. It doesn't search for a sieve from a set.
+
+Noll, Andreatta and Agon's tone-sieve analysis, Squibbs 1996 and Gibson are analysis and theory. I found no minimiser in any of them.
+
+The maths is known. Covering a set with arithmetic progressions, and the exact version, are NP-complete (Heath 1990). Bliznets, Nederlof and Szilágyi (arXiv 2312.06393) give parameterised exact algorithms. So an exact union-only minimum is a familiar problem, and ILP is the standard tool for it.
+
+What seems to be new (I found nothing that already does it, but my search wasn't exhaustive):
+
+1. A provably optimal minimiser for sieves using union, intersection and complement, with a stated cost.
+2. An exhaustive any-shape minimum for small periods.
+3. Exact formula-plus-exceptions fitting with a stated cost, plus a recovery study.
+4. Measured evidence that music21's greedy and several published formulas aren't minimal.
+5. The music21 crash on complemented intersections.
+
+## 6. Offering it to music21
+
+The crash fix is ready. It catches `ResidualException` in `Sieve._initCompression` and adds a test. It is reported upstream as [cuthbertLab/music21#2131](https://github.com/cuthbertLab/music21/issues/2131).
+
+For the feature, a proposal will be opened upstream. It would add an opt-in `CompressionSegment(..., method='exact')` that imports scipy only when asked. scipy is already in music21's optional `extras`, and `audioSearch` already imports scipy the same way with a fallback, so it adds no new dependency. A pure-Python branch-and-bound with a size guard is the alternative. The default stays greedy.
+
+The rest (the term shape, the general search and the tolerant mode) stays in this package. It's more than music21's core needs.
+
+## 7. Reproducing
+
+`python bench/reproduce.py` regenerates `bench/results.md` and the tolerant study in a few minutes. `--all` adds the 1,000-segment run, about 2 hours. CI runs the tests on Ubuntu and Windows with Python 3.10, 3.12 and 3.14 (`.github/workflows/ci.yml`).