zero-sum-sequences 0.1.0__tar.gz

zero_sum_sequences-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+__pycache__/
+*.py[cod]
+.ipynb_checkpoints/
+.DS_Store

zero_sum_sequences-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Hackl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zero_sum_sequences-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: zero-sum-sequences
+Version: 0.1.0
+Summary: Computations with additive and zero-sum sequences
+Project-URL: Repository, https://github.com/behackl/zero-sum-sequences
+Author: Benjamin Hackl
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: networkx>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Provides-Extra: sage
+Requires-Dist: sagelite[gap]==10.9.post1; extra == 'sage'
+Provides-Extra: tutorial
+Requires-Dist: ipykernel>=6.29; extra == 'tutorial'
+Requires-Dist: matplotlib>=3.8; extra == 'tutorial'
+Requires-Dist: nbconvert>=7.16; extra == 'tutorial'
+Description-Content-Type: text/markdown
+
+# Zero-sum sequences
+
+`zero-sum-sequences` provides immutable finite additive sequences and tools for
+enumerating their factorizations into minimal zero-sum sequences. The runtime
+is ordinary Python with NetworkX; SageMath is supported as an optional source
+of additive parents, but is not required.
+
+The package keeps group-specific mathematics explicit. Callers configure the
+ambient parent and provide an upper bound for its Davenport constant; the
+package does not infer structural invariants from the parent.
+
+## Installation
+
+Install the latest release from PyPI into Python 3.12 or newer:
+
+```console
+python -m pip install zero-sum-sequences
+```
+
+The optional `sage` extra installs the `sagelite` runtime on supported
+platforms:
+
+```console
+python -m pip install "zero-sum-sequences[sage]"
+```
+
+For a reproducible development environment using the committed `uv.lock`,
+clone the repository and run:
+
+```console
+uv sync --extra dev
+uv run python -m pytest
+```
+
+Alternatively, install the package and its test tools with `pip`:
+
+```console
+python -m pip install -e '.[dev]'
+python -m pytest
+```
+
+To include the Sage integration tests, use `uv sync --extra dev --extra sage`
+or install the editable `.[dev,sage]` extra.
+
+## Tutorial
+
+[![Launch the tutorial on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/behackl/zero-sum-sequences/main?urlpath=lab/tree/notebooks/tutorial.ipynb)
+
+The executable [tutorial](https://github.com/behackl/zero-sum-sequences/blob/main/notebooks/tutorial.ipynb) introduces the public API
+with small hand-checkable examples in ordinary Python.
+Its execution dependencies are available through
+`uv sync --extra tutorial` or the corresponding `pip` extra.
+
+## Additive sequences
+
+Configure an ambient parent and a Davenport upper bound once, then use the
+resulting callable space to construct sequences. `FiniteAdditiveGroup` is a
+small convenience adapter for groups represented by ordinary Python values:
+
+```python
+from zero_sum_sequences import AdditiveSequenceSpace, FiniteAdditiveGroup
+
+group = FiniteAdditiveGroup(
+    range(3),
+    zero=0,
+    add=lambda left, right: (left + right) % 3,
+    coerce=lambda value: int(value) % 3,
+)
+Sequences = AdditiveSequenceSpace(group, davenport_bound=3)
+
+sequence = Sequences([1, 1, 2, 2])
+sequence.is_zero_sum()  # True
+sequence.is_atom()      # False: 1 * 2 is a proper zero-sum subsequence
+sequence.multiplicities
+```
+
+Existing algebra systems can be used directly. A compatible parent is
+callable for coercion and provides `zero()`; its elements must be hashable and
+mutually orderable. Elements may implement `+`, or the parent may provide
+`add(left, right)`. Exhaustive catalogue enumeration additionally requires the
+parent to be finite, iterable, and to provide `is_finite()`.
+
+A sequence is immutable and hashable. Addition combines multisets,
+subtraction removes a subsequence, and multiplication by a non-negative
+integer repeats a sequence. Arithmetic preserves the sequence space, and the
+empty sequence retains the base parent and its zero element.
+`sequence.map_terms(mapping)` applies a map to every term and reconstructs the
+result as a canonical multiset; pass `target_space=` when the image belongs to
+a different sequence space.
+
+The configured bound must not be smaller than the actual Davenport constant
+when complete atom or factorization results are required.
+
+## Factorizations
+
+The factorization engine indexes relevant atom divisors as sparse
+multiplicity vectors and merges equal remainders in a directed acyclic graph.
+Attained lengths are represented internally as integer bitsets.
+
+```python
+lengths = sequence.length_set()
+witnesses = sequence.factorization_witnesses()
+factorizations = list(sequence.factorizations())
+graph = sequence.factorization_digraph()
+```
+
+`factorization_witnesses()` retains one factorization for every attained
+length. Exhaustive `factorizations()` is necessarily output-sensitive, but it
+emits each unordered factorization once. `factorization_digraph()` returns a
+NetworkX `DiGraph` whose vertices are remainder sequences and whose edges
+store the removed atom in their `"atom"` attribute.
+
+For several queries against the same remainder DAG, use the public solver:
+
+```python
+from zero_sum_sequences import FactorizationSolver
+
+solver = FactorizationSolver(sequence)
+solver.length_set()
+solver.factorization_witnesses()
+solver.statistics
+solver.digraph()
+```
+
+A complete precomputed catalogue can avoid rediscovering atoms:
+
+```python
+from zero_sum_sequences import AtomCatalogue, FactorizationSolver
+
+catalogue = AtomCatalogue(Sequences, atoms)
+solver = FactorizationSolver(sequence, atom_catalogue=catalogue)
+```
+
+For a small finite parent, a complete reduced catalogue can instead be
+generated exhaustively through the configured Davenport bound:
+
+```python
+catalogue = Sequences.enumerate_atom_catalogue()
+```
+
+The parent must be a finite iterable additive group. Enumeration completes
+each sorted prefix with its uniquely determined final term, rather than
+testing multisets whose sum is nonzero. Completeness depends on the configured
+Davenport bound being valid.
+
+The caller is responsible for catalogue completeness. A catalogue used for a
+complete result must contain every atom divisor relevant to the input.
+
+Factorizations are computed in the reduced block monoid: identity terms are
+not accepted by the solver and are not stored in an `AtomCatalogue`.
+
+## Automorphism orbits
+
+Group automorphisms act on sequences term by term. Because an
+`AdditiveSequence` is a multiset, the induced action automatically disregards
+the order of its terms. The package can materialize an orbit, test orbit
+membership, and return a shortest deterministic word in the configured
+automorphism generators.
+
+The convenience constructor for a product of cyclic groups configures the
+coordinate group and generators of its full automorphism group together. For
+example, the eight maximal-length atoms over $C_2\oplus C_4$ form one orbit:
+
+```python
+G = FiniteAdditiveGroup.cyclic_product(2, 4)
+C2xC4 = AdditiveSequenceSpace(G, davenport_bound=5)
+
+atom = C2xC4([(0, 1)] * 3 + [(1, 0), (1, 1)])
+other = C2xC4([(0, 1), (1, 0)] + [(1, 1)] * 3)
+
+len(atom.orbit())                         # 8
+atom.is_in_same_orbit(other)              # True
+witness = atom.orbit_witness(other)
+witness.show()
+# (1, 0) ↦ (1, 0)
+# (0, 1) ↦ (1, 1)
+```
+
+Automorphism data is resolved only on the first orbit query and then cached on
+the sequence space. A returned witness retains this context, so `show()` can
+display the induced homomorphism on the base parent's distinguished additive
+generators. `FiniteAdditiveGroup.cyclic_product(...)` supplies both the
+standard additive generators and elementary coordinate scalings and shears.
+Finite-dimensional Sage vector spaces over finite fields are recognized
+automatically and use their basis and generators of their general linear
+group. A custom `FiniteAdditiveGroup` can receive `additive_generators=` and
+callable `automorphism_generators=` at construction; callers can also pass an
+`AutomorphismAction` explicitly through the `action=` keyword.
+
+Orbit traversal is breadth-first and therefore requires a finite orbit.
+Automatic discovery raises `AutomorphismActionUnavailable` when the parent
+does not expose suitable generators, in which case an explicit action is
+required.
+
+## Benchmarks
+
+Run the short-to-very-long performance corpus with:
+
+```console
+python -m benchmarks.benchmark_factorization --enumerate
+```
+
+The cases and their mathematical expectations are documented in
+[`benchmarks/README.md`](https://github.com/behackl/zero-sum-sequences/blob/main/benchmarks/README.md).
+
+## License
+
+The source code is available under the MIT License.

zero_sum_sequences-0.1.0/README.md

@@ -0,0 +1,208 @@
+# Zero-sum sequences
+
+`zero-sum-sequences` provides immutable finite additive sequences and tools for
+enumerating their factorizations into minimal zero-sum sequences. The runtime
+is ordinary Python with NetworkX; SageMath is supported as an optional source
+of additive parents, but is not required.
+
+The package keeps group-specific mathematics explicit. Callers configure the
+ambient parent and provide an upper bound for its Davenport constant; the
+package does not infer structural invariants from the parent.
+
+## Installation
+
+Install the latest release from PyPI into Python 3.12 or newer:
+
+```console
+python -m pip install zero-sum-sequences
+```
+
+The optional `sage` extra installs the `sagelite` runtime on supported
+platforms:
+
+```console
+python -m pip install "zero-sum-sequences[sage]"
+```
+
+For a reproducible development environment using the committed `uv.lock`,
+clone the repository and run:
+
+```console
+uv sync --extra dev
+uv run python -m pytest
+```
+
+Alternatively, install the package and its test tools with `pip`:
+
+```console
+python -m pip install -e '.[dev]'
+python -m pytest
+```
+
+To include the Sage integration tests, use `uv sync --extra dev --extra sage`
+or install the editable `.[dev,sage]` extra.
+
+## Tutorial
+
+[![Launch the tutorial on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/behackl/zero-sum-sequences/main?urlpath=lab/tree/notebooks/tutorial.ipynb)
+
+The executable [tutorial](https://github.com/behackl/zero-sum-sequences/blob/main/notebooks/tutorial.ipynb) introduces the public API
+with small hand-checkable examples in ordinary Python.
+Its execution dependencies are available through
+`uv sync --extra tutorial` or the corresponding `pip` extra.
+
+## Additive sequences
+
+Configure an ambient parent and a Davenport upper bound once, then use the
+resulting callable space to construct sequences. `FiniteAdditiveGroup` is a
+small convenience adapter for groups represented by ordinary Python values:
+
+```python
+from zero_sum_sequences import AdditiveSequenceSpace, FiniteAdditiveGroup
+
+group = FiniteAdditiveGroup(
+    range(3),
+    zero=0,
+    add=lambda left, right: (left + right) % 3,
+    coerce=lambda value: int(value) % 3,
+)
+Sequences = AdditiveSequenceSpace(group, davenport_bound=3)
+
+sequence = Sequences([1, 1, 2, 2])
+sequence.is_zero_sum()  # True
+sequence.is_atom()      # False: 1 * 2 is a proper zero-sum subsequence
+sequence.multiplicities
+```
+
+Existing algebra systems can be used directly. A compatible parent is
+callable for coercion and provides `zero()`; its elements must be hashable and
+mutually orderable. Elements may implement `+`, or the parent may provide
+`add(left, right)`. Exhaustive catalogue enumeration additionally requires the
+parent to be finite, iterable, and to provide `is_finite()`.
+
+A sequence is immutable and hashable. Addition combines multisets,
+subtraction removes a subsequence, and multiplication by a non-negative
+integer repeats a sequence. Arithmetic preserves the sequence space, and the
+empty sequence retains the base parent and its zero element.
+`sequence.map_terms(mapping)` applies a map to every term and reconstructs the
+result as a canonical multiset; pass `target_space=` when the image belongs to
+a different sequence space.
+
+The configured bound must not be smaller than the actual Davenport constant
+when complete atom or factorization results are required.
+
+## Factorizations
+
+The factorization engine indexes relevant atom divisors as sparse
+multiplicity vectors and merges equal remainders in a directed acyclic graph.
+Attained lengths are represented internally as integer bitsets.
+
+```python
+lengths = sequence.length_set()
+witnesses = sequence.factorization_witnesses()
+factorizations = list(sequence.factorizations())
+graph = sequence.factorization_digraph()
+```
+
+`factorization_witnesses()` retains one factorization for every attained
+length. Exhaustive `factorizations()` is necessarily output-sensitive, but it
+emits each unordered factorization once. `factorization_digraph()` returns a
+NetworkX `DiGraph` whose vertices are remainder sequences and whose edges
+store the removed atom in their `"atom"` attribute.
+
+For several queries against the same remainder DAG, use the public solver:
+
+```python
+from zero_sum_sequences import FactorizationSolver
+
+solver = FactorizationSolver(sequence)
+solver.length_set()
+solver.factorization_witnesses()
+solver.statistics
+solver.digraph()
+```
+
+A complete precomputed catalogue can avoid rediscovering atoms:
+
+```python
+from zero_sum_sequences import AtomCatalogue, FactorizationSolver
+
+catalogue = AtomCatalogue(Sequences, atoms)
+solver = FactorizationSolver(sequence, atom_catalogue=catalogue)
+```
+
+For a small finite parent, a complete reduced catalogue can instead be
+generated exhaustively through the configured Davenport bound:
+
+```python
+catalogue = Sequences.enumerate_atom_catalogue()
+```
+
+The parent must be a finite iterable additive group. Enumeration completes
+each sorted prefix with its uniquely determined final term, rather than
+testing multisets whose sum is nonzero. Completeness depends on the configured
+Davenport bound being valid.
+
+The caller is responsible for catalogue completeness. A catalogue used for a
+complete result must contain every atom divisor relevant to the input.
+
+Factorizations are computed in the reduced block monoid: identity terms are
+not accepted by the solver and are not stored in an `AtomCatalogue`.
+
+## Automorphism orbits
+
+Group automorphisms act on sequences term by term. Because an
+`AdditiveSequence` is a multiset, the induced action automatically disregards
+the order of its terms. The package can materialize an orbit, test orbit
+membership, and return a shortest deterministic word in the configured
+automorphism generators.
+
+The convenience constructor for a product of cyclic groups configures the
+coordinate group and generators of its full automorphism group together. For
+example, the eight maximal-length atoms over $C_2\oplus C_4$ form one orbit:
+
+```python
+G = FiniteAdditiveGroup.cyclic_product(2, 4)
+C2xC4 = AdditiveSequenceSpace(G, davenport_bound=5)
+
+atom = C2xC4([(0, 1)] * 3 + [(1, 0), (1, 1)])
+other = C2xC4([(0, 1), (1, 0)] + [(1, 1)] * 3)
+
+len(atom.orbit())                         # 8
+atom.is_in_same_orbit(other)              # True
+witness = atom.orbit_witness(other)
+witness.show()
+# (1, 0) ↦ (1, 0)
+# (0, 1) ↦ (1, 1)
+```
+
+Automorphism data is resolved only on the first orbit query and then cached on
+the sequence space. A returned witness retains this context, so `show()` can
+display the induced homomorphism on the base parent's distinguished additive
+generators. `FiniteAdditiveGroup.cyclic_product(...)` supplies both the
+standard additive generators and elementary coordinate scalings and shears.
+Finite-dimensional Sage vector spaces over finite fields are recognized
+automatically and use their basis and generators of their general linear
+group. A custom `FiniteAdditiveGroup` can receive `additive_generators=` and
+callable `automorphism_generators=` at construction; callers can also pass an
+`AutomorphismAction` explicitly through the `action=` keyword.
+
+Orbit traversal is breadth-first and therefore requires a finite orbit.
+Automatic discovery raises `AutomorphismActionUnavailable` when the parent
+does not expose suitable generators, in which case an explicit action is
+required.
+
+## Benchmarks
+
+Run the short-to-very-long performance corpus with:
+
+```console
+python -m benchmarks.benchmark_factorization --enumerate
+```
+
+The cases and their mathematical expectations are documented in
+[`benchmarks/README.md`](https://github.com/behackl/zero-sum-sequences/blob/main/benchmarks/README.md).
+
+## License
+
+The source code is available under the MIT License.

zero_sum_sequences-0.1.0/benchmarks/README.md

@@ -0,0 +1,32 @@
+# Factorization benchmark corpus
+
+The benchmark corpus is shared by the test suite and timing runner. It
+separates input size from combinatorial difficulty and checks the sole
+supported memoized factorization implementation.
+
+| Case | Tier | Terms | Expected length set |
+|---|---|---:|---|
+| `c3-atom` | short | 3 | `{1}` |
+| `c3-balanced-block` | short | 6 | `{2,3}` |
+| `rank-three-inverse-pair` | short | 14 | `{2,3,4,5,7}` |
+| `c3-balanced-power-7` | long | 42 | `[14,21]` |
+| `c3-balanced-power-40` | long | 240 | `[80,120]` |
+| `rank-three-inverse-power-3` | long | 42 | `[6,21]` |
+| `c3-balanced-power-250` | very long | 1,500 | `[500,750]` |
+| `c3-pure-power-5000` | very long | 15,000 | `{5000}` |
+
+For the balanced `C_3` family, write `A = 1^3`, `B = 2^3`, and
+`C = 1 * 2`. A factorization of `(A * B)^n` has `x` copies each of `A`
+and `B`, and `3(n-x)` copies of `C`, for `0 <= x <= n`. Its length set is
+therefore exactly `[2n,3n]`, and it has `n+1` unordered factorizations. The
+pure-power case has one factorization of length 5,000.
+
+The rank-three cases exercise a less artificial support and a larger
+candidate-atom set. The runner reports candidate indexing, state-graph solve,
+and safe exhaustive-enumeration timings while validating all expected results.
+
+Run:
+
+```console
+python -m benchmarks.benchmark_factorization --enumerate
+```

zero_sum_sequences-0.1.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Reproducible performance benchmarks for the computational package."""

zero_sum_sequences-0.1.0/benchmarks/benchmark_factorization.py

@@ -0,0 +1,136 @@
+"""Benchmark the memoized factorization implementation."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+from collections.abc import Sequence
+from time import perf_counter
+
+from zero_sum_sequences import FactorizationSolver
+
+from .factorization_cases import factorization_benchmark_cases
+
+
+def elapsed(callable_):
+    start = perf_counter()
+    result = callable_()
+    return result, perf_counter() - start
+
+
+def benchmark_case(
+    case, *, enumerate_factorizations: bool, repeats: int
+) -> dict[str, object]:
+    best_run = None
+    for _ in range(repeats):
+        solver, preparation_seconds = elapsed(
+            lambda: FactorizationSolver(case.sequence)
+        )
+        lengths, solve_seconds = elapsed(solver.length_set)
+        if best_run is None or preparation_seconds + solve_seconds < sum(best_run[1:]):
+            best_run = (solver, preparation_seconds, solve_seconds)
+    assert best_run is not None
+    solver, preparation_seconds, solve_seconds = best_run
+    lengths = solver.length_set()
+    if lengths != set(case.expected_lengths):
+        raise AssertionError(
+            f"{case.name}: expected {sorted(case.expected_lengths)}, "
+            f"got {sorted(lengths)}"
+        )
+    statistics = solver.statistics
+
+    factorization_count: int | None = None
+    enumeration_seconds: float | None = None
+    if enumerate_factorizations and case.enumerate_factorizations:
+        factorizations, enumeration_seconds = elapsed(
+            lambda: list(solver.factorizations())
+        )
+        factorization_count = len(factorizations)
+        if factorization_count != case.expected_factorizations:
+            raise AssertionError(
+                f"{case.name}: expected {case.expected_factorizations} "
+                f"factorizations, got {factorization_count}"
+            )
+
+    return {
+        "name": case.name,
+        "tier": case.tier,
+        "terms": len(case.sequence),
+        "lengths": len(lengths),
+        "atoms": statistics.candidate_atoms,
+        "states": statistics.states,
+        "transitions": statistics.transitions,
+        "prepare_ms": preparation_seconds * 1000,
+        "solve_ms": solve_seconds * 1000,
+        "factorizations": factorization_count,
+        "enumerate_ms": (
+            None if enumeration_seconds is None else enumeration_seconds * 1000
+        ),
+    }
+
+
+def format_value(value: object) -> str:
+    if value is None:
+        return "—"
+    if isinstance(value, float):
+        return f"{value:.3f}"
+    return str(value)
+
+
+def print_markdown(rows: list[dict[str, object]]) -> None:
+    columns = (
+        "name",
+        "tier",
+        "terms",
+        "lengths",
+        "atoms",
+        "states",
+        "transitions",
+        "prepare_ms",
+        "solve_ms",
+        "factorizations",
+        "enumerate_ms",
+    )
+    print("| " + " | ".join(columns) + " |")
+    print("| " + " | ".join("---" for _ in columns) + " |")
+    for row in rows:
+        print("| " + " | ".join(format_value(row[column]) for column in columns) + " |")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--enumerate",
+        action="store_true",
+        help="also enumerate unique factorizations for cases marked as safe",
+    )
+    parser.add_argument(
+        "--repeats",
+        type=int,
+        default=3,
+        help="number of timing repetitions; the minimum is reported",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = build_parser().parse_args(argv)
+    if arguments.repeats < 1:
+        raise SystemExit("--repeats must be positive")
+    print(f"Python {platform.python_version()}")
+    print()
+    cases = factorization_benchmark_cases()
+    rows = [
+        benchmark_case(
+            case,
+            enumerate_factorizations=arguments.enumerate,
+            repeats=arguments.repeats,
+        )
+        for case in cases
+    ]
+    print_markdown(rows)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())