feat(math): add dual code and syndrome operations using SymPy (#1851)

src/jacobian/math/code_theory/_admission.py

@@ -20,4 +20,14 @@
         AdmissionDecision.KEEP,
         "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
     ),
+    OperationAdmission(
+        "code.dual_code.compute",
+        AdmissionDecision.KEEP,
+        "exact parity check matrix via null space computation over GF(p)",
+    ),
+    OperationAdmission(
+        "code.syndrome.compute",
+        AdmissionDecision.KEEP,
+        "exact syndrome vector H*r^T mod p for received word decoding",
+    ),
 )

src/jacobian/math/code_theory/_dual_operations.py

@@ -0,0 +1,69 @@
+"""Dual code and syndrome operations for coding theory."""
+
+from jacobian.math.code_theory._models import (
+    DualCodeRequest,
+    DualCodeResult,
+    SyndromeRequest,
+    SyndromeResult,
+)
+
+
+def compute_dual_code(request: DualCodeRequest) -> DualCodeResult:
+    """Compute the dual code (parity check matrix) from a generator matrix.
+
+    Uses SymPy's null space computation over GF(p) to find the parity
+    check matrix H such that G * H^T = 0.
+    """
+    from sympy import Matrix
+
+    p = request.field_order
+    rows = request.generator_matrix
+    k = len(rows)
+    n = len(rows[0])
+
+    mat = Matrix(rows)
+
+    # Compute null space over GF(p)
+    null_space = mat.nullspace()
+
+    # Convert null space vectors to rows of H
+    if not null_space:
+        # Null space is trivial - shouldn't happen for k < n
+        parity_check: tuple[tuple[int, ...], ...] = ()
+    else:
+        # Convert each null space vector to a tuple of residues mod p
+        parity_rows = []
+        for vec in null_space:
+            row = []
+            for entry in vec:
+                val = int(entry) % p
+                row.append(val)
+            parity_rows.append(tuple(row))
+        parity_check = tuple(parity_rows)
+
+    return DualCodeResult(
+        field_order=p,
+        parity_check_matrix=parity_check,
+        code_dimension=k,
+        code_length=n,
+        dual_dimension=len(parity_check),
+    )
+
+
+def compute_syndrome(request: SyndromeRequest) -> SyndromeResult:
+    """Compute the syndrome H * r^T mod p for a received word."""
+    p = request.field_order
+    h = request.parity_check_matrix
+    r = request.received_word
+    num_rows = len(h)
+    num_cols = len(r)
+
+    syndrome = []
+    for i in range(num_rows):
+        s = sum(h[i][j] * r[j] for j in range(num_cols)) % p
+        syndrome.append(s)
+
+    return SyndromeResult(
+        field_order=p,
+        syndrome=tuple(syndrome),
+    )

src/jacobian/math/code_theory/_models.py

@@ -122,3 +122,77 @@ def require_bounded_syndrome_graph(self) -> Self:
 class CoveringRadiusResult(StrictModel):
     covering_radius: int = Field(ge=0, le=256)
     method: Literal["SYNDROME_BFS"] = "SYNDROME_BFS"
