subsequence.sequence_utils

The API reference for sieve and residual_class.

sieve

sieve(
    classes: typing.Sequence[typing.Tuple[int, int]],
    hi: int,
    lo: int = 0,
) -> typing.List[int]

Xenakis sieve: the sorted integers in [lo, hi) in any of the classes.

A sieve (Xenakis's crible) is a logical formula over residual classes that denotes a subset of the integers. This primary form takes a list of (modulus, residue) pairs and returns their union over a bounded range — every x in [lo, hi) with x % modulus == residue for at least one class. The integers index any ordered parameter, so one kernel builds custom scales (over 0–11 semitones), non-octave pitch pools, rhythm grids, and bar-selection masks.

For intersection and complement, compose residual_class objects with &, |, ~ and evaluate the result (see Sieve).

Parameters

• classes: (modulus, residue) pairs. modulus must be ≥ 1; the residue is taken modulo the modulus.
• hi: Exclusive upper bound.
• lo: Inclusive lower bound (default 0).

Returns

• typing.List[int]: The sorted, de-duplicated integers in range that satisfy any class.

Raises

• ValueError: If a modulus is below 1.

Example

sieve([(12, 0), (12, 2), (12, 4), (12, 5), (12, 7), (12, 9), (12, 11)], hi=12)
# → [0, 2, 4, 5, 7, 9, 11]  — the major scale as a sieve
sieve([(2, 0)], hi=12)          # → [0, 2, 4, 6, 8, 10]  — whole-tone
sieve([(5, 0), (7, 1)], lo=60, hi=96)   # a non-octave pitch pool

residual_class

residual_class(modulus: int, residue: int) -> Sieve

A single residual class {x : x % modulus == residue} as a Sieve.

The atom of sieve algebra (Xenakis's notation modulus @ residue). Combine with & | ~ and call Sieve.evaluate.