feat(math): add simplicial complex link and f-vector operations (#1850)

src/jacobian/math/topology/_admission.py

@@ -25,4 +25,14 @@
         AdmissionDecision.KEEP,
         "distinct exact bounded mathematical value or invariant with material computational or reliability leverage",
     ),
+    OperationAdmission(
+        "topology.simplicial_complex.f_vector.compute",
+        AdmissionDecision.KEEP,
+        "exact f-vector, h-vector, and Euler characteristic of a simplicial complex",
+    ),
+    OperationAdmission(
+        "topology.simplicial_complex.link.compute",
+        AdmissionDecision.KEEP,
+        "exact link of a simplex with maximal facets of the link complex",
+    ),
 )

src/jacobian/math/topology/_models.py

@@ -785,3 +785,47 @@ def require_complete_integral_dimension_range(self) -> Self:
     "face_closure",
     "simplicial_complex_digest",
 ]
+
+
+class LinkRequest(StrictModel):
+    """Request the link of a simplex in a simplicial complex."""
+
+    complex: SimplicialComplexRequest
+    simplex: tuple[VertexLabel, ...] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def require_valid_simplex(self) -> Self:
+        vertex_set = set(self.complex.vertices)
+        for v in self.simplex:
+            if v not in vertex_set:
+                raise ValueError("simplex vertices must be in the complex")
+        return self
+
+
+class LinkResult(TopologyExactResult):
+    """The link of a simplex: facets of the link complex."""
+
+    simplex: tuple[str, ...]
+    link_facets: tuple[tuple[str, ...], ...]
+    link_is_empty: bool
+
+
+__all__.extend(["LinkRequest", "LinkResult"])
+
+
+class FVectorRequest(StrictModel):
+    """Request the f-vector and h-vector of a simplicial complex."""
+
+    complex: SimplicialComplexRequest
+
+
+class FVectorResult(TopologyExactResult):
+    """The f-vector and h-vector of a simplicial complex."""
+
+    f_vector: tuple[int, ...]
+    h_vector: tuple[int, ...]
+    euler_characteristic: int
+    dimension: int
+
+
+__all__.extend(["FVectorRequest", "FVectorResult"])

src/jacobian/math/topology/_operations.py

@@ -23,6 +23,8 @@
     ChainComplexResult,
     FacesInDimension,
     FiniteSimplicialComplex,
+    FVectorRequest,
+    FVectorResult,
     HomologyConvention,
     HomologyGroupResult,
     IntegralFreeGenerator,
@@ -31,6 +33,8 @@
     IntegralSimplicialHomologyResult,
     IntegralTorsionGenerator,
     IntegralVector,
+    LinkRequest,
+    LinkResult,
     ModularVector,
     SimplexBasis,
     SimplicialComplexCanonicalizationResult,
@@ -682,3 +686,86 @@ def _integral_homology(
 )
 
 __all__ = ["TOPOLOGY_OPERATIONS"]