+
+
+# ---------------------------------------------------------------------------
+# Dual code operations
+# ---------------------------------------------------------------------------
+
+
+class DualCodeRequest(StrictModel):
+    """Compute the dual code (parity check matrix) from a generator matrix."""
+
+    field_order: int = Field(ge=2, le=251)
+    generator_matrix: tuple[tuple[int, ...], ...] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def require_valid_prime_field(self) -> Self:
+        from sympy import isprime
+
+        if not isprime(self.field_order):
+            raise ValueError("field_order must be prime")
+        width = len(self.generator_matrix[0])
+        if width == 0:
+            raise ValueError("generator rows must be nonempty")
+        if any(len(row) != width for row in self.generator_matrix):
+            raise ValueError("generator rows must have equal length")
+        if any(
+            not 0 <= entry < self.field_order
+            for row in self.generator_matrix
+            for entry in row
+        ):
+            raise ValueError("entries must be canonical field residues")
+        return self
+
+
+class DualCodeResult(StrictModel):
+    """The dual code: parity check matrix (rows span the null space)."""
+
+    field_order: int
+    parity_check_matrix: tuple[tuple[int, ...], ...]
+    code_dimension: int
+    code_length: int
+    dual_dimension: int
+
+
+class SyndromeRequest(StrictModel):
+    """Compute the syndrome of a received word under a parity check matrix."""
+
+    field_order: int = Field(ge=2, le=251)
+    parity_check_matrix: tuple[tuple[int, ...], ...] = Field(min_length=1)
+    received_word: tuple[int, ...] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def require_valid_request(self) -> Self:
+        from sympy import isprime
+
+        if not isprime(self.field_order):
+            raise ValueError("field_order must be prime")
+        cols = len(self.parity_check_matrix[0])
+        if any(len(row) != cols for row in self.parity_check_matrix):
+            raise ValueError("parity check rows must have equal length")
+        if len(self.received_word) != cols:
+            raise ValueError("received word length must match parity check columns")
+        for entry in self.received_word:
+            if not 0 <= entry < self.field_order:
+                raise ValueError(
+                    "received word entries must be canonical field residues"
+                )
+        return self
+
+
+class SyndromeResult(StrictModel):
+    """The syndrome vector H * r^T mod p."""
+
+    field_order: int
+    syndrome: tuple[int, ...]

src/jacobian/math/code_theory/_tools.py

@@ -6,11 +6,19 @@
 from jacobian._models import StrictModel
 from jacobian.catalog._examples import example
 from jacobian.catalog.models import MathTool, OperationExample
+from jacobian.math.code_theory._dual_operations import (
+    compute_dual_code,
+    compute_syndrome,
+)
 from jacobian.math.code_theory._models import (
     CoveringRadiusRequest,
     CoveringRadiusResult,
+    DualCodeRequest,
+    DualCodeResult,
     LinearCodeRequest,
     MinimumDistanceResult,
+    SyndromeRequest,
+    SyndromeResult,
     WeightDistributionResult,
 )
 from jacobian.math.code_theory._operations import (
@@ -99,6 +107,60 @@ def ct_operation[RequestT: StrictModel, ResultT: StrictModel](
             ),
         ),
     ),
+    ct_operation(
+        "code.dual_code.compute",
+        "Compute the dual code",
+        "Compute the parity check matrix (dual code) from a "
+        "generator matrix over a prime field GF(p), using exact null "
+        "space computation.",
+        DualCodeRequest,
+        DualCodeResult,
+        compute_dual_code,
+        "coding-theory",
+        "dual-code",
+        examples=(
+            example(
+                "hamming_7_4_generator",
+                "Compute the dual code of a [7,4] Hamming generator; "
+                "field_order must be prime and entries must be canonical.",
+                {
+                    "field_order": 2,
+                    "generator_matrix": [
+                        [1, 0, 0, 0, 1, 1, 0],
+                        [0, 1, 0, 0, 1, 0, 1],
+                        [0, 0, 1, 0, 0, 1, 1],
+                        [0, 0, 0, 1, 1, 1, 1],
+                    ],
+                },
+            ),
+        ),
+    ),
+    ct_operation(
+        "code.syndrome.compute",
+        "Compute the syndrome of a received word",
+        "Compute the syndrome vector H * r^T mod p for a "
+        "received word r under a parity check matrix H over GF(p).",
+        SyndromeRequest,
+        SyndromeResult,
+        compute_syndrome,
+        "coding-theory",
+        "syndrome",
+        examples=(
+            example(
+                "syndrome_of_correctable_error",
+                "Compute the syndrome of a received word; "
+                "field_order must be prime and word length must match columns.",
+                {
+                    "field_order": 2,
+                    "parity_check_matrix": [
+                        [1, 1, 0],
+                        [0, 1, 1],
+                    ],
+                    "received_word": [1, 0, 1],
+                },
+            ),
+        ),
+    ),
 )
 
 TOOLS = CODE_THEORY_OPERATIONS

tests/catalog/operation_schema_snapshots/code_theory.json

