feat(math): add plane algebraic curve operations (#1877)

Add plane_algebraic_curves domain with 3 operations: affine curve
check, projective closure via homogenization, and affine chart
extraction via dehomogenization. Uses SymPy for exact polynomial
computation.

Closes #1877

Author: morluto

src/jacobian/catalog/builtins.py

@@ -12,6 +12,12 @@
 from jacobian.math.additive_combinatorics._tools import (
     TOOLS as ADDITIVE_COMBINATORICS_TOOLS,
 )
+from jacobian.math.plane_algebraic_curves._admission import (
+    ADMISSIONS as PLANE_ALGEBRAIC_CURVES_ADMISSIONS,
+)
+from jacobian.math.plane_algebraic_curves._tools import (
+    TOOLS as PLANE_ALGEBRAIC_CURVES_TOOLS,
+)
 from jacobian.math.algebraic_combinatorics._admission import (
     ADMISSIONS as ALGEBRAIC_COMBINATORICS_ADMISSIONS,
 )
@@ -339,6 +345,7 @@
     *ELECTRICAL_NETWORKS_TOOLS,
     *REGULAR_LANGUAGES_TOOLS,
     *ALGEBRAIC_COMBINATORICS_TOOLS,
+    *PLANE_ALGEBRAIC_CURVES_TOOLS,
     *REAL_ALGEBRA_TOOLS,
     *FINITE_METRIC_SPACES_TOOLS,
     *PETRI_NET_TOOLS,
@@ -351,6 +358,7 @@
 _RAW_ADMISSIONS: tuple[OperationAdmission, ...] = (
     *ADDITIVE_COMBINATORICS_ADMISSIONS,
     *ALGEBRAIC_COMBINATORICS_ADMISSIONS,
+    *PLANE_ALGEBRAIC_CURVES_ADMISSIONS,
     *ANALYSIS_ADMISSIONS,
     *ARITHMETIC_ADMISSIONS,
     *ARITHMETIC_COUNTING_ADMISSIONS,

src/jacobian/math/plane_algebraic_curves/__init__.py

@@ -0,0 +1,3 @@
+"""Plane algebraic curve operations."""
+
+__all__: list[str] = []

src/jacobian/math/plane_algebraic_curves/_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(
+        "algebraic_geometry.affine_plane_curve.check",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "algebraic_geometry.plane_curve.projective_closure.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "algebraic_geometry.projective_curve.affine_chart.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+)

src/jacobian/math/plane_algebraic_curves/_models.py

@@ -0,0 +1,53 @@
+"""Typed wire contracts for plane algebraic curve operations."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from jacobian._models import StrictModel
+
+MAX_VARS = 3
+MAX_COEFF = 4096
+
+
+class AffineCurveRequest(StrictModel):
+    """An affine plane curve f(x, y) = 0."""
+
+    variables: tuple[str, ...] = Field(min_length=2, max_length=2)
+    polynomial: str = Field(min_length=1, max_length=MAX_COEFF)
+
+
+class ProjectiveClosureRequest(StrictModel):
+    """Compute the projective closure of an affine curve."""
+
+    variables: tuple[str, ...] = Field(min_length=2, max_length=2)
+    polynomial: str = Field(min_length=1, max_length=MAX_COEFF)
+
+
+class AffineChartRequest(StrictModel):
+    """Extract an affine chart from a projective curve."""
+
+    variables: tuple[str, ...] = Field(min_length=3, max_length=3)
+    polynomial: str = Field(min_length=1, max_length=MAX_COEFF)
+    chart_variable: str = Field(min_length=1, max_length=64)
+
+
+# Results
+
+
+class AffineCurveResult(StrictModel):
+    is_valid: bool
+    degree: int = Field(ge=0)
+    method: str = "SYmpy_CURVE_CHECK"
+
+
+class ProjectiveClosureResult(StrictModel):
+    polynomial: str
+    variables: tuple[str, ...]
+    method: str = "HOMOGENIZATION"
+
+
+class AffineChartResult(StrictModel):
+    polynomial: str
+    variables: tuple[str, ...]
+    method: str = "DEhomOGENIZATION"

src/jacobian/math/plane_algebraic_curves/_operations.py

@@ -0,0 +1,74 @@
+"""Domain functions for plane algebraic curve operations."""
+
+from __future__ import annotations
+
+import sympy
+
+from jacobian.math.plane_algebraic_curves._models import (
+    AffineChartRequest,
+    AffineChartResult,
+    AffineCurveRequest,
+    AffineCurveResult,
+    ProjectiveClosureRequest,
+    ProjectiveClosureResult,
+)
+
+
+def compute_affine_curve_check(request: AffineCurveRequest) -> AffineCurveResult:
+    """Check that a polynomial defines a valid affine plane curve."""
+    var_symbols = sympy.symbols(request.variables)
+    var_map = dict(zip(request.variables, var_symbols, strict=True))
+    poly = sympy.sympify(request.polynomial, locals=var_map)
+    degree = int(sympy.total_degree(poly))
+    is_valid = poly != 0
+    return AffineCurveResult(
+        is_valid=is_valid,
+        degree=degree,
+    )
+
+
+def compute_projective_closure(
+    request: ProjectiveClosureRequest,
+) -> ProjectiveClosureResult:
+    """Compute the projective closure by homogenizing with a new variable."""
+    var_symbols = list(sympy.symbols(request.variables))
+    var_map = dict(zip(request.variables, var_symbols, strict=True))
+    poly = sympy.sympify(request.polynomial, locals=var_map)
+    z = sympy.Symbol("z")
+    terms = sympy.Poly(poly, *var_symbols)
+    degree = terms.total_degree()
+    new_terms = []
+    for monom, coeff in terms.as_dict().items():
+        total_deg = sum(monom)
+        factor = z ** (degree - total_deg)
+        term = coeff
+        for i, exp in enumerate(monom):
+            term *= var_symbols[i] ** exp
+        new_terms.append(term * factor)
+    homogenized = sympy.expand(sum(new_terms))
+    return ProjectiveClosureResult(
+        polynomial=str(homogenized),
+        variables=(*request.variables, "z"),
+    )
+
+
+def compute_affine_chart(request: AffineChartRequest) -> AffineChartResult:
+    """Extract an affine chart by dehomogenizing at the chart variable."""
+    var_symbols = list(sympy.symbols(request.variables))
+    var_map = dict(zip(request.variables, var_symbols, strict=True))
+    chart_var = sympy.Symbol(request.chart_variable)
+
+    if request.chart_variable not in request.variables:
+        raise ValueError("chart_variable must be one of the projective variables")
+
+    poly = sympy.sympify(request.polynomial, locals=var_map)
+    idx = request.variables.index(request.chart_variable)
+    other_vars = [v for i, v in enumerate(request.variables) if i != idx]
+
+    dehomogenized = poly.subs(chart_var, 1)
+    dehomogenized = sympy.expand(dehomogenized)
+
+    return AffineChartResult(
+        polynomial=str(dehomogenized),
+        variables=tuple(other_vars),
+    )

src/jacobian/math/plane_algebraic_curves/_tools.py

@@ -0,0 +1,117 @@
+"""Plane algebraic curve 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.plane_algebraic_curves._models import (
+    AffineChartRequest,
+    AffineChartResult,
+    AffineCurveRequest,
+    AffineCurveResult,
+    ProjectiveClosureRequest,
+    ProjectiveClosureResult,
+)
+from jacobian.math.plane_algebraic_curves._operations import (
+    compute_affine_chart,
+    compute_affine_curve_check,
+    compute_projective_closure,
+)
+
+
+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(
+        "algebraic_geometry.affine_plane_curve.check",
+        "Check an affine plane curve",
+        "Check that a polynomial defines a valid affine plane curve f(x,y)=0 "
+        "and return its degree.",
+        AffineCurveRequest,
+        AffineCurveResult,
+        compute_affine_curve_check,
+        "algebraic-geometry",
+        "affine-curve",
+        "exact",
+        examples=(
+            example(
+                "circle",
+                "Check the unit circle x^2 + y^2 - 1 = 0.",
+                {
+                    "variables": ["x", "y"],
+                    "polynomial": "x**2 + y**2 - 1",
+                },
+            ),
+        ),
+    ),
+    _op(
+        "algebraic_geometry.plane_curve.projective_closure.compute",
+        "Compute the projective closure of an affine curve",
+        "Homogenize an affine plane curve to obtain its projective closure.",
+        ProjectiveClosureRequest,
+        ProjectiveClosureResult,
+        compute_projective_closure,
+        "algebraic-geometry",
+        "projective-closure",
+        "exact",
+        examples=(
+            example(
+                "circle_closure",
+                "Projective closure of x^2 + y^2 - 1.",
+                {
+                    "variables": ["x", "y"],
+                    "polynomial": "x**2 + y**2 - 1",
+                },
+            ),
+        ),
+    ),
+    _op(
+        "algebraic_geometry.projective_curve.affine_chart.compute",
+        "Extract an affine chart from a projective curve",
+        "Dehomogenize a projective curve at the given chart variable by "
+        "setting that variable to 1.",
+        AffineChartRequest,
+        AffineChartResult,
+        compute_affine_chart,
+        "algebraic-geometry",
+        "affine-chart",
+        "exact",
+        examples=(
+            example(
+                "chart_z",
+                "Extract the z=1 chart of x^2 + y^2 - z^2.",
+                {
+                    "variables": ["x", "y", "z"],
+                    "polynomial": "x**2 + y**2 - z**2",
+                    "chart_variable": "z",
+                },
+            ),
+        ),
+    ),
+)
+
+__all__ = ["TOOLS"]

tests/catalog/operation_schema_snapshots/plane_algebraic_curves.json

@@ -0,0 +1,18 @@
+{
+    "catalog_version": "1",
+    "domain": "plane_algebraic_curves",
+    "operations": {
+        "algebraic_geometry.affine_plane_curve.check": {
+            "input_schema": "sha256:3da4e24fb42e02ef27a2b86823396546c65f4eda6ae2181ff2296e73d6ead0d6",
+            "output_schema": "sha256:ebbe1cbf85ae3ac33a346cfd5457d80a87ec979f9849a5e340d3f79f06e762b9"
+        },
+        "algebraic_geometry.plane_curve.projective_closure.compute": {
+            "input_schema": "sha256:38f21b9ec38af2258ddecd2a8273562dbb725463e5df19eea5c5b889de6227e6",
+            "output_schema": "sha256:b18e7f7351c526592ca42bed59a186f182beedc167dcacbdbcfc11216ed775a3"
+        },
+        "algebraic_geometry.projective_curve.affine_chart.compute": {
+            "input_schema": "sha256:dbc389f87c55719512a31608d7108a0047cad7e78ddf8b049c3ace374a036a72",
+            "output_schema": "sha256:476deb3413dde8691cfec3fc9c965af5feac7278e8d6ebc471b5f32f6fb7fec9"
+        }
+    }
+}

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/plane_algebraic_curves/__init__.py

@@ -0,0 +1,49 @@
+"""Tests for plane algebraic curve operations."""
+
+from jacobian.math.plane_algebraic_curves._models import (
+    AffineChartRequest,
+    AffineCurveRequest,
+    ProjectiveClosureRequest,
+)
+from jacobian.math.plane_algebraic_curves._operations import (
+    compute_affine_chart,
+    compute_affine_curve_check,
+    compute_projective_closure,
+)
+from jacobian.math.plane_algebraic_curves._tools import TOOLS
+
+
+def test_catalog_contains_only_audited_operations() -> None:
+    assert {tool.operation_id for tool in TOOLS} == {
+        "algebraic_geometry.affine_plane_curve.check",
+        "algebraic_geometry.plane_curve.projective_closure.compute",
+        "algebraic_geometry.projective_curve.affine_chart.compute",
+    }
+
+
+def test_affine_curve_check_circle() -> None:
+    request = AffineCurveRequest(
+        variables=("x", "y"), polynomial="x**2 + y**2 - 1"
+    )
+    result = compute_affine_curve_check(request)
+    assert result.is_valid is True
+    assert result.degree == 2
+
+
+def test_projective_closure_circle() -> None:
+    request = ProjectiveClosureRequest(
+        variables=("x", "y"), polynomial="x**2 + y**2 - 1"
+    )
+    result = compute_projective_closure(request)
+    assert "z" in result.polynomial
+
+
+def test_affine_chart_circle() -> None:
+    request = AffineChartRequest(
+        variables=("x", "y", "z"),
+        polynomial="x**2 + y**2 - z**2",
+        chart_variable="z",
+    )
+    result = compute_affine_chart(request)
+    assert result.polynomial == "x**2 + y**2 - 1"
+    assert result.variables == ("x", "y")