+
+
+def _build_all_simplices(facets: tuple) -> set:  # type: ignore[type-arg]
+    """Build all simplices from maximal facets."""
+    from itertools import combinations as _comb
+
+    all_s = set()
+    for facet in facets:
+        for r in range(1, len(facet) + 1):
+            for subset in _comb(facet, r):
+                all_s.add(frozenset(subset))
+    return all_s
+
+
+def _find_maximal_simplices(simplex_set: set) -> list:  # type: ignore[type-arg]
+    """Find maximal simplices in a set of frozensets."""
+    result = []
+    for s in simplex_set:
+        if not any(s < other for other in simplex_set if s != other):
+            result.append(s)
+    return result
+
+
+def compute_link(request: LinkRequest) -> LinkResult:
+    """Compute the link of a simplex in a simplicial complex."""
+    from jacobian.math.topology._models import LinkResult
+
+    target = set(request.simplex)
+    all_simplices = _build_all_simplices(request.complex.facets)
+    link_simplices = set()
+    for simplex in all_simplices:
+        if not (set(simplex) & target) and (simplex | target) in all_simplices:
+            link_simplices.add(simplex)
+    link_facets = _find_maximal_simplices(link_simplices)
+    link_facet_tuples = tuple(
+        tuple(sorted(s))
+        for s in sorted(link_facets, key=lambda s: (-len(s), sorted(s)))
+    )
+    return LinkResult(
+        simplex=request.simplex,
+        link_facets=link_facet_tuples,
+        link_is_empty=len(link_facets) == 0,
+    )
+
+
+def compute_f_vector(request: FVectorRequest) -> FVectorResult:
+    """Compute the f-vector and h-vector of a simplicial complex."""
+    from itertools import combinations as _comb
+    from math import comb as _comb_func
+
+    from jacobian.math.topology._models import FVectorResult
+
+    facets = request.complex.facets
+    all_simplices = set()
+    for facet in facets:
+        for r in range(1, len(facet) + 1):
+            for subset in _comb(facet, r):
+                all_simplices.add(tuple(sorted(subset)))
+
+    max_dim = 0
+    counts_by_dim: dict[int, int] = {}
+    for simplex in all_simplices:
+        dim = len(simplex) - 1
+        counts_by_dim[dim] = counts_by_dim.get(dim, 0) + 1
+        max_dim = max(max_dim, dim)
+
+    f_vector = tuple(counts_by_dim.get(d, 0) for d in range(max_dim + 1))
+    euler = sum((-1) ** d * counts_by_dim.get(d, 0) for d in range(max_dim + 1))
+
+    n = len(f_vector)
+    h_vector = []
+    for i in range(n):
+        h = 0
+        for j in range(i + 1):
+            h += ((-1) ** (i - j)) * f_vector[j] * _comb_func(n - 1 - j, i - j)
+        h_vector.append(h)
+
+    return FVectorResult(
+        f_vector=f_vector,
+        h_vector=tuple(h_vector),
+        euler_characteristic=euler,
+        dimension=max_dim,
+    )

src/jacobian/math/topology/_tools.py

@@ -1,8 +1,75 @@
 """Finite simplicial topology domain."""
 
-from jacobian.catalog.models import MathTools
-from jacobian.math.topology._operations import TOPOLOGY_OPERATIONS
+from jacobian.catalog._examples import example
+from jacobian.catalog.models import MathTool, MathTools
+from jacobian.math.topology._models import (
+    FVectorRequest,
+    FVectorResult,
+    LinkRequest,
+    LinkResult,
+)
+from jacobian.math.topology._operations import (
+    TOPOLOGY_OPERATIONS,
+    compute_f_vector,
+    compute_link,
+)
 
 __all__ = ["TOOLS"]
 
-TOOLS: MathTools = TOPOLOGY_OPERATIONS
+_f_vector_tool = MathTool(
+    operation_id="topology.simplicial_complex.f_vector.compute",
+    version="1",
+    title="Compute the f-vector and h-vector of a simplicial complex",
+    description=(
+        "Compute the f-vector (face counts by dimension) and h-vector "
+        "of a finite simplicial complex, with Euler characteristic."
+    ),
+    request_type=FVectorRequest,
+    result_type=FVectorResult,
+    run=compute_f_vector,
+    tags=("topology", "simplicial", "exact"),
+    examples=(
+        example(
+            "triangle_f_vector",
+            "Compute f-vector of a triangle (3 vertices, 3 edges, 1 face); "
+            "facets must be a list of maximal simplices.",
+            {
+                "complex": {
+                    "vertices": ["v0", "v1", "v2"],
+                    "facets": [["v0", "v1", "v2"]],
+                }
+            },
+        ),
+    ),
+)
+
+_link_tool = MathTool(
+    operation_id="topology.simplicial_complex.link.compute",
+    version="1",
+    title="Compute the link of a simplex",
+    description=(
+        "Compute the link of a simplex sigma in a simplicial complex K: "
+        "all simplices tau such that sigma intersect tau = empty and sigma union tau "
+        "is a simplex of K. Returns the facets of the link complex."
+    ),
+    request_type=LinkRequest,
+    result_type=LinkResult,
+    run=compute_link,
+    tags=("topology", "simplicial", "exact"),
+    examples=(
+        example(
+            "link_of_vertex_in_triangle",
+            "Compute the link of vertex v0 in a triangle; "
+            "the simplex must be a subset of the complex vertices.",
+            {
+                "complex": {
+                    "vertices": ["v0", "v1", "v2"],
+                    "facets": [["v0", "v1", "v2"]],
+                },
+                "simplex": ["v0"],
+            },
+        ),
+    ),
+)
+
+TOOLS: MathTools = (*TOPOLOGY_OPERATIONS, _f_vector_tool, _link_tool)

