feat(math): add quadratic forms domain with evaluate, discriminant, signature

Create the quadratic_forms domain with three operations:

- quadratic_form.evaluate.compute: exact q(x) = x^T A x for an
  integral symmetric matrix and integer vector.
- quadratic_form.discriminant.compute: exact det(A) via SymPy
  integer matrix computation.
- quadratic_form.signature.compute: inertia (n_pos, n_neg, n_zero)
  via SymPy eigenvalue computation, with definiteness classification.

Partially addresses #1841.

Author: morluto

src/jacobian/catalog/builtins.py

@@ -238,6 +238,10 @@
 from jacobian.math.posets._tools import TOOLS as POSETS_TOOLS
 from jacobian.math.probability._admission import ADMISSIONS as PROBABILITY_ADMISSIONS
 from jacobian.math.probability._tools import TOOLS as PROBABILITY_TOOLS
+from jacobian.math.quadratic_forms._admission import (
+    ADMISSIONS as QUADRATIC_FORMS_ADMISSIONS,
+)
+from jacobian.math.quadratic_forms._tools import TOOLS as QUADRATIC_FORMS_TOOLS
 from jacobian.math.recurrence_solving._admission import (
     ADMISSIONS as RECURRENCE_SOLVING_ADMISSIONS,
 )
