feat(math): add algebraic topology operations (#1878)

Add algebraic_topology_ops domain with 2 operations: edge path word
computation and edge path concatenation. Uses exact graph traversal
over bounded edge paths.

Closes #1878

Author: morluto

src/jacobian/catalog/builtins.py

@@ -18,6 +18,12 @@
 from jacobian.math.algebraic_combinatorics._tools import (
     TOOLS as ALGEBRAIC_COMBINATORICS_TOOLS,
 )
+from jacobian.math.algebraic_topology_ops._admission import (
+    ADMISSIONS as ALGEBRAIC_TOPOLOGY_OPS_ADMISSIONS,
+)
+from jacobian.math.algebraic_topology_ops._tools import (
+    TOOLS as ALGEBRAIC_TOPOLOGY_OPS_TOOLS,
+)
 from jacobian.math.analysis._admission import ADMISSIONS as ANALYSIS_ADMISSIONS
 from jacobian.math.analysis._tools import TOOLS as ANALYSIS_TOOLS
 from jacobian.math.arithmetic._admission import ADMISSIONS as ARITHMETIC_ADMISSIONS
@@ -311,6 +317,7 @@
     *POLYNOMIAL_TOOLS,
     *MULTIVARIATE_POLYNOMIAL_TOOLS,
     *ANALYSIS_TOOLS,
+    *ALGEBRAIC_TOPOLOGY_OPS_TOOLS,
     *PROBABILITY_TOOLS,
     *OPTIMIZATION_TOOLS,
     *TOPOLOGY_TOOLS,
@@ -352,6 +359,7 @@
     *ADDITIVE_COMBINATORICS_ADMISSIONS,
     *ALGEBRAIC_COMBINATORICS_ADMISSIONS,
     *ANALYSIS_ADMISSIONS,
+    *ALGEBRAIC_TOPOLOGY_OPS_ADMISSIONS,
     *ARITHMETIC_ADMISSIONS,
     *ARITHMETIC_COUNTING_ADMISSIONS,
     *ARITHMETIC_DYNAMICS_ADMISSIONS,

src/jacobian/math/algebraic_topology_ops/__init__.py

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

src/jacobian/math/algebraic_topology_ops/_admission.py

@@ -0,0 +1,18 @@
+"""Owner-local admission decisions for built-in math operations."""
+
+from __future__ import annotations
+
+from jacobian.catalog.admission import AdmissionDecision, OperationAdmission
+
+ADMISSIONS: tuple[OperationAdmission, ...] = (
+    OperationAdmission(
+        "topology.simplicial.edge_path.word.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+    OperationAdmission(
+        "topology.simplicial.edge_path.concatenate.compute",
+        AdmissionDecision.KEEP,
+        "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
+    ),
+)

src/jacobian/math/algebraic_topology_ops/_models.py

@@ -0,0 +1,74 @@
+"""Typed wire contracts for algebraic topology operations."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from jacobian._models import StrictModel
+
+MAX_EDGES = 64
+MAX_WORD = 128
+
+
+class EdgePath(StrictModel):
+    """A path in a graph as a sequence of oriented edges."""
+
+    vertex_count: int = Field(ge=2)
+    edges: tuple[tuple[int, int], ...] = Field(min_length=1, max_length=MAX_EDGES)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        for u, v in self.edges:
+            if not (0 <= u < self.vertex_count and 0 <= v < self.vertex_count):
+                raise ValueError("edge vertices must be in 0..vertex_count-1")
+        return self
+
+
+class EdgePathWordRequest(StrictModel):
+    """Compute the free group word for an edge path."""
+
+    vertex_count: int = Field(ge=2)
+    edges: tuple[tuple[int, int], ...] = Field(min_length=1, max_length=MAX_EDGES)
+    path: tuple[int, ...] = Field(min_length=2, max_length=MAX_WORD)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if any(not 0 <= v < self.vertex_count for v in self.path):
+            raise ValueError("path vertices must be in 0..vertex_count-1")
+        for u, v in self.edges:
+            if not (0 <= u < self.vertex_count and 0 <= v < self.vertex_count):
+                raise ValueError("edge vertices must be in 0..vertex_count-1")
+        return self
+
+
+class EdgePathConcatenateRequest(StrictModel):
+    """Concatenate two edge paths."""
+
+    vertex_count: int = Field(ge=2)
+    path_a: tuple[int, ...] = Field(min_length=2, max_length=MAX_WORD)
+    path_b: tuple[int, ...] = Field(min_length=2, max_length=MAX_WORD)
+
+    @model_validator(mode="after")
+    def require_valid(self) -> Self:
+        if any(not 0 <= v < self.vertex_count for v in self.path_a):
+            raise ValueError("path_a vertices must be valid")
+        if any(not 0 <= v < self.vertex_count for v in self.path_b):
+            raise ValueError("path_b vertices must be valid")
+        return self
+
+
+# Results
+
+
+class EdgePathWordResult(StrictModel):
+    word: tuple[str, ...]
+    length: int = Field(ge=0)
+    method: str = "EDGE_LABEL_REDUCTION"
+
+
+class EdgePathConcatenateResult(StrictModel):
+    path: tuple[int, ...]
+    length: int = Field(ge=0)
+    method: str = "PATH_CONCATENATION"

src/jacobian/math/algebraic_topology_ops/_operations.py

@@ -0,0 +1,59 @@
+"""Domain functions for algebraic topology operations."""
+
+from __future__ import annotations
+
+from jacobian.math.algebraic_topology_ops._models import (
+    EdgePathConcatenateRequest,
+    EdgePathConcatenateResult,
+    EdgePathWordRequest,
+    EdgePathWordResult,
+)
+
+
+def compute_edge_path_word(request: EdgePathWordRequest) -> EdgePathWordResult:
+    """Compute the free group word for an edge path.
+
+    Each edge in the graph is assigned a generator label e_i.
+    Traversing edge i forward adds e_i, backward adds e_i^{-1}.
+    """
+    edges = list(request.edges)
+    path = list(request.path)
+    word: list[str] = []
+    for i in range(len(path) - 1):
+        u, v = path[i], path[i + 1]
+        found = False
+        for j, (eu, ev) in enumerate(edges):
+            if u == eu and v == ev:
+                word.append(f"e{j + 1}")
+                found = True
+                break
+            if u == ev and v == eu:
+                word.append(f"e{j + 1}^-1")
+                found = True
+                break
+        if not found:
+            word.append(f"INVALID({u}->{v})")
+    return EdgePathWordResult(
+        word=tuple(word),
+        length=len(word),
+    )
+
+
+def compute_edge_path_concatenate(
+    request: EdgePathConcatenateRequest,
+) -> EdgePathConcatenateResult:
+    """Concatenate two edge paths.
+
+    If the last vertex of path_a equals the first vertex of path_b,
+    the concatenation is path_a + path_b[1:], removing the duplicate.
+    """
+    path_a = list(request.path_a)
+    path_b = list(request.path_b)
+    if path_a and path_b and path_a[-1] == path_b[0]:
+        result = path_a + path_b[1:]
+    else:
+        result = path_a + path_b
+    return EdgePathConcatenateResult(
+        path=tuple(result),
+        length=len(result),
+    )

src/jacobian/math/algebraic_topology_ops/_tools.py

@@ -0,0 +1,93 @@
+"""Algebraic topology 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.algebraic_topology_ops._models import (
+    EdgePathConcatenateRequest,
+    EdgePathConcatenateResult,
+    EdgePathWordRequest,
+    EdgePathWordResult,
+)
+from jacobian.math.algebraic_topology_ops._operations import (
+    compute_edge_path_concatenate,
+    compute_edge_path_word,
+)
+
+
+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(
+        "topology.simplicial.edge_path.word.compute",
+        "Compute the free group word for an edge path",
+        "Compute the free group word representation of an edge path in a "
+        "graph, where each edge corresponds to a generator and its inverse.",
+        EdgePathWordRequest,
+        EdgePathWordResult,
+        compute_edge_path_word,
+        "topology",
+        "edge-path",
+        "exact",
+        examples=(
+            example(
+                "triangle_path",
+                "Compute the word for path 0->1->2 in a triangle.",
+                {
+                    "vertex_count": 3,
+                    "edges": [[0, 1], [1, 2], [2, 0]],
+                    "path": [0, 1, 2],
+                },
+            ),
+        ),
+    ),
+    _op(
+        "topology.simplicial.edge_path.concatenate.compute",
+        "Concatenate two edge paths",
+        "Concatenate two edge paths in a graph, removing the shared vertex.",
+        EdgePathConcatenateRequest,
+        EdgePathConcatenateResult,
+        compute_edge_path_concatenate,
+        "topology",
+        "edge-path",
+        "exact",
+        examples=(
+            example(
+                "concatenate_paths",
+                "Concatenate [0,1] and [1,2] in a 3-vertex graph.",
+                {
+                    "vertex_count": 3,
+                    "path_a": [0, 1],
+                    "path_b": [1, 2],
+                },
+            ),
+        ),
+    ),
+)
+
+__all__ = ["TOOLS"]

