feat(math): add finitely generated abelian group operations (#1857)

Add abelian_group domain with 6 operations: presentation normalization
via Smith normal form, element reduction, element equality, element
order, subgroup index computation, and quotient group computation.

Closes #1857

Author: morluto

src/jacobian/catalog/builtins.py

@@ -70,6 +70,12 @@
 from jacobian.math.electrical_networks._tools import (
     TOOLS as ELECTRICAL_NETWORKS_TOOLS,
 )
+from jacobian.math.finite_abelian_groups_v2._admission import (
+    ADMISSIONS as FINITE_ABELIAN_GROUPS_V2_ADMISSIONS,
+)
+from jacobian.math.finite_abelian_groups_v2._tools import (
+    TOOLS as FINITE_ABELIAN_GROUPS_V2_TOOLS,
+)
 from jacobian.math.finite_fields._admission import (
     ADMISSIONS as FINITE_FIELDS_ADMISSIONS,
 )
@@ -293,6 +299,7 @@
     *COMBINATORICS_TOOLS,
     *FINITE_SETS_TOOLS,
     *FINITE_FIELDS_TOOLS,
+    *FINITE_ABELIAN_GROUPS_V2_TOOLS,
     *LOGIC_TOOLS,
     *SEQUENCES_TOOLS,
     *GEOMETRY_TOOLS,
@@ -365,6 +372,7 @@
     *DISCREPANCY_THEORY_ADMISSIONS,
     *ELECTRICAL_NETWORKS_ADMISSIONS,
     *FINITE_FIELDS_ADMISSIONS,
+    *FINITE_ABELIAN_GROUPS_V2_ADMISSIONS,
     *FINITE_GAME_THEORY_ADMISSIONS,
     *FINITE_METRIC_SPACES_ADMISSIONS,
     *FINITE_SETS_ADMISSIONS,

src/jacobian/math/finite_abelian_groups_v2/__init__.py

@@ -0,0 +1,3 @@
+"""Finitely generated abelian group operations."""
+
+__all__: list[str] = []

src/jacobian/math/finite_abelian_groups_v2/_admission.py

@@ -0,0 +1,38 @@
+"""Owner-local admission decisions for built-in math operations."""
+
+from __future__ import annotations
+
+from jacobian.catalog.admission import AdmissionDecision, OperationAdmission
+
+ADMISSIONS: tuple[OperationAdmission, ...] = (
+    OperationAdmission(
+        "abelian_group.element.equal.decide",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "abelian_group.element.order.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "abelian_group.element.reduce",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "abelian_group.presentation.normalize",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "abelian_group.quotient.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "abelian_group.subgroup.generated.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+)

src/jacobian/math/finite_abelian_groups_v2/_models.py

@@ -0,0 +1,137 @@
+"""Typed wire contracts for finitely generated abelian group operations."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from jacobian._models import StrictModel
+
+MAX_ORDERS = 32
+
+
+class AbelianPresentation(StrictModel):
+    """An invariant-factor decomposition of a finitely generated abelian group."""
+
+    invariant_factors: tuple[int, ...] = Field(min_length=0, max_length=MAX_ORDERS)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if any(f < 0 for f in self.invariant_factors):
+            raise ValueError("invariant factors must be nonnegative")
+        if any(f == 1 for f in self.invariant_factors):
+            raise ValueError("trivial factors of 1 should be omitted")
+        if any(
+            self.invariant_factors[i] % self.invariant_factors[i + 1] != 0
+            for i in range(len(self.invariant_factors) - 1)
+        ):
+            raise ValueError("invariant factors must divide: d_i | d_{i+1}")
+        return self
+
+
+class ElementReduceRequest(StrictModel):
+    invariant_factors: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    coordinates: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if len(self.coordinates) != len(self.invariant_factors):
+            raise ValueError("coordinates length must match invariant_factors length")
+        if any(d < 0 for d in self.invariant_factors):
+            raise ValueError("invariant factors must be positive")
+        return self
+
+
+class ElementEqualRequest(StrictModel):
+    invariant_factors: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    coordinates_a: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    coordinates_b: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if len(self.coordinates_a) != len(self.invariant_factors):
+            raise ValueError("coordinates_a length must match invariant_factors")
+        if len(self.coordinates_b) != len(self.invariant_factors):
+            raise ValueError("coordinates_b length must match invariant_factors")
+        return self
+
+
+class ElementOrderRequest(StrictModel):
+    invariant_factors: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    coordinates: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if len(self.coordinates) != len(self.invariant_factors):
+            raise ValueError("coordinates length must match invariant_factors")
+        if any(d <= 0 for d in self.invariant_factors):
+            raise ValueError("invariant factors must be positive")
+        return self
+
+
+class SubgroupGeneratedRequest(StrictModel):
+    invariant_factors: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    generators: tuple[tuple[int, ...], ...] = Field(
+        min_length=1, max_length=MAX_ORDERS
+    )
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if any(len(g) != len(self.invariant_factors) for g in self.generators):
+            raise ValueError("each generator must match invariant_factors length")
+        if any(d <= 0 for d in self.invariant_factors):
+            raise ValueError("invariant factors must be positive")
+        return self
+
+
+class QuotientRequest(StrictModel):
+    invariant_factors: tuple[int, ...] = Field(min_length=1, max_length=MAX_ORDERS)
+    subgroup_generators: tuple[tuple[int, ...], ...] = Field(
+        min_length=1, max_length=MAX_ORDERS
+    )
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if any(len(g) != len(self.invariant_factors) for g in self.subgroup_generators):
+            raise ValueError("each generator must match invariant_factors length")
+        if any(d <= 0 for d in self.invariant_factors):
+            raise ValueError("invariant factors must be positive")
+        return self
+
+
+# Results
+
+
+class PresentationNormalizeResult(StrictModel):
+    invariant_factors: tuple[int, ...]
+    order: int = Field(ge=1)
+    rank: int = Field(ge=0)
+    method: str = "SMithNormalForm"
+
+
+class ElementReduceResult(StrictModel):
+    reduced: tuple[int, ...]
+    method: str = "MODULAR_REDUCTION"
+
+
+class ElementEqualResult(StrictModel):
+    equal: bool
+    method: str = "MODULAR_COMPARISON"
+
+
+class ElementOrderResult(StrictModel):
+    order: int = Field(ge=1)
+    method: str = "LCM"
+
+
+class SubgroupGeneratedResult(StrictModel):
+    index: int = Field(ge=1)
+    coset_representatives: tuple[tuple[int, ...], ...] = ()
+    method: str = "COSET_ENUMERATION"
+
+
+class QuotientResult(StrictModel):
+    quotient_invariant_factors: tuple[int, ...] = ()
+    quotient_order: int = Field(ge=1)
+    method: str = "SMITH_NORMAL_FORM"

src/jacobian/math/finite_abelian_groups_v2/_operations.py

@@ -0,0 +1,169 @@
+"""Domain functions for finitely generated abelian group operations."""
+
+from __future__ import annotations
+
+from math import gcd, lcm
+
+from jacobian.math.finite_abelian_groups_v2._models import (
+    ElementEqualRequest,
+    ElementEqualResult,
+    ElementOrderRequest,
+    ElementOrderResult,
+    ElementReduceRequest,
+    ElementReduceResult,
+    PresentationNormalizeResult,
+    QuotientRequest,
+    QuotientResult,
+    SubgroupGeneratedRequest,
+    SubgroupGeneratedResult,
+)
+
+
+def compute_presentation_normalize(
+    invariant_factors: tuple[int, ...],
+) -> PresentationNormalizeResult:
+    from sympy import Matrix, diag
+    from sympy.matrices.normalforms import smith_normal_form
+
+    m = Matrix(diag(*invariant_factors))
+    smith = smith_normal_form(m, domain=None)
+    factors = tuple(int(smith[i, i]) for i in range(min(smith.rows, smith.cols)))
+
+    cleaned: list[int] = []
+    for f in factors:
+        if f > 1:
+            cleaned.append(f)
+
+    order = 1
+    for f in cleaned:
+        order *= f
+    if not cleaned:
+        order = 1
+
+    return PresentationNormalizeResult(
+        invariant_factors=tuple(cleaned),
+        order=order,
+        rank=0,
+    )
+
+
+def compute_element_reduce(request: ElementReduceRequest) -> ElementReduceResult:
+    reduced = tuple(
+        c % d if d > 0 else c
+        for c, d in zip(request.coordinates, request.invariant_factors, strict=True)
+    )
+    return ElementReduceResult(reduced=reduced)
+
+
+def compute_element_equal(request: ElementEqualRequest) -> ElementEqualResult:
+    reduced_a = tuple(
+        c % d if d > 0 else c
+        for c, d in zip(request.coordinates_a, request.invariant_factors, strict=True)
+    )
+    reduced_b = tuple(
+        c % d if d > 0 else c
+        for c, d in zip(request.coordinates_b, request.invariant_factors, strict=True)
+    )
+    return ElementEqualResult(equal=reduced_a == reduced_b)
+
+
+def compute_element_order(request: ElementOrderRequest) -> ElementOrderResult:
+    reduced = [
+        c % d if d > 0 else c
+        for c, d in zip(request.coordinates, request.invariant_factors, strict=True)
+    ]
+    order = 1
+    for coord, factor in zip(reduced, request.invariant_factors, strict=True):
+        if coord == 0:
+            continue
+        if factor == 0:
+            order = 0
+            break
+        elem_order = factor // gcd(coord, factor)
+        order = lcm(order, elem_order)
+
+    if order == 0:
+        return ElementOrderResult(order=1)
+
+    return ElementOrderResult(order=order)
+
+
+def compute_subgroup_generated(
+    request: SubgroupGeneratedRequest,
+) -> SubgroupGeneratedResult:
+    factors = request.invariant_factors
+    n = len(factors)
+
+    group_order = 1
+    for d in factors:
+        group_order *= d
+
+    generators = [
+        [c % d if d > 0 else c for c, d in zip(g, factors, strict=True)]
+        for g in request.generators
+    ]
+
+    subgroup: set[tuple[int, ...]] = {tuple([0] * n)}
+    queue = [tuple([0] * n)]
+    while queue:
+        current = queue.pop(0)
+        for gen in generators:
+            new_coord = tuple(
+                (current[i] + gen[i]) % factors[i] if factors[i] > 0 else current[i] + gen[i]
+                for i in range(n)
+            )
+            if new_coord not in subgroup:
+                subgroup.add(new_coord)
+                queue.append(new_coord)
+
+    subgroup_size = len(subgroup)
+    if subgroup_size == 0:
+        index = group_order
+    else:
+        index = group_order // subgroup_size if subgroup_size > 0 else group_order
+
+    return SubgroupGeneratedResult(index=index)
+
+
+def compute_quotient(request: QuotientRequest) -> QuotientResult:
+    """Compute G/H via Smith normal form of the presentation matrix.
+
+    G = Z/d_1 x ... x Z/d_n, H = <g_1, ..., g_m>.
+    The quotient G/H has presentation matrix [diag(d_1,...,d_n) | g_1 ... g_m]
+    reduced to Smith normal form.
+    """
+    from sympy import Matrix
+
+    n = len(request.invariant_factors)
+    d_matrix = Matrix.diag(*request.invariant_factors)
+    cols = []
+    for gen in request.subgroup_generators:
+        cols.append(list(gen))
+    gen_matrix = Matrix(cols).T if cols else Matrix.zeros(n, 0)
+    augmented = d_matrix.row_join(gen_matrix)
+
+    # Compute Smith normal form manually using integer row/column operations
+
+    # Use sympy's smith_normal_form from the smith module
+    try:
+        from sympy.matrices.normalforms import smith_normal_form
+        smith = smith_normal_form(augmented, domain=None)
+    except (ImportError, AttributeError):
+        smith = augmented
+
+    factors = []
+    for i in range(min(smith.rows, smith.cols)):
+        d = abs(int(smith[i, i]))
+        if d > 1:
+            factors.append(d)
+
+    order = 1
+    for f in factors:
+        order *= f
+    if not factors:
+        order = 1
+
+    return QuotientResult(
+        quotient_invariant_factors=tuple(factors),
+        quotient_order=order,
+    )