feat(math): add Latin square operations (#1887)

Add latin_squares_ops domain with 3 operations: Latin square
verification, orthogonality check, and transpose. Uses exact combinatorial
checks over bounded n x n matrices.

Closes #1887

Author: morluto

src/jacobian/catalog/builtins.py

@@ -170,6 +170,12 @@
     ADMISSIONS as IMPARTIAL_GAMES_ADMISSIONS,
 )
 from jacobian.math.impartial_games._tools import TOOLS as IMPARTIAL_GAMES_TOOLS
+from jacobian.math.latin_squares_ops._admission import (
+    ADMISSIONS as LATIN_SQUARES_OPS_ADMISSIONS,
+)
+from jacobian.math.latin_squares_ops._tools import (
+    TOOLS as LATIN_SQUARES_OPS_TOOLS,
+)
 from jacobian.math.lattices._admission import ADMISSIONS as LATTICES_ADMISSIONS
 from jacobian.math.lattices._tools import TOOLS as LATTICES_TOOLS
 from jacobian.math.logic._admission import ADMISSIONS as LOGIC_ADMISSIONS
@@ -307,6 +313,7 @@
     *SYMBOLIC_MATRIX_TOOLS,
     *RATIONAL_LINEAR_TOOLS,
     *LATTICES_TOOLS,
+    *LATIN_SQUARES_OPS_TOOLS,
     *FORMAL_POWER_SERIES_TOOLS,
     *POLYNOMIAL_TOOLS,
     *MULTIVARIATE_POLYNOMIAL_TOOLS,
@@ -391,6 +398,7 @@
     *GROUP_ADMISSIONS,
     *IMPARTIAL_GAMES_ADMISSIONS,
     *LATTICES_ADMISSIONS,
+    *LATIN_SQUARES_OPS_ADMISSIONS,
     *LOGIC_ADMISSIONS,
     *MARKOV_CHAIN_ADMISSIONS,
     *MATRICES_ADMISSIONS,

src/jacobian/math/latin_squares_ops/__init__.py

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