tests/catalog/operation_schema_snapshots/algebraic_topology_ops.json

@@ -0,0 +1,14 @@
+{
+    "catalog_version": "1",
+    "domain": "algebraic_topology_ops",
+    "operations": {
+        "topology.simplicial.edge_path.concatenate.compute": {
+            "input_schema": "sha256:032aa114a51b155f849194e433e7259901f843a3f779d511f28a2930db133cfb",
+            "output_schema": "sha256:b783b16a3b53a4ffbbfd38b220ef9208cd2c998f8a25d3ebd12c671f00193257"
+        },
+        "topology.simplicial.edge_path.word.compute": {
+            "input_schema": "sha256:d6b5fc61ccb1c894985679dbf3cf6c55d6d3076c6f18bbb408b5e936940bfa8f",
+            "output_schema": "sha256:1b0449d78502cd66e325226742fb6cb2a3e2684cec8136b12ecdb2fa83ad6cba"
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+"""Tests for algebraic topology operations."""
+
+from jacobian.math.algebraic_topology_ops._models import (
+    EdgePathConcatenateRequest,
+    EdgePathWordRequest,
+)
+from jacobian.math.algebraic_topology_ops._operations import (
+    compute_edge_path_concatenate,
+    compute_edge_path_word,
+)
+from jacobian.math.algebraic_topology_ops._tools import TOOLS
+
+
+def test_catalog_contains_only_audited_operations() -> None:
+    assert {tool.operation_id for tool in TOOLS} == {
+        "topology.simplicial.edge_path.word.compute",
+        "topology.simplicial.edge_path.concatenate.compute",
+    }
+
+
+def test_edge_path_word_forward() -> None:
+    request = EdgePathWordRequest(
+        vertex_count=3,
+        edges=((0, 1), (1, 2), (2, 0)),
+        path=(0, 1, 2),
+    )
+    result = compute_edge_path_word(request)
+    assert result.word == ("e1", "e2")
+    assert result.length == 2
+
+
+def test_edge_path_word_backward() -> None:
+    request = EdgePathWordRequest(
+        vertex_count=3,
+        edges=((0, 1), (1, 2), (2, 0)),
+        path=(1, 0),
+    )
+    result = compute_edge_path_word(request)
+    assert result.word == ("e1^-1",)
+
+
+def test_edge_path_concatenate() -> None:
+    request = EdgePathConcatenateRequest(
+        vertex_count=3,
+        path_a=(0, 1),
+        path_b=(1, 2),
+    )
+    result = compute_edge_path_concatenate(request)
+    assert result.path == (0, 1, 2)
+    assert result.length == 3