@@ -274,6 +278,7 @@
 from jacobian.math.words._tools import TOOLS as WORDS_TOOLS
 
 _BUILTIN_CANDIDATES: MathTools = (
+    *QUADRATIC_FORMS_TOOLS,
     *BOOLEAN_TOOLS,
     *GROUP_TOOLS,
     *GRAPH_COLORING_OPS_TOOLS,
@@ -411,6 +416,7 @@
     *POLYNOMIALS_REAL_ALGEBRA_ADMISSIONS,
     *POSETS_ADMISSIONS,
     *PROBABILITY_ADMISSIONS,
+    *QUADRATIC_FORMS_ADMISSIONS,
     *RECURRENCE_SOLVING_ADMISSIONS,
     *REGULAR_LANGUAGES_ADMISSIONS,
     *ROOT_ISOLATION_ADMISSIONS,

src/jacobian/math/quadratic_forms/__init__.py

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

src/jacobian/math/quadratic_forms/_admission.py

@@ -0,0 +1,21 @@
+"""Owner-local admission decisions for built-in math operations."""
+
+from jacobian.catalog.admission import AdmissionDecision, OperationAdmission
+
+ADMISSIONS: tuple[OperationAdmission, ...] = (
+    OperationAdmission(
+        "quadratic_form.evaluate.compute",
+        AdmissionDecision.KEEP,
+        "exact integer evaluation q(x) = x^T A x for an integral quadratic form",
+    ),
+    OperationAdmission(
+        "quadratic_form.discriminant.compute",
+        AdmissionDecision.KEEP,
+        "exact determinant of the symmetric matrix via SymPy",
+    ),
+    OperationAdmission(
+        "quadratic_form.signature.compute",
+        AdmissionDecision.KEEP,
+        "exact inertia and definiteness classification via SymPy eigenvalues",
+    ),
+)

src/jacobian/math/quadratic_forms/_models.py

@@ -0,0 +1,81 @@
+"""Typed wire contracts for quadratic form operations."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from jacobian._models import StrictModel
+
+MAX_DIM = 10
+
+
+class SymmetricMatrix(StrictModel):
+    """A symmetric integer matrix representing a quadratic form."""
+
+    matrix: tuple[tuple[int, ...], ...] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def require_symmetric_square(self) -> Self:
+        n = len(self.matrix)
+        if n > MAX_DIM:
+            raise ValueError(f"dimension must not exceed {MAX_DIM}")
+        for row in self.matrix:
+            if len(row) != n:
+                raise ValueError("matrix must be square")
+        for i in range(n):
+            for j in range(n):
+                if self.matrix[i][j] != self.matrix[j][i]:
+                    raise ValueError("matrix must be symmetric")
+        return self
+
+
+class EvaluationRequest(StrictModel):
+    """Evaluate q(x) = x^T A x for an integer vector x."""
+
+    form: SymmetricMatrix
+    vector: tuple[int, ...] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def require_matching_dimension(self) -> Self:
+        if len(self.vector) != len(self.form.matrix):
+            raise ValueError("vector dimension must match form dimension")
+        return self
+
+
+class DiscriminantRequest(StrictModel):
+    """Compute the discriminant of a quadratic form."""
+
+    form: SymmetricMatrix
+
+
+class SignatureRequest(StrictModel):
+    """Compute the signature (n_pos, n_neg, n_zero) of a quadratic form."""
+
+    form: SymmetricMatrix
+
+
+class EvaluationResult(StrictModel):
+    """The value q(x) = x^T A x."""
+
+    value: int
+    dimension: int
+
+
+class DiscriminantResult(StrictModel):
+    """The discriminant det(A) of a quadratic form."""
+
+    discriminant: int
+    dimension: int
+
+
+class SignatureResult(StrictModel):
+    """The inertia (positive, negative, zero eigenvalue counts) of a form."""
+
+    n_positive: int
+    n_negative: int
+    n_zero: int
+    is_positive_definite: bool
+    is_negative_definite: bool
+    is_indefinite: bool

src/jacobian/math/quadratic_forms/_operations.py

@@ -0,0 +1,67 @@
+"""Exact quadratic form operations using SymPy for linear algebra."""
+
+from jacobian.math.quadratic_forms._models import (
+    DiscriminantRequest,
+    DiscriminantResult,
+    EvaluationRequest,
+    EvaluationResult,
+    SignatureRequest,
+    SignatureResult,
+)
+
+
+def evaluate_form(request: EvaluationRequest) -> EvaluationResult:
+    """Evaluate q(x) = x^T A x for an integer vector x."""
+    a = request.form.matrix
+    x = request.vector
+    n = len(a)
+    value = 0
+    for i in range(n):
+        for j in range(n):
+            value += a[i][j] * x[i] * x[j]
+    return EvaluationResult(value=value, dimension=n)
+
+
+def compute_discriminant(request: DiscriminantRequest) -> DiscriminantResult:
+    """Compute det(A) for the symmetric matrix A."""
+    from sympy import Matrix
+
+    a = request.form.matrix
+    n = len(a)
+    m = Matrix(a)
+    det = int(m.det())
+    return DiscriminantResult(discriminant=det, dimension=n)
+
+
+def compute_signature(request: SignatureRequest) -> SignatureResult:
+    """Compute the signature (inertia) of a quadratic form using SymPy eigenvalues."""
+    from sympy import Matrix
+
+    a = request.form.matrix
+    n = len(a)
+    m = Matrix(a)
+
+    # Compute eigenvalues
+    eigenvals = m.eigenvals()
+
+    n_positive = 0
+    n_negative = 0
+    n_zero = 0
+
+    for eigenval, mult in eigenvals.items():
+        eigenval_int = int(eigenval)
+        if eigenval_int > 0:
+            n_positive += mult
+        elif eigenval_int < 0:
+            n_negative += mult
+        else:
+            n_zero += mult
+
+    return SignatureResult(
+        n_positive=n_positive,
+        n_negative=n_negative,
+        n_zero=n_zero,
+        is_positive_definite=n_positive == n and n_zero == 0 and n_negative == 0,
+        is_negative_definite=n_negative == n and n_zero == 0 and n_positive == 0,
+        is_indefinite=n_positive > 0 and n_negative > 0,
+    )

src/jacobian/math/quadratic_forms/_tools.py

@@ -0,0 +1,112 @@
+"""Quadratic form 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.quadratic_forms._models import (
+    DiscriminantRequest,
+    DiscriminantResult,
+    EvaluationRequest,
+    EvaluationResult,
+    SignatureRequest,
+    SignatureResult,
+)
+from jacobian.math.quadratic_forms._operations import (
+    compute_discriminant,
+    compute_signature,
+    evaluate_form,
+)
+
+
+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, ...] = (),
+) -> MathTool[RequestT, ResultT]:
+    return MathTool(
+        operation_id=operation_id,
+        version="1",
+        title=title,
+        description=description,
+        request_type=request_model,
+        result_type=result_model,
+        run=operation,
+        tags=tags,
+        examples=examples,
+    )
+
+
+_FORM_2D = {"matrix": [[1, 0], [0, 1]]}
+
+TOOLS: tuple[MathTool[Any, Any], ...] = (
+    _op(
+        "quadratic_form.evaluate.compute",
+        "Evaluate a quadratic form q(x) = x^T A x",
+        "Compute the exact integer value q(x) = x^T A x for an "
+        "integral quadratic form (symmetric matrix) and integer vector.",
+        EvaluationRequest,
+        EvaluationResult,
+        evaluate_form,
+        "algebra",
+        "quadratic-form",
+        "exact",
+        examples=(
+            example(
+                "identity_2d_at_3_4",
+                "Evaluate x^T I x at (3, 4); "
+                "the matrix must be symmetric and the vector length must match.",
+                {"form": _FORM_2D, "vector": [3, 4]},
+            ),
+        ),
+    ),
+    _op(
+        "quadratic_form.discriminant.compute",
+        "Compute the discriminant det(A) of a quadratic form",
+        "Compute the exact determinant of the symmetric matrix "
+        "representing the quadratic form, using SymPy for exact "
+        "integer matrix computation.",
+        DiscriminantRequest,
+        DiscriminantResult,
+        compute_discriminant,
+        "algebra",
+        "quadratic-form",
+        "exact",
+        examples=(
+            example(
+                "identity_2d_discriminant",
+                "Compute det(I_2) = 1; the matrix must be symmetric.",
+                {"form": _FORM_2D},
+            ),
+        ),
+    ),
+    _op(
+        "quadratic_form.signature.compute",
+        "Compute the signature/inertia of a quadratic form",
+        "Compute the inertia (n_positive, n_negative, n_zero) of a "
+        "quadratic form using SymPy eigenvalue computation, with "
+        "definiteness classification.",
+        SignatureRequest,
+        SignatureResult,
+        compute_signature,
+        "algebra",
+        "quadratic-form",
+        "exact",
+        examples=(
+            example(
+                "identity_2d_signature",
+                "Compute the signature of I_2; the matrix must be symmetric.",
+                {"form": _FORM_2D},
+            ),
+        ),
+    ),
+)
+
+__all__ = ["TOOLS"]

tests/catalog/operation_schema_snapshots/quadratic_forms.json

@@ -0,0 +1,18 @@
+{
+  "catalog_version": "1",
+  "domain": "quadratic_forms",
+  "operations": {
+    "quadratic_form.discriminant.compute": {
+      "input_schema": "sha256:9b4d46e182bc38cf57216b1848dfadc7a24c455b6296e75d7354c5891ea1b3ef",
+      "output_schema": "sha256:532affab5b9e21899414e52ee6eab97cb705d22d0bb36b4c2f3458e68b00b600"
+    },
+    "quadratic_form.evaluate.compute": {
+      "input_schema": "sha256:de7a0719f61ae1937853880ce14c23f857593dd8ff28ecdab463a93d87c0d830",
+      "output_schema": "sha256:75dbab9324cd95ed8e266b5e1d5cedcdfdb2a4529b6114ee04798fa52dd48f82"
+    },
+    "quadratic_form.signature.compute": {
+      "input_schema": "sha256:e028e2197eda2d9e65c3848aece7a71f2dc2338caac38cb0227ea4da4cdf6698",
+      "output_schema": "sha256:b455fedbc2b023b4755dd5f7d24cc8781a02e9649ab2f9efca912219f0ab719d"
+    }
+  }
+}

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: