sievemin 0.1.1__py3-none-any.whl

sievemin/__init__.py

@@ -0,0 +1,7 @@
+"""sievemin: exact minimisation of Xenakis sieves."""
+from .formula import Domain, parse, to_str, to_music21, evaluate, size, leaves, operators
+from .solve import (Result, min_period, minimize, minimize_union, minimize_dnf,
+                    minimize_general, factor_groups)
+
+__version__ = '0.1.1'
+from .tolerant import TolerantResult, minimize_union_tolerant

sievemin/cli.py

@@ -0,0 +1,55 @@
+"""Command line: ``sievemin 0 2 4 5 7 9 11 --period 12``."""
+from __future__ import annotations
+
+import argparse
+
+from .formula import Domain, parse, evaluate, to_music21
+from .solve import minimize
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description='Exact minimum Xenakis sieve for a set of integers.')
+    ap.add_argument('points', nargs='*', type=int, help='the integers in the set')
+    ap.add_argument('--sieve', help='take the set from this sieve formula instead')
+    ap.add_argument('--period', type=int, help='match on all integers with this period')
+    ap.add_argument('--z', nargs=2, type=int, metavar=('LO', 'HI'),
+                    help='match on the window LO..HI (default: min..max of the points)')
+    ap.add_argument('--language', choices=['union', 'dnf', 'general'], default='dnf')
+    ap.add_argument('--max-modulus', type=int, help='cap every leaf modulus')
+    ap.add_argument('--max-neg', type=int, default=2,
+                    help='dnf: most complemented classes per term (default 2)')
+    ap.add_argument('--max-edits', type=int, default=0,
+                    help='allow up to this many point exceptions (union language)')
+    ap.add_argument('--edit-cost', type=float, default=1,
+                    help='cost of one exception in formula-size units (default 1)')
+    a = ap.parse_args(argv)
+
+    if a.period:
+        dom = Domain.periodic(a.period)
+    elif a.z:
+        dom = Domain.window(range(a.z[0], a.z[1] + 1))
+    elif a.points:
+        dom = Domain.window(range(min(a.points), max(a.points) + 1))
+    else:
+        ap.error('give --z or --period with --sieve')
+    target = evaluate(parse(a.sieve), dom) if a.sieve else dom.mask(a.points)
+
+    if a.max_edits:
+        from .tolerant import minimize_union_tolerant
+        r = minimize_union_tolerant(target, dom, max_edits=a.max_edits,
+                                    edit_cost=a.edit_cost, max_modulus=a.max_modulus)
+        print(r)
+        print(f'cost {r.cost:g} = size {r.size} + {a.edit_cost:g} x {r.edits} exceptions; '
+              f'optimal: {r.optimal}; {r.runtime * 1e3:.0f} ms; domain {dom!r}')
+        return
+    kw = {'max_modulus': a.max_modulus}
+    if a.language == 'dnf':
+        kw['max_neg'] = a.max_neg
+    r = minimize(target, dom, a.language, **kw)
+    print(to_music21(r.formula))
+    print(f'size {r.size} (leaves {r.leaves}, operators {r.operators}); '
+          f'optimal: {r.optimal}; {r.runtime * 1e3:.0f} ms; domain {dom!r}')
+
+
+if __name__ == '__main__':
+    main()

sievemin/formula.py

