feat(math): add simplicial complex f-vector operation

Add topology.simplicial_complex.f_vector.compute to the topology
domain. Computes the f-vector (face counts by dimension), h-vector,
and Euler characteristic of a finite simplicial complex from its
maximal facets.

Partially addresses #1798.

Author: morluto

src/jacobian/math/topology/_admission.py

@@ -25,4 +25,9 @@
         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",
+    ),
 )

src/jacobian/math/topology/_models.py

@@ -785,3 +785,21 @@ def require_complete_integral_dimension_range(self) -> Self:
     "face_closure",
     "simplicial_complex_digest",
 ]
+
+
+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,
@@ -682,3 +684,47 @@ def _integral_homology(
 )
 
 __all__ = ["TOPOLOGY_OPERATIONS"]
+
+
+def compute_f_vector(request: FVectorRequest) -> FVectorResult:
+    """Compute the f-vector and h-vector of a simplicial complex."""
+    facets = request.complex.facets
+
+    # Build all simplices from facets
+    from itertools import combinations as _comb
+
+    all_simplices: set[tuple[str, ...]] = set()
+    for facet in facets:
+        n = len(facet)
+        for r in range(1, n + 1):
+            for subset in _comb(facet, r):
+                all_simplices.add(tuple(sorted(subset)))
+
+    # Count by dimension
+    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))
+
+    # Compute h-vector from f-vector
+    from math import comb as _comb_func
+
+    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,37 @@
 """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
+from jacobian.math.topology._operations import TOPOLOGY_OPERATIONS, compute_f_vector
 
 __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 simplices.",
+            {
+                "complex": {
+                    "vertices": ["v0", "v1", "v2"],
+                    "facets": [["v0", "v1", "v2"]],
+                }
+            },
+        ),
+    ),
+)
+
+TOOLS: MathTools = (*TOPOLOGY_OPERATIONS, _f_vector_tool)

tests/catalog/operation_schema_snapshots/topology.json

@@ -10,6 +10,10 @@
       "input_schema": "sha256:5696974624ef54213bd7f17dedfd0b85bca3c218eb03f32dfa2c425f6b141b1a",
       "output_schema": "sha256:c737a222d0d9965766a9a58c4477784f6876a0696b4950b919b448f1fd6d950a"
     },
+    "topology.simplicial_complex.f_vector.compute": {
+      "input_schema": "sha256:cda6b5cff62d3c4ea1facadf31c5e3f437a18995a5f239785fd55032fbcaac35",
+      "output_schema": "sha256:4d6d236e58516aecf41c20352328af26f6ac9c9259c9764ad9aa163b76ab38cf"
+    },
     "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)) == 400
     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: 240,
         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) == 240
 
 
 def test_catalog_construction_fails_closed_on_duplicate_candidates() -> None:

tests/math/topology/test_f_vector.py

@@ -0,0 +1,33 @@
+"""Tests for simplicial complex f-vector operation."""
+
+from jacobian.math.topology._models import FVectorRequest
+from jacobian.math.topology._operations import compute_f_vector
+
+
+def test_triangle() -> None:
+    result = compute_f_vector(
+        FVectorRequest(
+            complex={"vertices": ["v0", "v1", "v2"], "facets": [["v0", "v1", "v2"]]}
+        )
+    )
+    assert result.f_vector == (3, 3, 1)
+    assert result.euler_characteristic == 1
+    assert result.dimension == 2
+
+
+def test_edge() -> None:
+    result = compute_f_vector(
+        FVectorRequest(complex={"vertices": ["v0", "v1"], "facets": [["v0", "v1"]]})
+    )
+    assert result.f_vector == (2, 1)
+    assert result.euler_characteristic == 1
+    assert result.dimension == 1
+
+
+def test_single_vertex() -> None:
+    result = compute_f_vector(
+        FVectorRequest(complex={"vertices": ["v0"], "facets": [["v0"]]})
+    )
+    assert result.f_vector == (1,)
+    assert result.euler_characteristic == 1
+    assert result.dimension == 0