tests/catalog/operation_schema_snapshots/topology.json

@@ -10,6 +10,14 @@
       "input_schema": "sha256:5696974624ef54213bd7f17dedfd0b85bca3c218eb03f32dfa2c425f6b141b1a",
       "output_schema": "sha256:c737a222d0d9965766a9a58c4477784f6876a0696b4950b919b448f1fd6d950a"
     },
+    "topology.simplicial_complex.f_vector.compute": {
+      "input_schema": "sha256:cda6b5cff62d3c4ea1facadf31c5e3f437a18995a5f239785fd55032fbcaac35",
+      "output_schema": "sha256:4d6d236e58516aecf41c20352328af26f6ac9c9259c9764ad9aa163b76ab38cf"
+    },
+    "topology.simplicial_complex.link.compute": {
+      "input_schema": "sha256:d2816a7eebda83156efa956c3b3a2354ec8f7bd1ebaef7db40f13ac35ae0e6f0",
+      "output_schema": "sha256:bd4ed92b56c6fadfb0e14a454409bbc7b0c4ab084dfc5c86ef482f38c481dbc5"
+    },
     "topology.simplicial_homology.compute": {
       "input_schema": "sha256:fb63f528a8a29fc0764b550ac7a631896c7736f706ab2a73d7c7621da4ee4a58",
       "output_schema": "sha256:37e3af857a4f953425c5ff1755dc2aa29ab238bb8bca27fbec5484f40ff45441"

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/topology/test_link.py

@@ -0,0 +1,49 @@
+"""Tests for simplicial complex link operation."""
+
+from jacobian.math.topology._models import LinkRequest
+from jacobian.math.topology._operations import compute_link
+
+
+def test_link_of_vertex_in_triangle() -> None:
+    result = compute_link(
+        LinkRequest(
+            complex={"vertices": ["v0", "v1", "v2"], "facets": [["v0", "v1", "v2"]]},
+            simplex=("v0",),
+        )
+    )
+    assert result.link_facets == (("v1", "v2"),)
+    assert result.link_is_empty is False
+
+
+def test_link_of_edge_in_triangle() -> None:
+    result = compute_link(
+        LinkRequest(
+            complex={"vertices": ["v0", "v1", "v2"], "facets": [["v0", "v1", "v2"]]},
+            simplex=("v0", "v1"),
+        )
+    )
+    assert result.link_facets == (("v2",),)
+
+
+def test_link_of_vertex_in_discrete_complex() -> None:
+    result = compute_link(
+        LinkRequest(
+            complex={"vertices": ["v0", "v1"], "facets": [["v0"], ["v1"]]},
+            simplex=("v0",),
+        )
+    )
+    assert result.link_is_empty is True
+
+
+def test_link_of_face_in_boundary() -> None:
+    result = compute_link(
+        LinkRequest(
+            complex={
+                "vertices": ["v0", "v1", "v2"],
+                "facets": [["v0", "v1"], ["v1", "v2"], ["v0", "v2"]],
+            },
+            simplex=("v0",),
+        )
+    )
+    assert ("v1",) in result.link_facets
+    assert ("v2",) in result.link_facets