src/jacobian/math/latin_squares_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(
+        "latin_square.check",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "latin_square.orthogonality.check",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "latin_square.transpose.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+)

src/jacobian/math/latin_squares_ops/_models.py

@@ -0,0 +1,62 @@
+"""Typed wire contracts for Latin square operations."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from jacobian._models import StrictModel
+
+MAX_N = 32
+
+
+class LatinSquare(StrictModel):
+    """A Latin square as an n x n matrix of symbols 0..n-1."""
+
+    order: int = Field(ge=1, le=MAX_N)
+    cells: tuple[tuple[int, ...], ...] = Field(min_length=1, max_length=MAX_N)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if len(self.cells) != self.order:
+            raise ValueError("cells must be order x order")
+        if any(len(row) != self.order for row in self.cells):
+            raise ValueError("cells must be a square matrix")
+        if any(not 0 <= v < self.order for row in self.cells for v in row):
+            raise ValueError("cell values must be in 0..order-1")
+        return self
+
+
+class LatinSquareRequest(StrictModel):
+    square: LatinSquare
+
+
+class OrthogonalityRequest(StrictModel):
+    square_a: LatinSquare
+    square_b: LatinSquare
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if self.square_a.order != self.square_b.order:
+            raise ValueError("squares must have the same order")
+        return self
+
+
+# Results
+
+
+class LatinSquareCheckResult(StrictModel):
+    is_latin: bool
+    method: str = "ROW_COLUMN_SYMBOL_UNIQUENESS"
+
+
+class OrthogonalityResult(StrictModel):
+    is_orthogonal: bool
+    pair_count: int = Field(ge=0)
+    method: str = "ORDERED_PAIR_UNIQUENESS"
+
+
+class LatinSquareTransposeResult(StrictModel):
+    transposed: tuple[tuple[int, ...], ...]
+    method: str = "MATRIX_TRANSPOSE"

src/jacobian/math/latin_squares_ops/_operations.py

@@ -0,0 +1,51 @@
+"""Domain functions for Latin square operations."""
+
+from __future__ import annotations
+
+from jacobian.math.latin_squares_ops._models import (
+    LatinSquareCheckResult,
+    LatinSquareRequest,
+    LatinSquareTransposeResult,
+    OrthogonalityRequest,
+    OrthogonalityResult,
+)
+
+
+def compute_latin_square_check(request: LatinSquareRequest) -> LatinSquareCheckResult:
+    """Check if a matrix is a Latin square."""
+    n = request.square.order
+    cells = request.square.cells
+    for i in range(n):
+        if len(set(cells[i])) != n:
+            return LatinSquareCheckResult(is_latin=False)
+        col = set()
+        for j in range(n):
+            col.add(cells[j][i])
+        if len(col) != n:
+            return LatinSquareCheckResult(is_latin=False)
+    return LatinSquareCheckResult(is_latin=True)
+
+
+def compute_orthogonality(request: OrthogonalityRequest) -> OrthogonalityResult:
+    """Check if two Latin squares of the same order are orthogonal."""
+    n = request.square_a.order
+    pairs: set[tuple[int, int]] = set()
+    for i in range(n):
+        for j in range(n):
+            pair = (request.square_a.cells[i][j], request.square_b.cells[i][j])
+            if pair in pairs:
+                return OrthogonalityResult(is_orthogonal=False, pair_count=len(pairs))
+            pairs.add(pair)
+    return OrthogonalityResult(is_orthogonal=True, pair_count=len(pairs))
+
+
+def compute_latin_square_transpose(
+    request: LatinSquareRequest,
+) -> LatinSquareTransposeResult:
+    """Transpose a Latin square (swap rows and columns)."""
+    n = request.square.order
+    cells = request.square.cells
+    transposed = tuple(
+        tuple(cells[j][i] for j in range(n)) for i in range(n)
+    )
+    return LatinSquareTransposeResult(transposed=transposed)

src/jacobian/math/latin_squares_ops/_tools.py

@@ -0,0 +1,125 @@
+"""Latin square 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.latin_squares_ops._models import (
+    LatinSquareCheckResult,
+    LatinSquareRequest,
+    LatinSquareTransposeResult,
+    OrthogonalityRequest,
+    OrthogonalityResult,
+)
+from jacobian.math.latin_squares_ops._operations import (
+    compute_latin_square_check,
+    compute_latin_square_transpose,
+    compute_orthogonality,
+)
+
+
+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(
+        "latin_square.check",
+        "Check if a matrix is a Latin square",
+        "Verify that each row and column contains every symbol 0..n-1 "
+        "exactly once.",
+        LatinSquareRequest,
+        LatinSquareCheckResult,
+        compute_latin_square_check,
+        "latin-square",
+        "verification",
+        "exact",
+        examples=(
+            example(
+                "z2_latin_square",
+                "Check the 2x2 Latin square [[0,1],[1,0]].",
+                {
+                    "square": {
+                        "order": 2,
+                        "cells": [[0, 1], [1, 0]],
+                    },
+                },
+            ),
+        ),
+    ),
+    _op(
+        "latin_square.orthogonality.check",
+        "Check orthogonality of two Latin squares",
+        "Check whether two Latin squares of the same order are orthogonal, "
+        "i.e., all ordered pairs of entries are distinct.",
+        OrthogonalityRequest,
+        OrthogonalityResult,
+        compute_orthogonality,
+        "latin-square",
+        "orthogonality",
+        "exact",
+        examples=(
+            example(
+                "orthogonal_z2",
+                "Check orthogonality of [[0,1],[1,0]] and [[0,1],[1,0]].",
+                {
+                    "square_a": {
+                        "order": 2,
+                        "cells": [[0, 1], [1, 0]],
+                    },
+                    "square_b": {
+                        "order": 2,
+                        "cells": [[0, 1], [1, 0]],
+                    },
+                },
+            ),
+        ),
+    ),
+    _op(
+        "latin_square.transpose.compute",
+        "Transpose a Latin square",
+        "Swap rows and columns of a Latin square.",
+        LatinSquareRequest,
+        LatinSquareTransposeResult,
+        compute_latin_square_transpose,
+        "latin-square",
+        "transpose",
+        "exact",
+        examples=(
+            example(
+                "transpose_z2",
+                "Transpose [[0,1],[1,0]].",
+                {
+                    "square": {
+                        "order": 2,
+                        "cells": [[0, 1], [1, 0]],
+                    },
+                },
+            ),
+        ),
+    ),
+)
+
+__all__ = ["TOOLS"]

tests/catalog/operation_schema_snapshots/latin_squares_ops.json

@@ -0,0 +1,18 @@
+{
+    "catalog_version": "1",
+    "domain": "latin_squares_ops",
+    "operations": {
+        "latin_square.check": {
+            "input_schema": "sha256:59ca806a02fcdf709c1d356e67e767fe50d825270a4231ef7b23c3722b915107",
+            "output_schema": "sha256:d15c5c9d2c54f60418b60ea8015e174603b627b803c244d946b48276d70a703d"
+        },
+        "latin_square.orthogonality.check": {
+            "input_schema": "sha256:595c651ee68bc30d9a7f7aada49dcfa6d8f94e9af2ae05fe91eec877d0f490c1",
+            "output_schema": "sha256:82729ec18eee98eae447f61a0099751476a72fcd056b1a2f2aa5bc8fba6fd186"
+        },
+        "latin_square.transpose.compute": {
+            "input_schema": "sha256:59ca806a02fcdf709c1d356e67e767fe50d825270a4231ef7b23c3722b915107",
+            "output_schema": "sha256:f3e5e3a172846ac5c250efe7fc525ccf15457ba605a0987f3ccaf2ed0235d5a4"
+        }
+    }
+}

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: