zero-sum-sequences 0.1.2__tar.gz → 0.2.0__tar.gz

{zero_sum_sequences-0.1.2 → zero_sum_sequences-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zero-sum-sequences
-Version: 0.1.2
+Version: 0.2.0
 Summary: Computations with additive and zero-sum sequences
 Project-URL: Repository, https://github.com/behackl/zero-sum-sequences
 Author: Benjamin Hackl
@@ -312,6 +312,106 @@ Automatic discovery raises `AutomorphismActionUnavailable` when the parent
 does not expose suitable generators, in which case an explicit action is
 required.
 
+## Materialized automorphism groups
+
+For a finite parent the whole automorphism group can be materialized, which
+gives stabilizers, canonical orbit representatives, transporters and
+classification of many objects at once:
+
+```python
+G = FiniteAdditiveGroup.cyclic_product(2, 4)
+C2xC4 = AdditiveSequenceSpace(G, davenport_bound=5)
+group = C2xC4.automorphism_group()        # AutomorphismGroup(order=8)
+
+x = C2xC4([(1, 1), (1, 1), (0, 2)])
+group.orbit(x)                            # the four images, sorted
+len(group.stabilizer(x))                  # 2
+form = group.canonical_form(x)            # orbit minimum + smallest automorphism reaching it
+form.automorphism.generator_images()      # ((1, 0), (1, 1)): the "matrix", column by column
+group.transporter(x, group.apply(form.automorphism, x))
+
+atoms = tuple(C2xC4.enumerate_atom_catalogue())
+group.orbit_representatives(atoms)        # 11 orbits: representative -> members
+```
+
+The group acts on sequences and on tuples of sequences; tuples are treated as
+multisets unless `ordered=True` (the canonical form of a tuple also records
+the permutation that sorts the image). Canonical forms are minima with
+respect to the total order on sequences (length first, then the sorted term
+list, exposed through `<`), so representatives do not depend on how the group
+was found.
+
+The parent decides how the group is obtained: a `FiniteAdditiveGroup` may
+receive a callable `automorphism_group=` returning an `AutomorphismGroup`
+built from any element type with `apply_term`, `compose` and `inverse`
+callbacks (for example units acting on a cyclic group, or CAS matrices);
+otherwise its `automorphism_generators` are closed under composition.
+Orbit traversals cost proportionally to the orbit size; stabilizers and
+smallest transporters scan the whole group once, so they are cheap for
+groups of a few thousand elements and expensive beyond that.
+`AutomorphismGroupUnavailable` is raised when neither a provider nor
+generators exist.
+
+## Indexed and serialized catalogues
+
+An `AtomCatalogue` stores its atoms in the sequence order (length first,
+then terms), so `catalogue.index(atom)` and `catalogue[i]` form a stable
+identifier namespace. It can be filtered, classified into automorphism
+orbits, and written to or read from JSON lines:
+
+```python
+catalogue = C2xC4.enumerate_atom_catalogue()
+catalogue.index(atom), catalogue[7], atom in catalogue
+short = catalogue.restrict(max_length=3)            # also restrict(support=...)
+for orbit in catalogue.orbits():                    # AtomOrbit(representative, indices, stabilizer_order)
+    ...
+catalogue.representative(atom)                      # orbit minimum of an atom
+catalogue.transporter(atom)                         # an automorphism mapping atom to it
+catalogue.permutation(group.elements[1])            # an automorphism as an index permutation
+
+catalogue.to_jsonl("atoms.jsonl", annotate=lambda atom: {"label": ...})
+same = AtomCatalogue.from_jsonl("atoms.jsonl", C2xC4)
+same.annotations[atom]["label"]
+catalogue.digest()                                  # sha256 of the atoms, annotation-independent
+```
+
+`from_jsonl` checks the order, the indices and the digest, and re-verifies
+every record as an atom unless `verify=False`. Terms are serialized through
+the parent: `FiniteAdditiveGroup` accepts `encode_term=`/`decode_term=`,
+coordinate groups and Sage vector spaces use lists of integers by default,
+and `sequence.encode()` / `space.decode(data)` apply the codec to whole
+sequences.
+
+## Memoized factorization queries
+
+A `FactorizationCache` answers length-set questions over one catalogue with
+caching, and can exploit that length sets are automorphism invariants:
+
+```python
+cache = C2xC4.factorization_cache(catalogue)
+cache.length_set(x), cache.minimum(x), cache.maximum(x)
+cache.has_length(x, 3), cache.witness(x, 3), cache.witnesses(x)
+cache.statistics()                                      # hits, misses, solver builds
+
+aware = C2xC4.factorization_cache(catalogue, group=group)
+aware.length_set(group.apply(a, x)) == aware.length_set(x)   # one solve per orbit
+aware.witness(group.apply(a, x), 3)                     # transported back through a^-1
+
+cache.to_jsonl("lengths.jsonl")                         # bound to catalogue.digest()
+FactorizationCache.from_jsonl("lengths.jsonl", catalogue)
+```
+
+Length sets are kept without bound; solvers are kept in a bounded LRU
+(`maxsize=`) so that follow-up questions about a recent sequence reuse its
+remainder graph. With `group=` every query is keyed by a canonical form.
+The default is the full canonical form, whose orbit traversal is worthwhile
+when solving is the expensive part; for large groups pass
+`canonicalize=AnchoredCanonicalizer(catalogue, group)`, which only
+transports the largest atom dividing the sequence to its orbit
+representative and reduces under that representative's stabilizer. Any
+callable returning an automorphic image of its argument (optionally with the
+automorphism) is accepted as `canonicalize=`.
+
 ## Benchmarks
 
 Run the short-to-very-long performance corpus with:

{zero_sum_sequences-0.1.2 → zero_sum_sequences-0.2.0}/README.md

@@ -292,6 +292,106 @@ Automatic discovery raises `AutomorphismActionUnavailable` when the parent
 does not expose suitable generators, in which case an explicit action is
 required.
 
+## Materialized automorphism groups
+
+For a finite parent the whole automorphism group can be materialized, which
+gives stabilizers, canonical orbit representatives, transporters and
+classification of many objects at once:
+
+```python
+G = FiniteAdditiveGroup.cyclic_product(2, 4)
+C2xC4 = AdditiveSequenceSpace(G, davenport_bound=5)
+group = C2xC4.automorphism_group()        # AutomorphismGroup(order=8)
+
+x = C2xC4([(1, 1), (1, 1), (0, 2)])
+group.orbit(x)                            # the four images, sorted
+len(group.stabilizer(x))                  # 2
+form = group.canonical_form(x)            # orbit minimum + smallest automorphism reaching it
+form.automorphism.generator_images()      # ((1, 0), (1, 1)): the "matrix", column by column
+group.transporter(x, group.apply(form.automorphism, x))
+
+atoms = tuple(C2xC4.enumerate_atom_catalogue())
+group.orbit_representatives(atoms)        # 11 orbits: representative -> members
+```
+
+The group acts on sequences and on tuples of sequences; tuples are treated as
+multisets unless `ordered=True` (the canonical form of a tuple also records
+the permutation that sorts the image). Canonical forms are minima with
+respect to the total order on sequences (length first, then the sorted term
+list, exposed through `<`), so representatives do not depend on how the group
+was found.
+
+The parent decides how the group is obtained: a `FiniteAdditiveGroup` may
+receive a callable `automorphism_group=` returning an `AutomorphismGroup`
+built from any element type with `apply_term`, `compose` and `inverse`
+callbacks (for example units acting on a cyclic group, or CAS matrices);
+otherwise its `automorphism_generators` are closed under composition.
+Orbit traversals cost proportionally to the orbit size; stabilizers and
+smallest transporters scan the whole group once, so they are cheap for
+groups of a few thousand elements and expensive beyond that.
+`AutomorphismGroupUnavailable` is raised when neither a provider nor
+generators exist.
+
+## Indexed and serialized catalogues
+
+An `AtomCatalogue` stores its atoms in the sequence order (length first,
+then terms), so `catalogue.index(atom)` and `catalogue[i]` form a stable
+identifier namespace. It can be filtered, classified into automorphism
+orbits, and written to or read from JSON lines:
+
+```python
+catalogue = C2xC4.enumerate_atom_catalogue()
+catalogue.index(atom), catalogue[7], atom in catalogue
+short = catalogue.restrict(max_length=3)            # also restrict(support=...)
+for orbit in catalogue.orbits():                    # AtomOrbit(representative, indices, stabilizer_order)
+    ...
+catalogue.representative(atom)                      # orbit minimum of an atom
+catalogue.transporter(atom)                         # an automorphism mapping atom to it
+catalogue.permutation(group.elements[1])            # an automorphism as an index permutation
+
+catalogue.to_jsonl("atoms.jsonl", annotate=lambda atom: {"label": ...})
+same = AtomCatalogue.from_jsonl("atoms.jsonl", C2xC4)
+same.annotations[atom]["label"]
+catalogue.digest()                                  # sha256 of the atoms, annotation-independent
+```
+
+`from_jsonl` checks the order, the indices and the digest, and re-verifies
+every record as an atom unless `verify=False`. Terms are serialized through
+the parent: `FiniteAdditiveGroup` accepts `encode_term=`/`decode_term=`,
+coordinate groups and Sage vector spaces use lists of integers by default,
+and `sequence.encode()` / `space.decode(data)` apply the codec to whole
+sequences.
+
+## Memoized factorization queries
+
+A `FactorizationCache` answers length-set questions over one catalogue with
+caching, and can exploit that length sets are automorphism invariants:
+
+```python
+cache = C2xC4.factorization_cache(catalogue)
+cache.length_set(x), cache.minimum(x), cache.maximum(x)
+cache.has_length(x, 3), cache.witness(x, 3), cache.witnesses(x)
+cache.statistics()                                      # hits, misses, solver builds
+
+aware = C2xC4.factorization_cache(catalogue, group=group)
+aware.length_set(group.apply(a, x)) == aware.length_set(x)   # one solve per orbit
+aware.witness(group.apply(a, x), 3)                     # transported back through a^-1
+
+cache.to_jsonl("lengths.jsonl")                         # bound to catalogue.digest()
+FactorizationCache.from_jsonl("lengths.jsonl", catalogue)
+```
+
+Length sets are kept without bound; solvers are kept in a bounded LRU
+(`maxsize=`) so that follow-up questions about a recent sequence reuse its
+remainder graph. With `group=` every query is keyed by a canonical form.
+The default is the full canonical form, whose orbit traversal is worthwhile
+when solving is the expensive part; for large groups pass
+`canonicalize=AnchoredCanonicalizer(catalogue, group)`, which only
+transports the largest atom dividing the sequence to its orbit
+representative and reduces under that representative's stabilizer. Any
+callable returning an automorphic image of its argument (optionally with the
+automorphism) is accepted as `canonicalize=`.
+
 ## Benchmarks
 
 Run the short-to-very-long performance corpus with:

{zero_sum_sequences-0.1.2 → zero_sum_sequences-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zero-sum-sequences"
-version = "0.1.2"
+version = "0.2.0"
 description = "Computations with additive and zero-sum sequences"
 readme = "README.md"
 requires-python = ">=3.12"

{zero_sum_sequences-0.1.2 → zero_sum_sequences-0.2.0}/src/zero_sum_sequences/__init__.py

@@ -3,8 +3,15 @@
 from importlib.metadata import version as _distribution_version
 
 from .additive_sequence import AdditiveSequence, AdditiveSequenceSpace
-from .atom_catalogue import AtomCatalogue
+from .atom_catalogue import AtomCatalogue, AtomOrbit
+from .automorphisms import (
+    Automorphism,
+    AutomorphismGroup,
+    AutomorphismGroupUnavailable,
+    CanonicalForm,
+)
 from .factorization import Factorization, FactorizationSolver
+from .factorization_cache import AnchoredCanonicalizer, FactorizationCache
 from .orbits import (
     AutomorphismAction,
     AutomorphismActionUnavailable,
@@ -17,12 +24,19 @@ __all__ = [
     "AdditiveSequence",
     "AdditiveSequenceSpace",
     "AtomCatalogue",
+    "AtomOrbit",
     "Factorization",
     "FactorizationRelation",
+    "AnchoredCanonicalizer",
+    "FactorizationCache",
     "FactorizationSolver",
     "FiniteAdditiveGroup",
+    "Automorphism",
     "AutomorphismAction",
     "AutomorphismActionUnavailable",
+    "AutomorphismGroup",
+    "AutomorphismGroupUnavailable",
+    "CanonicalForm",
     "OrbitWitness",
 ]
 __version__ = _distribution_version("zero-sum-sequences")

{zero_sum_sequences-0.1.2 → zero_sum_sequences-0.2.0}/src/zero_sum_sequences/additive_sequence.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import functools
 import itertools
 from collections import Counter
 from collections.abc import Callable, Iterable, Iterator, Mapping
@@ -74,7 +75,12 @@ class AdditiveSequenceSpace(Generic[Element]):
         A positive upper bound for the parent's Davenport constant.
     """
 
-    __slots__ = ("_parent", "_davenport_bound", "_automorphism_action")
+    __slots__ = (
+        "_parent",
+        "_davenport_bound",
+        "_automorphism_action",
+        "_automorphism_group",
+    )
 
     def __init__(self, parent, *, davenport_bound: int) -> None:
         if not callable(parent):
@@ -88,6 +94,52 @@ class AdditiveSequenceSpace(Generic[Element]):
             name="Davenport bound",
         )
         self._automorphism_action = None
+        self._automorphism_group = None
+
+    def factorization_cache(self, catalogue, *, group=None, canonicalize=None, maxsize: int | None = 1024):
+        """A :class:`FactorizationCache` over ``catalogue`` for this space."""
+
+        from .factorization_cache import FactorizationCache
+
+        if catalogue.space is not self:
+            raise TypeError("the catalogue belongs to a different space")
+        return FactorizationCache(
+            catalogue, group=group, canonicalize=canonicalize, maxsize=maxsize
+        )
+
+    def encode_term(self, term: Element) -> object:
+        """JSON-compatible encoding of one term, delegated to the parent."""
+
+        encoder = getattr(self._parent, "encode_term", None)
+        if callable(encoder):
+            return encoder(term)
+        from .parents import default_encode_term
+
+        return default_encode_term(term)
+
+    def decode_term(self, data: object) -> Element:
+        """Inverse of :meth:`encode_term`, delegated to the parent."""
+
+        decoder = getattr(self._parent, "decode_term", None)
+        if callable(decoder):
+            return _immutable_term(decoder(data))
+        return _immutable_term(self._parent(data))
+
+    def decode(self, data: Iterable[object]) -> AdditiveSequence[Element]:
+        """Construct a sequence from a list of encoded terms."""
+
+        return self(self.decode_term(item) for item in data)
+
+    def automorphism_group(self):
+        """Return the materialized automorphism group of the additive parent.
+
+        The parent may supply the group itself; otherwise it is the closure
+        of the parent's automorphism generators.  The result is cached.
+        """
+
+        from .automorphisms import automorphism_group
+
+        return automorphism_group(self)
 
     @property
     def base_parent(self):
@@ -226,6 +278,7 @@ class AdditiveSequenceSpace(Generic[Element]):
         )
 
 
+@functools.total_ordering
 class AdditiveSequence(Generic[Element]):
     """An immutable finite multiset in an :class:`AdditiveSequenceSpace`.
 
@@ -258,6 +311,28 @@ class AdditiveSequence(Generic[Element]):
         self._length = sum(count for _, count in items)
         self._hash = hash((space, items))
 
+    @classmethod
+    def _from_items(
+        cls, space: AdditiveSequenceSpace[Element], items: tuple[tuple[Element, int], ...]
+    ) -> AdditiveSequence[Element]:
+        """Fast constructor from sorted ``(term, count)`` items of canonical terms."""
+
+        sequence = cls.__new__(cls)
+        sequence._space = space
+        sequence._items = items
+        sequence._length = sum(count for _, count in items)
+        sequence._hash = hash((space, items))
+        return sequence
+
+    def _map_canonical(self, mapping: Callable[[Element], Element]) -> AdditiveSequence[Element]:
+        """Image under a term map whose values are canonical parent elements."""
+
+        counts: dict[Element, int] = {}
+        for term, count in self._items:
+            image = mapping(term)
+            counts[image] = counts.get(image, 0) + count
+        return AdditiveSequence._from_items(self._space, tuple(sorted(counts.items())))
+
     def parent(self) -> AdditiveSequenceSpace[Element]:
         """Return the configured sequence space."""
 
@@ -558,6 +633,19 @@ class AdditiveSequence(Generic[Element]):
     def __rmul__(self, repetitions: object) -> Self:
         return self * repetitions
 
+    def encode(self) -> list[object]:
+        """The sorted term list with multiplicities, terms encoded by the space."""
+
+        return [self._space.encode_term(term) for term in self]
+
+    def __lt__(self, other: object) -> bool:
+        """Total order: shorter sequences first, then the sorted term lists."""
+
+        if not isinstance(other, AdditiveSequence):
+            return NotImplemented
+        self._require_same_space(other)
+        return (self._length, tuple(self)) < (other._length, tuple(other))
+
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, AdditiveSequence):
             return NotImplemented