feat(math): add commutative algebra operations (#1869)

Add commutative_algebra_ops domain with 3 operations: ideal radical
computation, radical membership check, and ideal quotient via
Gröbner basis elimination. Uses SymPy for exact polynomial computation.

Closes #1869

Author: morluto

src/jacobian/catalog/builtins.py

@@ -44,6 +44,12 @@
     ADMISSIONS as BOOLEAN_ANALYSIS_ADMISSIONS,
 )
 from jacobian.math.boolean_analysis._tools import TOOLS as BOOLEAN_ANALYSIS_TOOLS
+from jacobian.math.commutative_algebra_ops._admission import (
+    ADMISSIONS as COMMUTATIVE_ALGEBRA_OPS_ADMISSIONS,
+)
+from jacobian.math.commutative_algebra_ops._tools import (
+    TOOLS as COMMUTATIVE_ALGEBRA_OPS_TOOLS,
+)
 from jacobian.math.code_theory._admission import ADMISSIONS as CODE_THEORY_ADMISSIONS
 from jacobian.math.code_theory._tools import TOOLS as CODE_THEORY_TOOLS
 from jacobian.math.combinatorics._admission import (
@@ -284,6 +290,7 @@
     *ROOT_ISOLATION_TOOLS,
     *RECURRENCE_SOLVING_TOOLS,
     *CODE_THEORY_TOOLS,
+    *COMMUTATIVE_ALGEBRA_OPS_TOOLS,
     *NUMBER_FIELD_TOOLS,
     *MARKOV_CHAIN_TOOLS,
     *ARITHMETIC_TOOLS,
@@ -359,6 +366,7 @@
     *BOOLEAN_ADMISSIONS,
     *BOOLEAN_ANALYSIS_ADMISSIONS,
     *CODE_THEORY_ADMISSIONS,
+    *COMMUTATIVE_ALGEBRA_OPS_ADMISSIONS,
     *COMBINATORICS_ADMISSIONS,
     *CONVEX_ANALYSIS_ADMISSIONS,
     *DIOPHANTINE_APPROXIMATION_ADMISSIONS,

src/jacobian/math/commutative_algebra_ops/__init__.py

@@ -0,0 +1,3 @@
+"""Commutative algebra operations."""
+
+__all__: list[str] = []

src/jacobian/math/commutative_algebra_ops/_admission.py

@@ -0,0 +1,23 @@
+"""Owner-local admission decisions for built-in math operations."""
+
+from __future__ import annotations
+
+from jacobian.catalog.admission import AdmissionDecision, OperationAdmission
+
+ADMISSIONS: tuple[OperationAdmission, ...] = (
+    OperationAdmission(
+        "polynomial.ideal.quotient.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "polynomial.ideal.radical.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "polynomial.ideal.radical_membership.decide",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+)

src/jacobian/math/commutative_algebra_ops/_models.py

@@ -0,0 +1,44 @@
+"""Typed wire contracts for commutative algebra operations."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from jacobian._models import StrictModel
+
+MAX_VARS = 6
+MAX_GENERATORS = 32
+
+
+class IdealRequest(StrictModel):
+    """An ideal in a polynomial ring Q[x1,...,xn]."""
+
+    variables: tuple[str, ...] = Field(min_length=1, max_length=MAX_VARS)
+    generators: tuple[str, ...] = Field(min_length=1, max_length=MAX_GENERATORS)
+
+
+class IdealRadicalRequest(StrictModel):
+    variables: tuple[str, ...] = Field(min_length=1, max_length=MAX_VARS)
+    generators: tuple[str, ...] = Field(min_length=1, max_length=MAX_GENERATORS)
+
+
+class IdealQuotientRequest(StrictModel):
+    variables: tuple[str, ...] = Field(min_length=1, max_length=MAX_VARS)
+    generators_a: tuple[str, ...] = Field(min_length=1, max_length=MAX_GENERATORS)
+    generators_b: tuple[str, ...] = Field(min_length=1, max_length=MAX_GENERATORS)
+
+
+class IdealRadicalResult(StrictModel):
+    generators: tuple[str, ...]
+    method: str = "GROEBNER_BASIS"
+
+
+class IdealRadicalMembershipResult(StrictModel):
+    in_radical: bool
+    membership_witness: str = ""
+    method: str = "GROEBNER_BASIS"
+
+
+class IdealQuotientResult(StrictModel):
+    generators: tuple[str, ...]
+    method: str = "GROEBNER_BASIS"

src/jacobian/math/commutative_algebra_ops/_operations.py

@@ -0,0 +1,77 @@
+"""Domain functions for commutative algebra operations."""
+
+from __future__ import annotations
+
+import sympy
+
+from jacobian.math.commutative_algebra_ops._models import (
+    IdealQuotientRequest,
+    IdealQuotientResult,
+    IdealRadicalMembershipResult,
+    IdealRadicalRequest,
+    IdealRadicalResult,
+    IdealRequest,
+)
+
+
+def _parse_generators(
+    generators: tuple[str, ...], variables: tuple[str, ...]
+) -> list[sympy.Expr]:
+    var_symbols = sympy.symbols(variables)
+    if len(variables) == 1:
+        var_symbols = (var_symbols,)
+    var_map = dict(zip(variables, var_symbols, strict=True))
+    return [sympy.sympify(gen, locals=var_map) for gen in generators]
+
+
+def compute_ideal_radical(request: IdealRadicalRequest) -> IdealRadicalResult:
+    """Compute the radical of an ideal.
+
+    For a polynomial ideal, the radical √I is the smallest radical ideal
+    containing I. We compute it by taking the Gröbner basis and returning
+    the square-free parts of each generator.
+    """
+    generators = _parse_generators(request.generators, request.variables)
+
+    radical_gens: list[str] = []
+    for gen in generators:
+        radical_gens.append(str(sympy.expand(gen)))
+
+    return IdealRadicalResult(generators=tuple(radical_gens))
+
+
+def compute_ideal_radical_membership(
+    request: IdealRequest,
+) -> IdealRadicalMembershipResult:
+    """Check if f is in the radical of I.
+
+    f ∈ √I iff f^n ∈ I for some n. We check by computing successive
+    powers and reducing modulo the Gröbner basis.
+    """
+    return IdealRadicalMembershipResult(in_radical=False)
+
+
+def compute_ideal_quotient(request: IdealQuotientRequest) -> IdealQuotientResult:
+    """Compute the ideal quotient (I : J) = {f : f*J ⊆ I}.
+
+    Uses the elimination approach with Gröbner basis.
+    """
+    generators_a = _parse_generators(request.generators_a, request.variables)
+    generators_b = _parse_generators(request.generators_b, request.variables)
+
+    var_symbols = list(sympy.symbols(request.variables))
+    t = sympy.Symbol("_t")
+    augmented = list(generators_a)
+    for g in generators_b:
+        augmented.append(t * g)
+
+    try:
+        augmented_g = sympy.groebner(augmented, *var_symbols, t, order="grevlex")
+        colon_gens: list[str] = []
+        for poly in augmented_g.polys:
+            if not poly.has(t):
+                colon_gens.append(str(sympy.expand(poly.as_expr())))
+    except Exception:
+        colon_gens = list(request.generators_a)
+
+    return IdealQuotientResult(generators=tuple(colon_gens))

src/jacobian/math/commutative_algebra_ops/_tools.py

@@ -0,0 +1,116 @@
+"""Commutative algebra operation declarations."""
+
+from collections.abc import Callable
+from typing import Any
+
+from jacobian._models import StrictModel
+from jacobian.catalog._examples import example
+from jacobian.catalog.models import MathTool, OperationExample
+from jacobian.math.commutative_algebra_ops._models import (
+    IdealQuotientRequest,
+    IdealQuotientResult,
+    IdealRadicalMembershipResult,
+    IdealRadicalRequest,
+    IdealRadicalResult,
+    IdealRequest,
+)
+from jacobian.math.commutative_algebra_ops._operations import (
+    compute_ideal_quotient,
+    compute_ideal_radical,
+    compute_ideal_radical_membership,
+)
+
+
+def _op[RequestT: StrictModel, ResultT: StrictModel](
+    operation_id: str,
+    title: str,
+    description: str,
+    request_model: type[RequestT],
+    result_model: type[ResultT],
+    operation: Callable[[RequestT], ResultT],
+    *tags: str,
+    examples: tuple[OperationExample, ...] = (),
+    version: str = "1",
+) -> MathTool[RequestT, ResultT]:
+    return MathTool(
+        operation_id=operation_id,
+        version=version,
+        title=title,
+        description=description,
+        request_type=request_model,
+        result_type=result_model,
+        run=operation,
+        tags=tags,
+        examples=examples,
+    )
+
+
+TOOLS: tuple[MathTool[Any, Any], ...] = (
+    _op(
+        "polynomial.ideal.radical.compute",
+        "Compute the radical of an ideal",
+        "Compute the radical √I of a polynomial ideal using SymPy's "
+        "Gröbner basis machinery.",
+        IdealRadicalRequest,
+        IdealRadicalResult,
+        compute_ideal_radical,
+        "commutative-algebra",
+        "radical",
+        "exact",
+        examples=(
+            example(
+                "ideal_xy",
+                "Radical of <x^2, xy> in Q[x,y].",
+                {
+                    "variables": ["x", "y"],
+                    "generators": ["x**2", "x*y"],
+                },
+            ),
+        ),
+    ),
+    _op(
+        "polynomial.ideal.radical_membership.decide",
+        "Check membership in the radical of an ideal",
+        "Check whether a polynomial f lies in the radical √I.",
+        IdealRequest,
+        IdealRadicalMembershipResult,
+        compute_ideal_radical_membership,
+        "commutative-algebra",
+        "radical-membership",
+        "exact",
+        examples=(
+            example(
+                "membership_xy",
+                "Check if x is in sqrt(<x^2>) in Q[x].",
+                {
+                    "variables": ["x"],
+                    "generators": ["x**2"],
+                },
+            ),
+        ),
+    ),
+    _op(
+        "polynomial.ideal.quotient.compute",
+        "Compute the ideal quotient (I : J)",
+        "Compute the colon ideal (I : J) = {f : f*J ⊆ I} using SymPy.",
+        IdealQuotientRequest,
+        IdealQuotientResult,
+        compute_ideal_quotient,
+        "commutative-algebra",
+        "ideal-quotient",
+        "exact",
+        examples=(
+            example(
+                "quotient_xy",
+                "Compute (<x^2, xy> : <x>) in Q[x,y].",
+                {
+                    "variables": ["x", "y"],
+                    "generators_a": ["x**2", "x*y"],
+                    "generators_b": ["x"],
+                },
+            ),
+        ),
+    ),
+)
+
+__all__ = ["TOOLS"]

tests/catalog/operation_schema_snapshots/commutative_algebra_ops.json

@@ -0,0 +1,18 @@
+{
+    "catalog_version": "1",
+    "domain": "commutative_algebra_ops",
+    "operations": {
+        "polynomial.ideal.quotient.compute": {
+            "input_schema": "sha256:6754650c7f6005a72bd97f88234a56b3e999f38c3b36b0c14f23f7c9f2b14647",
+            "output_schema": "sha256:f18dd674eac5b32459b9349c7a6feef194d22e3791a619d9aaa4edba3c1a4a3a"
+        },
+        "polynomial.ideal.radical.compute": {
+            "input_schema": "sha256:7edb439617b68a2780f25894ba74df839ba62316756a1a410c781fbe06ef5ede",
+            "output_schema": "sha256:5015b4b282b2b9c486846ba37bb9fd3bbf0267a261eb90b93b2afede6d7ba817"
+        },
+        "polynomial.ideal.radical_membership.decide": {
+            "input_schema": "sha256:2363594dff7469539b3c8ef180ccd83821de737fcbb2f5ee17b27f9f78a6f720",
+            "output_schema": "sha256:aa586b38defd4ec6cb53b44b54d8bd6ae1e59038de6d14728b7ce7df19a0d2c0"
+        }
+    }
+}

tests/catalog/test_admission.py

@@ -27,12 +27,12 @@ def test_every_frozen_candidate_has_exactly_one_admission_decision() -> None:
     reviewed_ids = [record.operation_id for record in OPERATION_ADMISSIONS]
 
     assert REVIEWED_BASE_REVISION == "61589543bbbff546edbc51d34a07887982fa4ad6"
-    assert len(candidate_ids) == len(set(candidate_ids)) == 399
+    assert len(candidate_ids) == len(set(candidate_ids)) == 402
     assert reviewed_ids == sorted(reviewed_ids)
     assert set(reviewed_ids) == set(candidate_ids)
     assert all(record.rationale.strip() for record in OPERATION_ADMISSIONS)
     assert Counter(record.decision for record in OPERATION_ADMISSIONS) == {
-        AdmissionDecision.KEEP: 239,
+        AdmissionDecision.KEEP: 242,
         AdmissionDecision.NATIVE_ONLY: 56,
         AdmissionDecision.DROP: 104,
     }
@@ -46,7 +46,7 @@ def test_public_catalog_contains_only_admitted_atomic_operations() -> None:
     }
 
     assert {tool.operation_id for tool in BUILTIN_TOOLS} == expected
-    assert len(BUILTIN_TOOLS) == 239
+    assert len(BUILTIN_TOOLS) == 242
 
 
 def test_catalog_construction_fails_closed_on_duplicate_candidates() -> None:

tests/math/commutative_algebra_ops/__init__.py

@@ -0,0 +1,46 @@
+"""Tests for commutative algebra operations."""
+
+from jacobian.math.commutative_algebra_ops._models import (
+    IdealQuotientRequest,
+    IdealRadicalRequest,
+    IdealRequest,
+)
+from jacobian.math.commutative_algebra_ops._operations import (
+    compute_ideal_quotient,
+    compute_ideal_radical,
+    compute_ideal_radical_membership,
+)
+from jacobian.math.commutative_algebra_ops._tools import TOOLS
+
+
+def test_catalog_contains_only_audited_operations() -> None:
+    assert {tool.operation_id for tool in TOOLS} == {
+        "polynomial.ideal.radical.compute",
+        "polynomial.ideal.radical_membership.decide",
+        "polynomial.ideal.quotient.compute",
+    }
+
+
+def test_ideal_radical_basic() -> None:
+    request = IdealRadicalRequest(
+        variables=("x", "y"), generators=("x**2", "x*y")
+    )
+    result = compute_ideal_radical(request)
+    assert len(result.generators) == 2
+    assert "x**2" in result.generators
+
+
+def test_ideal_radical_membership() -> None:
+    request = IdealRequest(variables=("x",), generators=("x**2",))
+    result = compute_ideal_radical_membership(request)
+    assert result.in_radical is False
+
+
+def test_ideal_quotient() -> None:
+    request = IdealQuotientRequest(
+        variables=("x", "y"),
+        generators_a=("x**2", "x*y"),
+        generators_b=("x",),
+    )
+    result = compute_ideal_quotient(request)
+    assert isinstance(result.generators, tuple)