zero-sum-sequences 0.1.0__py3-none-any.whl

zero_sum_sequences/parents.py

@@ -0,0 +1,264 @@
+"""Small adapters for defining additive parents without a CAS dependency."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from itertools import product
+from math import gcd
+from operator import index
+from typing import Generic, TypeVar
+
+Element = TypeVar("Element")
+
+
+def _positive_modulus(value: object) -> int:
+    if isinstance(value, bool):
+        raise ValueError("cyclic moduli must be positive integers")
+    try:
+        modulus = index(value)
+    except TypeError:
+        raise ValueError("cyclic moduli must be positive integers") from None
+    if modulus < 1:
+        raise ValueError("cyclic moduli must be positive integers")
+    return modulus
+
+
+def _scale_coordinate(coordinate: int, unit: int, modulus: int):
+    def scaling(element):
+        image = list(element)
+        image[coordinate] = unit * image[coordinate] % modulus
+        return tuple(image)
+
+    return scaling
+
+
+def _shear_coordinate(
+    target: int,
+    source: int,
+    coefficient: int,
+    modulus: int,
+):
+    def shear(element):
+        image = list(element)
+        image[target] = (
+            image[target] + coefficient * image[source]
+        ) % modulus
+        return tuple(image)
+
+    return shear
+
+
+class FiniteAdditiveGroup(Generic[Element]):
+    """A finite additive parent defined by elements and an operation.
+
+    The supplied data is treated as a group presentation; associativity,
+    inverses, and closure are not checked exhaustively.  Results produced by
+    ``add`` are coerced and checked for membership when the operation is used.
+    """
+
+    __slots__ = (
+        "_elements",
+        "_element_set",
+        "_zero",
+        "_operation",
+        "_coerce",
+        "_additive_generators",
+        "_automorphism_generators",
+    )
+
+    @classmethod
+    def cyclic_product(cls, *moduli: int) -> FiniteAdditiveGroup[tuple[int, ...]]:
+        """Return the coordinate group ``C_n1 x ... x C_nr``.
+
+        The parent includes elementary generators of its full automorphism
+        group: multiplication of one coordinate by a unit and all admissible
+        coordinate shears.  Consequently, sequence orbit methods work without
+        an explicitly supplied action.
+        """
+
+        if not moduli:
+            raise ValueError("at least one cyclic modulus is required")
+        normalized_moduli = tuple(_positive_modulus(value) for value in moduli)
+
+        def coerce(value):
+            try:
+                coordinates = tuple(value)
+            except TypeError:
+                raise ValueError(
+                    "cyclic-product elements must be coordinate iterables"
+                ) from None
+            if len(coordinates) != len(normalized_moduli):
+                raise ValueError(
+                    "cyclic-product elements have the wrong number of coordinates"
+                )
+            try:
+                return tuple(
+                    index(coordinate) % modulus
+                    for coordinate, modulus in zip(
+                        coordinates,
+                        normalized_moduli,
+                    )
+                )
+            except TypeError:
+                raise ValueError(
+                    "cyclic-product coordinates must be integers"
+                ) from None
+
+        def add(left, right):
+            return tuple(
+                (left[position] + right[position]) % modulus
+                for position, modulus in enumerate(normalized_moduli)
+            )
+
+        generators = []
+        for coordinate, modulus in enumerate(normalized_moduli):
+            generators.extend(
+                _scale_coordinate(coordinate, unit, modulus)
+                for unit in range(2, modulus)
+                if gcd(unit, modulus) == 1
+            )
+        for target, target_modulus in enumerate(normalized_moduli):
+            for source, source_modulus in enumerate(normalized_moduli):
+                if target == source:
+                    continue
+                coefficient = target_modulus // gcd(
+                    target_modulus,
+                    source_modulus,
+                )
+                if coefficient % target_modulus:
+                    generators.append(
+                        _shear_coordinate(
+                            target,
+                            source,
+                            coefficient,
+                            target_modulus,
+                        )
+                    )
+
+        additive_generators = tuple(
+            tuple(
+                1 if position == coordinate else 0
+                for position in range(len(normalized_moduli))
+            )
+            for coordinate, modulus in enumerate(normalized_moduli)
+            if modulus > 1
+        )
+
+        return cls(
+            product(*(range(modulus) for modulus in normalized_moduli)),
+            zero=(0,) * len(normalized_moduli),
+            add=add,
+            coerce=coerce,
+            additive_generators=additive_generators,
+            automorphism_generators=generators,
+        )
+
+    def __init__(
+        self,
+        elements: Iterable[Element],
+        *,
+        zero: Element,
+        add: Callable[[Element, Element], Element],
+        coerce: Callable[[object], Element] | None = None,
+        additive_generators: Iterable[Element] | None = None,
+        automorphism_generators: (
+            Iterable[Callable[[Element], Element]] | None
+        ) = None,
+    ) -> None:
+        if not callable(add):
+            raise TypeError("the additive operation must be callable")
+        if coerce is not None and not callable(coerce):
+            raise TypeError("coerce must be callable")
+
+        self._coerce = coerce if coerce is not None else lambda value: value
+        try:
+            coerced_elements = tuple(self._coerce(element) for element in elements)
+            element_set = frozenset(coerced_elements)
+        except TypeError:
+            raise TypeError("finite-group elements must be hashable") from None
+        if len(element_set) != len(coerced_elements):
+            raise ValueError("finite-group elements must be distinct after coercion")
+
+        try:
+            ordered_elements = tuple(sorted(coerced_elements))
+        except TypeError:
+            raise TypeError(
+                "finite-group elements must be mutually orderable"
+            ) from None
+
+        self._elements = ordered_elements
+        self._element_set = element_set
+        self._operation = add
+        self._zero = self(zero)
+        if additive_generators is None:
+            self._additive_generators = None
+        else:
+            try:
+                generators = tuple(self(element) for element in additive_generators)
+            except TypeError:
+                raise TypeError("additive generators must be iterable") from None
+            if self._zero in generators:
+                raise ValueError("additive generators must be nonzero")
+            if len(set(generators)) != len(generators):
+                raise ValueError("additive generators must be distinct")
+            self._additive_generators = generators
+        if automorphism_generators is None:
+            self._automorphism_generators = None
+        else:
+            generators = tuple(automorphism_generators)
+            if not all(callable(generator) for generator in generators):
+                raise TypeError("automorphism generators must be callable")
+            self._automorphism_generators = generators
+
+    def __call__(self, value: object) -> Element:
+        element = self._coerce(value)
+        try:
+            contained = element in self._element_set
+        except TypeError:
+            contained = False
+        if not contained:
+            raise ValueError(f"{element!r} is not an element of this group")
+        return element
+
+    def zero(self) -> Element:
+        """Return the additive identity."""
+
+        return self._zero
+
+    def add(self, left: Element, right: Element) -> Element:
+        """Add two elements and return their canonical representative."""
+
+        left = self(left)
+        right = self(right)
+        return self(self._operation(left, right))
+
+    def is_finite(self) -> bool:
+        return True
+
+    def additive_generators(self):
+        """Return a configured generating set for the additive group."""
+
+        if self._additive_generators is None:
+            raise NotImplementedError
+        return self._additive_generators
+
+    def automorphism_generators(self):
+        """Return explicitly configured automorphism generators.
+
+        Generic finite groups do not expose a presentation from which these
+        maps could be inferred.  Supply them at construction when automatic
+        orbit methods are desired.
+        """
+
+        if self._automorphism_generators is None:
+            raise NotImplementedError
+        return self._automorphism_generators
+
+    def __iter__(self) -> Iterator[Element]:
+        return iter(self._elements)
+
+    def __len__(self) -> int:
+        return len(self._elements)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self._elements)!r}, zero={self._zero!r})"

zero_sum_sequences-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,10 @@
+zero_sum_sequences/__init__.py,sha256=3PomZ1YK7yJWJTAYGgoL-0wWTHJX-29Yy24AWrap3m4,721
+zero_sum_sequences/additive_sequence.py,sha256=KuRvrH3u_7v_5W3GHOY66dCW4gQFyIvkVDFsgDKz0uE,18648
+zero_sum_sequences/atom_catalogue.py,sha256=4l00RjopVORnZ0bl59ZS0LN3sqf6DxyIcl3MTZOyBJM,3449
+zero_sum_sequences/factorization.py,sha256=oMI4NB1sXCbVTl-dEghjrhLkSGHOuveZrovOm6N8c9w,14516
+zero_sum_sequences/orbits.py,sha256=iJRY6KTiqE3wHGQybu_1WgC7m4BHFe5-sHpOorhObIk,18335
+zero_sum_sequences/parents.py,sha256=nbdWJN4j7wCC1kszNUzWbzo3XUrCOI8A51HOY4Z0a6s,9162
+zero_sum_sequences-0.1.0.dist-info/METADATA,sha256=t6uU1gqLp4dIvW1o-fHYknGTOn328ug83KCpgKHfVmU,8413
+zero_sum_sequences-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+zero_sum_sequences-0.1.0.dist-info/licenses/LICENSE,sha256=k6e0VWMPXDbULziLaPVyAIVhYuJdUYEmhCWGP07S8f8,1071
+zero_sum_sequences-0.1.0.dist-info/RECORD,,

zero_sum_sequences-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zero_sum_sequences-0.1.0.dist-info/licenses/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.