@@ -0,0 +1,254 @@
+"""Sieve formulas: parse, print, evaluate and cost.
+
+A formula is a small tree of tuples:
+
+    ('r', m, r)            residue class m@r  (all n with n % m == r)
+    ('-', child)           complement
+    ('&', (c1, c2, ...))   intersection
+    ('|', (c1, c2, ...))   union
+
+The string syntax is music21's: ``-`` complement, ``&`` intersection,
+``|`` union, with brackets ``() [] {}``. Precedence is ``-`` then ``&``
+then ``|``. A bare modulus ``m`` means ``m@0``.
+
+Cost (the number we minimise) is the formula *size*:
+leaves + binary operators + complements. An n-ary ``&``/``|`` with k
+children counts as k - 1 binary operators. ``leaves`` is also reported.
+"""
+from __future__ import annotations
+
+import re
+
+__all__ = ['parse', 'to_str', 'to_music21', 'evaluate', 'size', 'leaves', 'operators',
+           'moduli', 'Domain']
+
+
+class Domain:
+    """The integer points a formula must reproduce exactly.
+
+    ``Domain.window(z)`` is music21's semantics: the formula must match the
+    target on the points of ``z`` and nothing is said about points outside.
+    ``Domain.periodic(P)`` means the formula must match on all integers,
+    which for sieves built from moduli dividing ``P`` is the same as
+    matching on ``0..P-1``.
+    """
+
+    def __init__(self, points, period=None):
+        self.points = sorted(set(int(p) for p in points))
+        if not self.points:
+            raise ValueError('empty domain')
+        self.period = period
+        self.index = {p: i for i, p in enumerate(self.points)}
+        self.n = len(self.points)
+        self.full = (1 << self.n) - 1
+
+    @classmethod
+    def window(cls, z):
+        return cls(z)
+
+    @classmethod
+    def periodic(cls, period):
+        return cls(range(period), period=period)
+
+    @property
+    def span(self):
+        return self.points[-1] - self.points[0]
+
+    def mask(self, values):
+        """Bitmask of the given integers (they must lie in the domain)."""
+        out = 0
+        for v in values:
+            if self.period is not None:
+                v %= self.period
+            if v not in self.index:
+                raise ValueError(f'{v} is outside the domain')
+            out |= 1 << self.index[v]
+        return out
+
+    def values(self, mask):
+        return [p for i, p in enumerate(self.points) if mask >> i & 1]
+
+    @property
+    def contiguous(self):
+        return self.span + 1 == self.n
+
+    def class_mask(self, m, r):
+        r %= m
+        if self.contiguous:
+            # bit i is point lo + i; shift a stride-m comb to the first hit
+            stride = self._comb(m)
+            return (stride << ((r - self.points[0]) % m)) & self.full
+        out = 0
+        for i, p in enumerate(self.points):
+            if p % m == r:
+                out |= 1 << i
+        return out
+
+    def _comb(self, m):
+        cache = self.__dict__.setdefault('_combs', {})
+        if m not in cache:
+            c = 0
+            for i in range(0, self.n, m):
+                c |= 1 << i
+            cache[m] = c
+        return cache[m]
+
+    def __repr__(self):
+        if self.period is not None:
+            return f'Domain.periodic({self.period})'
+        return f'Domain.window({self.points[0]}..{self.points[-1]}, n={self.n})'
+
+
+# ---------------------------------------------------------------- parsing
+
+_TOKEN = re.compile(r'\s*(?:(\d+)\s*@\s*(-?\d+)|(\d+)|([-&|()\[\]{}]))')
+_OPEN = '([{'
+_CLOSE = ')]}'
+
+
+def _tokens(text):
+    pos, out = 0, []
+    text = text.strip()
+    while pos < len(text):
+        m = _TOKEN.match(text, pos)
+        if not m:
+            raise ValueError(f'cannot parse sieve at: {text[pos:]!r}')
+        if m.group(1):
+            out.append(('r', int(m.group(1)), int(m.group(2))))
+        elif m.group(3):
+            out.append(('r', int(m.group(3)), 0))
+        else:
+            out.append(m.group(4))
+        pos = m.end()
+    return out
+
+
+def parse(text: str):
+    """Parse a music21-style sieve string into a formula tree."""
+    toks = _tokens(text)
+    pos = 0
+
+    def peek():
+        return toks[pos] if pos < len(toks) else None
+
+    def take():
+        nonlocal pos
+        pos += 1
+        return toks[pos - 1]
+
+    def p_or():
+        kids = [p_and()]
+        while peek() == '|':
+            take()
+            kids.append(p_and())
+        return kids[0] if len(kids) == 1 else ('|', tuple(kids))
+
+    def p_and():
+        kids = [p_not()]
+        while peek() == '&':
+            take()
+            kids.append(p_not())
+        return kids[0] if len(kids) == 1 else ('&', tuple(kids))
+
+    def p_not():
+        if peek() == '-':
+            take()
+            return ('-', p_not())
+        return p_atom()
+
+    def p_atom():
+        t = take() if peek() is not None else None
+        if isinstance(t, tuple):
+            m, r = t[1], t[2]
+            if m < 1:
+                raise ValueError('modulus must be >= 1')
+            return ('r', m, r % m)
+        if t in _OPEN:
+            inner = p_or()
+            if take() != _CLOSE[_OPEN.index(t)]:
+                raise ValueError('unbalanced brackets')
+            return inner
+        raise ValueError(f'unexpected token {t!r}')
+
+    tree = p_or()
+    if pos != len(toks):
+        raise ValueError(f'trailing tokens: {toks[pos:]}')
+    return tree
+
+
+# --------------------------------------------------------------- printing
+
+def to_str(f) -> str:
+    """music21-compatible string for a formula tree."""
+    kind = f[0]
+    if kind == 'r':
+        return f'{f[1]}@{f[2]}'
+    if kind == '-':
+        inner = to_str(f[1])
+        return '-' + (inner if f[1][0] == 'r' else f'({inner})')
+    parts = []
+    for c in f[1]:
+        s = to_str(c)
+        if kind == '&' and c[0] == '|':
+            s = f'({s})'
+        parts.append(s)
+    return kind.join(parts)
+
+
+def to_music21(f) -> str:
+    """String that music21.sieve.Sieve accepts.
+
+    music21 10.5.2 crashes (ResidualException) on an unbracketed formula
+    that intersects a complemented class, e.g. ``3@1&-4@2``: its
+    ``_initCompression`` catches TypeError but the error raised is
+    ResidualException. Wrapping the whole formula in brackets sends it down
+    the other code path, which evaluates correctly.
+    """
+    s = to_str(f)
+    return f'({s})' if '-' in s else s
+
+
+# ------------------------------------------------------------- evaluation
+
+def evaluate(f, domain: Domain) -> int:
+    """Bitmask of the domain points the formula contains."""
+    kind = f[0]
+    if kind == 'r':
+        return domain.class_mask(f[1], f[2])
+    if kind == '-':
+        return domain.full & ~evaluate(f[1], domain)
+    masks = [evaluate(c, domain) for c in f[1]]
+    out = masks[0]
+    for m in masks[1:]:
+        out = out & m if kind == '&' else out | m
+    return out
+
+
+# ------------------------------------------------------------------ cost
+
+def leaves(f) -> int:
+    if f[0] == 'r':
+        return 1
+    if f[0] == '-':
+        return leaves(f[1])
+    return sum(leaves(c) for c in f[1])
+
+
+def operators(f) -> int:
+    if f[0] == 'r':
+        return 0
+    if f[0] == '-':
+        return 1 + operators(f[1])
+    return len(f[1]) - 1 + sum(operators(c) for c in f[1])
+
+
+def size(f) -> int:
+    return leaves(f) + operators(f)
+
+
+def moduli(f) -> list[int]:
+    if f[0] == 'r':
+        return [f[1]]
+    if f[0] == '-':
+        return moduli(f[1])
+    return [m for c in f[1] for m in moduli(c)]