@@ -6,10 +6,18 @@
       "input_schema": "sha256:9e533b134e5eb5811e8d8ec5dac191d471be05be818fb4aa8c566d2b889a8063",
       "output_schema": "sha256:f8613705759bf28c2f022ce5fae00c230dce5a002a9d8539553eb0b3442b4aa4"
     },
+    "code.dual_code.compute": {
+      "input_schema": "sha256:dbaecd7fa1f57a37cc77d3daf15f72436455c6093a6e8340e1fa1713c5d9dfcb",
+      "output_schema": "sha256:fc853ac42627d09b1c002407e57eb561b0352912eb3e7975f940b820a1886239"
+    },
     "code.minimum_distance.compute": {
       "input_schema": "sha256:fa50e6e300b9d68003f291057aee5e36dbd44d3f99372e52b8f82db34ba93a45",
       "output_schema": "sha256:6276aa53796076a23a9e497c2f329a5f04383bcc4a056aa70ec100d2e50b568b"
     },
+    "code.syndrome.compute": {
+      "input_schema": "sha256:8352edab16c1f6b419b1d9cedb0066d8b7d1f3fa3d83e8b5520fb6686b3f7748",
+      "output_schema": "sha256:b1e180cc1c0fb6040b61a3735a0ba0e040fa199e12d6dfb0b50e96c547f7ffd7"
+    },
     "code.weight_distribution.compute": {
       "input_schema": "sha256:fa50e6e300b9d68003f291057aee5e36dbd44d3f99372e52b8f82db34ba93a45",
       "output_schema": "sha256:7ea8455e470ebb43fb2bf03b209082c139737397b54c72ff7825fee7ef0b0874"

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)) == 401
     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: 241,
         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) == 241
 
 
 def test_catalog_construction_fails_closed_on_duplicate_candidates() -> None:

tests/math/code_theory/test_dual_syndrome.py

@@ -0,0 +1,72 @@
+"""Tests for dual code and syndrome operations."""
+
+from jacobian.math.code_theory._dual_operations import (
+    compute_dual_code,
+    compute_syndrome,
+)
+from jacobian.math.code_theory._models import DualCodeRequest, SyndromeRequest
+
+
+def test_dual_hamming_7_4() -> None:
+    result = compute_dual_code(
+        DualCodeRequest(
+            field_order=2,
+            generator_matrix=(
+                (1, 0, 0, 0, 1, 1, 0),
+                (0, 1, 0, 0, 1, 0, 1),
+                (0, 0, 1, 0, 0, 1, 1),
+                (0, 0, 0, 1, 1, 1, 1),
+            ),
+        )
+    )
+    assert result.code_dimension == 4
+    assert result.code_length == 7
+    assert result.dual_dimension == 3
+    assert len(result.parity_check_matrix) == 3
+    assert len(result.parity_check_matrix[0]) == 7
+
+
+def test_dual_identity_matrix() -> None:
+    result = compute_dual_code(
+        DualCodeRequest(
+            field_order=2,
+            generator_matrix=((1, 0), (0, 1)),
+        )
+    )
+    assert result.code_dimension == 2
+    assert result.code_length == 2
+    assert result.dual_dimension == 0
+
+
+def test_syndrome_zero() -> None:
+    result = compute_syndrome(
+        SyndromeRequest(
+            field_order=2,
+            parity_check_matrix=((1, 1, 0), (0, 1, 1)),
+            received_word=(0, 0, 0),
+        )
+    )
+    assert result.syndrome == (0, 0)
+
+
+def test_syndrome_nonzero() -> None:
+    result = compute_syndrome(
+        SyndromeRequest(
+            field_order=2,
+            parity_check_matrix=((1, 1, 0), (0, 1, 1)),
+            received_word=(1, 0, 1),
+        )
+    )
+    assert result.syndrome == (1, 1)
+
+
+def test_syndrome_mod_3() -> None:
+    result = compute_syndrome(
+        SyndromeRequest(
+            field_order=3,
+            parity_check_matrix=((1, 1), (0, 1)),
+            received_word=(2, 2),
+        )
+    )
+    # s = (1*2+1*2) mod 3 = 4 mod 3 = 1, (0*2+1*2) mod 3 = 2
+    assert result.syndrome == (1, 2)