sievemin/solve.py

@@ -0,0 +1,587 @@
+"""Exact sieve minimisers.
+
+Three formula languages, each solved to proven optimality:
+
+``minimize_union``    union of residue classes only (music21's output
+                      language). Exact minimum number of classes, found as
+                      an exact set cover (ILP, HiGHS via scipy). No bounds:
+                      every distinct class on the domain is a candidate.
+
+``minimize_dnf``      union of terms ``P & -(N1|...|Nk)`` where P is a
+                      residue class (written as an intersection of leaves if
+                      leaf moduli are capped) or absent, and k <= ``max_neg``.
+                      This is the shape of Xenakis's published sieves
+                      (e.g. Nomos Alpha). Optional top-level complement.
+                      Exact minimum size within the bounds (leaf modulus
+                      cap, k), again by weighted set cover over *all* terms
+                      of that shape.
+
+``minimize_general``  any formula of residue classes, ``-``, ``&``, ``|``.
+                      Exact minimum size by exhaustive dynamic programming
+                      over all 2^n subsets, so only for small domains
+                      (n <= ~14 points, e.g. one octave of a 12-tone scale).
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from itertools import product
+from math import gcd
+
+import numpy as np
+from scipy.optimize import milp, LinearConstraint, Bounds
+from scipy.sparse import csc_matrix
+
+from .formula import Domain, evaluate, size, leaves, operators, to_str, moduli
+
+__all__ = ['Result', 'min_period', 'minimize_union', 'minimize_dnf', 'minimize_general',
+           'minimize', 'factor_groups']
+
+
+@dataclass
+class Result:
+    formula: tuple
+    language: str
+    optimal: bool
+    runtime: float
+    candidates: int = 0
+    bounds: dict = field(default_factory=dict)
+    lower_bound: float | None = None
+
+    @property
+    def text(self):
+        return to_str(self.formula)
+
+    @property
+    def size(self):
+        return size(self.formula)
+
+    @property
+    def leaves(self):
+        return leaves(self.formula)
+
+    @property
+    def operators(self):
+        return operators(self.formula)
+
+    @property
+    def chars(self):
+        return len(self.text)
+
+    @property
+    def period(self):
+        from math import lcm
+        return lcm(*moduli(self.formula))
+
+    def __str__(self):
+        return self.text
+
+
+# ------------------------------------------------------------- helpers
+
+def _divisors(n):
+    return [d for d in range(1, n + 1) if n % d == 0]
+
+
+def _prime_powers(n):
+    out, p = [], 2
+    while p * p <= n:
+        if n % p == 0:
+            q = 1
+            while n % p == 0:
+                n //= p
+                q *= p
+            out.append(q)
+        p += 1
+    if n > 1:
+        out.append(n)
+    return out
+
+
+def factor_groups(d, max_modulus=None):
+    """Fewest moduli <= max_modulus whose lcm is d (None if impossible).
+
+    An intersection of classes m1@r1 & m2@r2 ... is one class with modulus
+    lcm(m1, m2, ...), so this is the cheapest way to write a class of
+    modulus d with capped leaf moduli.
+    """
+    if max_modulus is None or d <= max_modulus:
+        return [d]
+    pp = _prime_powers(d)
+    if any(q > max_modulus for q in pp):
+        return None
+    for k in range(2, len(pp) + 1):
+        for assign in product(range(k), repeat=len(pp)):
+            groups = [1] * k
+            for q, g in zip(pp, assign):
+                groups[g] *= q
+            if all(1 < g <= max_modulus for g in groups):
+                return sorted(groups)
+    return None
+
+
+def _class_formula(d, r, max_modulus=None):
+    groups = factor_groups(d, max_modulus)
+    lits = tuple(('r', g, r % g) for g in groups)
+    return lits[0] if len(lits) == 1 else ('&', lits)
+
+
+def _leaf_moduli(domain: Domain, max_modulus=None):
+    if domain.period is not None:
+        ms = _divisors(domain.period)
+    else:
+        ms = list(range(1, domain.span + 2))
+    if max_modulus is not None:
+        ms = [m for m in ms if m <= max_modulus]
+    return ms
+
+
+def _leaf_classes(domain, max_modulus=None, divides=None, shortest=False):
+    """Distinct non-empty class masks -> (m, r).
+
+    Keeps the smallest modulus for each mask, or with ``shortest`` the
+    shortest ``m@r`` string. With ``divides`` only moduli dividing that
+    number are used. Cached on the domain."""
+    cache = domain.__dict__.setdefault('_leafcache', {})
+    key = (max_modulus, divides, shortest)
+    if key in cache:
+        return cache[key]
+    out = {}
+    for m in _leaf_moduli(domain, max_modulus):
+        if divides is not None and divides % m:
+            continue
+        for r in range(m):
+            mk = domain.class_mask(m, r)
+            if not mk:
+                continue
+            old = out.get(mk)
+            if old is None or (shortest and len(f'{m}@{r}') < len(f'{old[0]}@{old[1]}')):
+                out[mk] = (m, r)
+    cache[key] = out
+    return out
+
+
+def _positive_classes(domain, max_modulus=None):
+    """Distinct class masks -> (cost_in_leaves, d, r) for the positive part."""
+    if domain.period is not None:
+        ds = _divisors(domain.period)
+    else:
+        ds = list(range(1, domain.span + 2))
+        if max_modulus is not None:
+            # classes with d > span are singletons; find the cheapest such d
+            best = None
+            for d in range(domain.span + 2, 100 * (domain.span + 2)):
+                g = factor_groups(d, max_modulus)
+                if g is not None and (best is None or len(g) < best[0]):
+                    best = (len(g), d)
+                    if len(g) <= 2:
+                        break
+            if best:
+                ds.append(best[1])
+    out = {}
+    for d in ds:
+        g = factor_groups(d, max_modulus)
+        if g is None:
+            continue
+        for r in range(d):
+            mk = domain.class_mask(d, r)
+            if not mk:
+                continue
+            key = (len(g), d, r)
+            if mk not in out or key < out[mk]:
+                out[mk] = key
+    return out
+
+
+def _bits(mask):
+    i = 0
+    while mask:
+        if mask & 1:
+            yield i
+        mask >>= 1
+        i += 1
+
+
+def _set_cover(target, columns, weights, secondary=None, tie_seconds=2.0):
+    """Exact set cover of the bits of ``target``, lexicographic objective.
+
+    Stage 1 minimises ``weights`` and proves optimality. If ``secondary`` is
+    given, stage 2 minimises it among covers with the same stage-1 cost,
+    under a time limit: the primary optimum is always proven, the tie-break
+    is best effort (``tie_proven`` says whether it was proven too).
+    Returns (chosen column indices, primary objective, proven, dual bound,
+    tie_proven).
+    """
+    sec = secondary or [0] * len(columns)
+    keep = _undominated(target, columns, weights, sec)
+    cols = [columns[j] for j in keep]
+    w = [weights[j] for j in keep]
+    chosen, obj, proven, bound = _ilp_cover(target, cols, w)
+    tie_proven = True
+    if secondary is not None:
+        s2 = [sec[j] for j in keep]
+        res = _ilp_cover(target, cols, s2, budget=(w, obj + 0.5),
+                         time_limit=tie_seconds)
+        if res is not None:
+            ch2, _, p2, _ = res
+            if sum(w[j] for j in ch2) <= obj + 0.5:
+                chosen, tie_proven = ch2, p2
+            else:
+                tie_proven = False
+        else:
+            tie_proven = False
+    return [keep[j] for j in chosen], obj, proven, bound, tie_proven
+
+
+def _undominated(target, columns, weights, secondary):
+    """Drop columns covered by another column no worse in both weights.
+
+    Exact: in any cover, such a column can be swapped for its dominator
+    without raising either cost. Ties are broken by index so exactly one of
+    two identical columns survives.
+    """
+    cols = [c & target for c in columns]
+    order = sorted(range(len(cols)),
+                   key=lambda j: (-bin(cols[j]).count('1'), weights[j], secondary[j], j))
+    kept = []
+    for j in order:
+        c, w, s = cols[j], weights[j], secondary[j]
+        if not any(c & ~cols[i] == 0 and weights[i] <= w and secondary[i] <= s
+                   for i in kept):
+            kept.append(j)
+    return sorted(kept)
+
+
+def _ilp_cover(target, columns, weights, budget=None, time_limit=None):
+    rows = {b: i for i, b in enumerate(_bits(target))}
+    ri, ci = [], []
+    for j, col in enumerate(columns):
+        for b in _bits(col & target):
+            ri.append(rows[b])
+            ci.append(j)
+    A = csc_matrix((np.ones(len(ri)), (ri, ci)), shape=(len(rows), len(columns)))
+    cons = [LinearConstraint(A, lb=1, ub=np.inf)]
+    if budget is not None:
+        bw, cap = budget
+        cons.append(LinearConstraint(np.asarray([bw], dtype=float), lb=-np.inf, ub=cap))
+    opts = {'mip_rel_gap': 0, 'presolve': True}
+    if time_limit is not None:
+        opts['time_limit'] = time_limit
+    res = milp(c=np.asarray(weights, dtype=float), constraints=cons,
+               integrality=np.ones(len(columns)), bounds=Bounds(0, 1), options=opts)
+    if res.x is None:
+        if budget is not None:
+            return None
+        raise RuntimeError(f'ILP failed: {res.message}')
+    chosen = [j for j, v in enumerate(res.x) if v > 0.5]
+    bound = getattr(res, 'mip_dual_bound', None)
+    proven = res.status == 0 and (bound is None or res.fun - bound < 1e-6)
+    return chosen, res.fun, proven, bound
+
+
+def _union(kids):
+    kids = tuple(kids)
+    return kids[0] if len(kids) == 1 else ('|', kids)
+
+
+def _check(formula, target, domain):
+    got = evaluate(formula, domain)
+    if got != target:
+        raise AssertionError(f'internal error: {to_str(formula)} does not match target')
+
+
+def _target(points, domain):
+    return domain.mask(points) if not isinstance(points, int) else points
+
+
+# ----------------------------------------------------- union of classes
+
+def _class_chars(m, r):
+    return len(f'{m}@{r}')
+
+
+PERIOD_LIMIT = 200_000
+
+
+def min_period(points, domain: Domain, max_modulus=None, limit=PERIOD_LIMIT):
+    """Smallest period (lcm of the moduli) of any union formula for the target.
+
+    L is achievable iff every target point lies in some class inside the
+    target whose modulus divides L (and is <= max_modulus). Searched for
+    L = 1..limit (periodic domains: divisors of the period, always found).
+    Returns None if no L <= limit works.
+    """
+    target = _target(points, domain)
+    ms = _leaf_moduli(domain, max_modulus)
+    cover = {}
+    for m in ms:  # points coverable by an in-target class of modulus m
+        c = 0
+        for r in range(m):
+            mk = domain.class_mask(m, r)
+            if mk and mk & ~target == 0:
+                c |= mk
+        if c:
+            cover[m] = c
+    if domain.period is not None:
+        Ls = _divisors(domain.period)
+    else:
+        Ls = range(1, limit + 1)
+    good = sorted(cover)
+    for L in Ls:
+        got = 0
+        for m in good:
+            if m > L:
+                break
+            if L % m == 0:
+                got |= cover[m]
+                if got == target:
+                    return L
+    return None
+
+
+def minimize_union(points, domain: Domain, max_modulus=None,
+                   objective='leaves') -> Result:
+    """Exact minimum union of residue classes equal to the target.
+
+    objective:
+      'leaves'  fewest classes (ties: fewest characters, then small moduli)
+      'chars'   shortest music21 string (ties: fewest classes)
+      'period'  smallest period, i.e. lcm of the moduli (then fewest classes)
+    """
+    t0 = time.perf_counter()
+    target = _target(points, domain)
+    if not target:
+        raise ValueError('empty target')
+    period = None
+    if objective == 'period':
+        period = min_period(target, domain, max_modulus)
+        if period is None:
+            raise ValueError(f'no union formula with period <= {PERIOD_LIMIT} '
+                             'within these bounds')
+    # dedupe by mask *after* restricting moduli to divisors of the period,
+    # or a class could be kept under a modulus that does not divide it
+    cls = {mk: mr for mk, mr in _leaf_classes(domain, max_modulus, divides=period,
+                                              shortest=objective == 'chars').items()
+           if mk & ~target == 0}
+    cols = list(cls)
+    if not cols or (target & ~_or(cols)):
+        raise ValueError('target cannot be written as a union of classes '
+                         'with these bounds')
+    chars = {c: _class_chars(*cls[c]) + 1 for c in cols}       # +1 for the '|'
+    m1 = max(mr[0] for mr in cls.values()) + 1
+    if objective == 'chars':
+        prim = [chars[c] for c in cols]
+        sec = [1 for c in cols]
+    elif objective in ('leaves', 'period'):
+        prim = [1 for c in cols]
+        sec = [chars[c] * m1 + cls[c][0] for c in cols]   # then fewest chars, small moduli
+    else:
+        raise ValueError(f'unknown objective {objective!r}')
+    chosen, obj, proven, bound, tie_ok = _set_cover(target, cols, prim, sec)
+    terms = sorted((cls[cols[j]] for j in chosen))
+    f = _union(('r', m, r) for m, r in terms)
+    _check(f, target, domain)
+    return Result(f, 'union', proven, time.perf_counter() - t0, len(cols),
+                  {'max_modulus': max_modulus, 'objective': objective,
+                   'tie_break_proven': tie_ok}, bound)
+
+
+def _or(masks):
+    out = 0
+    for m in masks:
+        out |= m
+    return out
+
+
+# ------------------------------------------------------------- DNF terms
+
+def _term_formula(pos, negs, max_modulus):
+    parts = []
+    if pos is not None:
+        _, d, r = pos
+        pf = _class_formula(d, r, max_modulus)
+        parts.extend(pf[1] if pf[0] == '&' else (pf,))
+    if negs:
+        parts.append(('-', _union(('r', m, r) for m, r in sorted(negs))))
+    return parts[0] if len(parts) == 1 else ('&', tuple(parts))
+
+
+def _dnf_terms(target, domain, max_modulus, max_neg, limit):
+    leafs = _leaf_classes(domain, max_modulus)
+    pos = _positive_classes(domain, max_modulus)
+    by_point = [[] for _ in range(domain.n)]
+    for mk, (m, r) in sorted(leafs.items(), key=lambda kv: kv[1]):
+        for b in _bits(mk):
+            by_point[b].append((mk, (m, r)))
+    full = domain.full
+    terms = {}  # mask -> (size, pos, negs)
+
+    def add(mask, p, negs):
+        lp = 0 if p is None else p[0]
+        k = len(negs)
+        sz = (2 * lp - 1 if lp else 0) + (2 * k if k else 0) + (1 if lp and k else 0)
+        old = terms.get(mask)
+        if old is None or sz < old[0]:
+            terms[mask] = (sz, p, tuple(negs))
+            if len(terms) > limit:
+                raise OverflowError
+
+    def grow(P, cur, bad, negs, p):
+        if not bad:
+            add(cur, p, negs)
+            return
+        if len(negs) == max_neg:
+            return
+        b = (bad & -bad).bit_length() - 1
+        seen = set()
+        for nm, mr in by_point[b]:
+            rel = nm & P
+            if rel in seen:
+                continue
+            seen.add(rel)
+            new = cur & ~nm
+            if not new & target:
+                continue
+            grow(P, new, bad & ~nm, negs + [mr], p)
+
+    starts = [(full, None)] + [(mk, key) for mk, key in pos.items() if mk & target]
+    for P, p in starts:
+        bad = P & ~target
+        if p is None and not bad:
+            continue  # the target is everything; handled by caller
+        grow(P, P, bad, [], p)
+    return terms
+
+
+def minimize_dnf(points, domain: Domain, max_modulus=None, max_neg=2,
+                 complement=True, limit=2_000_000) -> Result:
+    """Smallest union of ``P & -(N1|..|Nk)`` terms (k <= max_neg).
+
+    Optimal over all such formulas whose leaf moduli are <= ``max_modulus``
+    (None = no cap). With ``complement`` the whole formula may also be
+    ``-(...)`` of such a union for the complement set; the cheaper wins.
+    """
+    t0 = time.perf_counter()
+    target = _target(points, domain)
+    if not target:
+        raise ValueError('empty target')
+    if target == domain.full:
+        return Result(('r', 1, 0), 'dnf', True, time.perf_counter() - t0, 1,
+                      {'max_modulus': max_modulus, 'max_neg': max_neg,
+                       'complement': complement})
+    best, ncand, proven_all = None, 0, True
+    jobs = [(target, False)]
+    if complement:
+        jobs.append((domain.full & ~target, True))
+    for tg, neg in jobs:
+        terms = _dnf_terms(tg, domain, max_modulus, max_neg, limit)
+        ncand += len(terms)
+        cols = list(terms)
+        if tg & ~_or(cols):
+            continue
+        # size first; ties: fewer complemented classes
+        w = [terms[c][0] + 1 for c in cols]
+        chosen, obj, proven, _, _ = _set_cover(tg, cols, w)
+        proven_all &= proven
+        f = _union(_term_formula(terms[cols[j]][1], terms[cols[j]][2], max_modulus)
+                   for j in sorted(chosen, key=lambda j: (terms[cols[j]][1] or (0, 0, 0),
+                                                          terms[cols[j]][2])))
+        if neg:
+            f = ('-', f)
+        if best is None or (size(f), leaves(f)) < (size(best), leaves(best)):
+            best = f
+    if best is None:
+        raise ValueError('no formula within these bounds')
+    _check(best, target, domain)
+    return Result(best, 'dnf', proven_all, time.perf_counter() - t0, ncand,
+                  {'max_modulus': max_modulus, 'max_neg': max_neg,
+                   'complement': complement})
+
+
+# ---------------------------------------------------- general formulas
+
+def minimize_general(points, domain: Domain, max_modulus=None, max_points=14,
+                     max_size=40) -> Result:
+    """Smallest formula of any shape (``-``, ``&``, ``|`` over classes).
+
+    Dynamic programming over every subset of the domain by increasing size,
+    the classic way to find minimum Boolean formulas. Exact, but needs
+    2^n memory and time, so the domain is capped at ``max_points``.
+    """
+    t0 = time.perf_counter()
+    target = _target(points, domain)
+    n = domain.n
+    if n > max_points:
+        raise ValueError(f'domain has {n} points; general search is capped at {max_points}')
+    N = 1 << n
+    full = N - 1
+    INF = 255
+    cost = np.full(N, INF, dtype=np.uint8)
+    op = np.zeros(N, dtype=np.uint8)        # 0 leaf, 1 not, 2 and, 3 or
+    left = np.zeros(N, dtype=np.int64)
+    right = np.zeros(N, dtype=np.int64)
+    leaf_of = {}
+    for mk, (m, r) in _leaf_classes(domain, max_modulus).items():
+        cost[mk] = 1
+        leaf_of[mk] = (m, r)
+    # the empty set and the full set are expressible (m@r & -m@r) but are
+    # never useful as sub-formulas of a minimum formula for a proper target
+    levels = {1: np.array(sorted(leaf_of), dtype=np.int64)}
+    c = 1
+    while cost[target] == INF:
+        c += 1
+        if c > max_size:
+            raise ValueError('no formula found within max_size')
+        new = []
+        prev = levels.get(c - 1)
+        if prev is not None and len(prev):
+            comp = full ^ prev
+            sel = cost[comp] > c
+            idx = comp[sel]
+            cost[idx] = c
+            op[idx] = 1
+            left[idx] = prev[sel]
+            new.append(idx)
+        for i in range(1, (c - 1) // 2 + 1):
+            j = c - 1 - i
+            A, B = levels.get(i), levels.get(j)
+            if A is None or B is None or not len(A) or not len(B):
+                continue
+            for a in A:
+                for code, vals in ((2, a & B), (3, a | B)):
+                    sel = cost[vals] > c
+                    if not sel.any():
+                        continue
+                    idx = vals[sel]
+                    cost[idx] = c
+                    op[idx] = code
+                    left[idx] = a
+                    right[idx] = B[sel]
+                    new.append(idx)
+        levels[c] = np.unique(np.concatenate(new)) if new else np.array([], dtype=np.int64)
+
+    def build(mk):
+        o = op[mk]
+        if o == 0:
+            m, r = leaf_of[int(mk)]
+            return ('r', m, r)
+        if o == 1:
+            return ('-', build(left[mk]))
+        a, b = build(left[mk]), build(right[mk])
+        kind = '&' if o == 2 else '|'
+        kids = []
+        for x in (a, b):
+            kids.extend(x[1] if x[0] == kind else (x,))
+        return (kind, tuple(kids))
+
+    f = build(target)
+    _check(f, target, domain)
+    assert size(f) == c
+    return Result(f, 'general', True, time.perf_counter() - t0, int((cost < INF).sum()),
+                  {'max_modulus': max_modulus})
+
+
+def minimize(points, domain: Domain, language='dnf', **kw) -> Result:
+    fn = {'union': minimize_union, 'dnf': minimize_dnf,
+          'general': minimize_general}[language]
+    return fn(points, domain, **kw)

sievemin/tolerant.py

@@ -0,0 +1,152 @@
+"""Error-tolerant sieves: a formula plus a few point exceptions.
+
+Given a target set T, find a union of residue classes F and at most
+``max_edits`` exceptions such that
+
+    (F's points + added) - removed == T
+
+exactly, minimising the description length
+
+    cost = size(F) + edit_cost * (number of exceptions)
+
+where size(F) is the usual leaves + operators (2n - 1 for n classes).
+
+``edit_cost`` (lambda) is the price of one exception, in the same units as
+formula size. The default 1 makes an exception slightly cheaper than an
+extra singleton class in a union (a leaf plus a ``|`` = 2). In the synthetic
+study (bench/tolerant_study.md) lambda = 1 recovered a planted 2-3 class
+sieve from 1/2/3 flipped notes in 100/96/95% of trials; lambda = 2 in
+100/77/49% and lambda = 3 in 28/13/3%. With ``edit_cost = 2`` an exception
+is never cheaper than writing the point as its own class, so the cost can
+never be worse than the exact formula's size.
+
+Solved exactly as one ILP (HiGHS): binary x_c per candidate class, binary
+a_p per target point (exception: add p), binary d_q per non-target point
+(exception: remove q).
+
+    for p in T:      sum(x_c : p in c) + a_p >= 1
+    for q not in T:  d_q >= x_c            for every class c containing q
+    sum(a) + sum(d) <= max_edits
+
+Candidates are the classes (music21-style moduli, optionally capped) with at
+most ``max_edits`` points outside T: a class with more could never be used.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.optimize import milp, LinearConstraint, Bounds
+from scipy.sparse import coo_matrix
+
+from .formula import Domain, to_str, size
+from .solve import _leaf_classes, _bits, _target, _union, _divisors
+
+__all__ = ['TolerantResult', 'minimize_union_tolerant']
+
+
+@dataclass
+class TolerantResult:
+    formula: tuple
+    added: list            # points the formula misses (add them)
+    removed: list          # points the formula has but the target lacks
+    edit_cost: float
+    optimal: bool
+    runtime: float
+    candidates: int
+
+    @property
+    def text(self):
+        return to_str(self.formula)
+
+    @property
+    def size(self):
+        return size(self.formula)
+
+    @property
+    def edits(self):
+        return len(self.added) + len(self.removed)
+
+    @property
+    def cost(self):
+        return self.size + self.edit_cost * self.edits
+
+    def __str__(self):
+        parts = [self.text]
+        if self.added:
+            parts.append('add ' + ','.join(map(str, self.added)))
+        if self.removed:
+            parts.append('remove ' + ','.join(map(str, self.removed)))
+        return '  '.join(parts)
+
+
+def minimize_union_tolerant(points, domain: Domain, max_edits=1, edit_cost=1,
+                            max_modulus=None, time_limit=None) -> TolerantResult:
+    t0 = time.perf_counter()
+    target = _target(points, domain)
+    if not target:
+        raise ValueError('empty target')
+    outside = domain.full & ~target
+    cls = {mk: mr for mk, mr in _leaf_classes(domain, max_modulus).items()
+           if bin(mk & outside).count('1') <= max_edits}
+    cols = list(cls)
+    T = list(_bits(target))
+    O = sorted({b for c in cols for b in _bits(c & outside)})
+    nx, na, nd = len(cols), len(T), len(O)
+    ia = {b: nx + i for i, b in enumerate(T)}
+    idd = {b: nx + na + i for i, b in enumerate(O)}
+    nvar = nx + na + nd
+
+    rows, cols_i, vals, lb, ub = [], [], [], [], []
+    r = 0
+    cover = {b: [] for b in T}
+    for j, c in enumerate(cols):
+        for b in _bits(c & target):
+            cover[b].append(j)
+    for b in T:                                   # cover or add
+        for j in cover[b]:
+            rows.append(r); cols_i.append(j); vals.append(1)
+        rows.append(r); cols_i.append(ia[b]); vals.append(1)
+        lb.append(1); ub.append(np.inf); r += 1
+    for j, c in enumerate(cols):                  # outside point used => removed
+        for b in _bits(c & outside):
+            rows += [r, r]; cols_i += [idd[b], j]; vals += [1, -1]
+            lb.append(0); ub.append(np.inf); r += 1
+    for v in range(nx, nvar):                     # edit budget
+        rows.append(r); cols_i.append(v); vals.append(1)
+    lb.append(-np.inf); ub.append(max_edits); r += 1
+    for j in range(nx):                           # a formula has >= 1 class
+        rows.append(r); cols_i.append(j); vals.append(1)
+    lb.append(1); ub.append(np.inf); r += 1
+
+    A = coo_matrix((vals, (rows, cols_i)), shape=(r, nvar)).tocsr()
+    # objective: 2 per class (leaf + union op; the -1 for the first class is
+    # a constant), edit_cost per exception; tiny tie-break to small moduli
+    eps = 1e-4 / max(1, max(m for m, _ in cls.values()))
+    c = np.array([2 + eps * cls[col][0] for col in cols] + [edit_cost] * (na + nd), dtype=float)
+    opts = {'mip_rel_gap': 0, 'presolve': True}
+    if time_limit:
+        opts['time_limit'] = time_limit
+    res = milp(c=c, constraints=LinearConstraint(A, lb, ub),
+               integrality=np.ones(nvar), bounds=Bounds(0, 1), options=opts)
+    if res.x is None:
+        raise RuntimeError(f'ILP failed: {res.message}')
+    x = res.x > 0.5
+    chosen = sorted(cls[cols[j]] for j in range(nx) if x[j])
+    F_mask = 0
+    for j in range(nx):
+        if x[j]:
+            F_mask |= cols[j]
+    added = domain.values(target & ~F_mask)
+    removed = domain.values(F_mask & ~target)
+    if not chosen:
+        raise ValueError('every point became an exception; raise edit_cost')
+    f = _union(('r', m, rr) for m, rr in chosen)
+    # sanity: the edits reproduce the target exactly
+    assert (F_mask | domain.mask(added)) & ~domain.mask(removed) == target
+    assert len(added) + len(removed) <= max_edits
+    bound = getattr(res, 'mip_dual_bound', None)
+    proven = res.status == 0 and (bound is None or res.fun - bound < 1e-3)
+    return TolerantResult(f, added, removed, edit_cost, proven,
+                          time.perf_counter() - t0, nx)

sievemin-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+sievemin/__init__.py,sha256=h8YJ3N8Neah9ss1C77xzU0CQW2rselpajgVKPBZyfSE,362
+sievemin/cli.py,sha256=fqLZo_8edFkZw04hcyZFBXzHyrmrjYIPUHKypujnUq0,2511
+sievemin/formula.py,sha256=WaBNNcO1u_JiToJGArxuQBVeXOybLh3htqloSGxPYms,7333
+sievemin/solve.py,sha256=SFv_b_px21Mbk0bDJejhXI69Ik54QyEBwCwinP20LEs,20706
+sievemin/tolerant.py,sha256=yQB_IMaBSkCIVRdj91kHEngTeJNjkWA8arlKFxJaKCk,5954
+sievemin-0.1.1.dist-info/licenses/LICENSE,sha256=G-5vR3CvoLN8sM4rgj1B8v26McndLRwUG2GbFIRFCYo,1499
+sievemin-0.1.1.dist-info/METADATA,sha256=tDDX2TQr_vuV3a-Rgc0--AtS_8x6YNiHgzkUxtI7XAU,12660
+sievemin-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sievemin-0.1.1.dist-info/entry_points.txt,sha256=ECZBHq9nejqAx8hl3qexITtzFCtmGN60uhOeXBemq58,47
+sievemin-0.1.1.dist-info/top_level.txt,sha256=JvmAuaQeWLQ0VMeEY9nfub_ZihHaJUgY0jfDtdygMmY,9
+sievemin-0.1.1.dist-info/RECORD,,

sievemin-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sievemin-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sievemin = sievemin.cli:main

sievemin-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sievemin