holonomy-lib 0.8.0__py3-none-any.whl

holonomy_lib/topology/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""holonomy_lib.topology: Hodge Laplacians + persistent homology.
+
+Built on `holonomy_lib.simplicial`. Two flavors of output:
+
+  Hodge / Betti
+    `hodge_laplacian(complex, k)`; the Hodge Laplacian on k-chains,
+    `L_k = ∂_{k+1} ∂_{k+1}^T + ∂_k^T ∂_k`. Its kernel has dimension
+    equal to the k-th Betti number.
+    `betti_numbers(complex, max_dim)`; computes
+    `β_k = n_k - rank(∂_k) - rank(∂_{k+1})` from float64 boundary ranks,
+    giving `(β_0, β_1, …, β_max_dim)`. It does not form `L_k`.
+
+  Persistent homology
+    `persistence_diagrams(points_or_distances, max_dim)` returns the
+    per-dim birth/death barcodes for a Vietoris-Rips filtration.
+"""
+
+from holonomy_lib.topology.hodge import betti_numbers, hodge_laplacian
+from holonomy_lib.topology.persistent_homology import persistence_diagrams
+
+__all__ = [
+    "betti_numbers",
+    "hodge_laplacian",
+    "persistence_diagrams",
+]

holonomy_lib/topology/_filtration.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Vietoris-Rips filtration construction for persistent homology.
+
+A filtration is a totally-ordered sequence of simplices, each with
+a birth time at which it joins the complex. For the Vietoris-Rips
+filtration, the birth time of a simplex `σ` is the largest pairwise
+distance among its vertices:
+
+    birth(σ) = max_{i, j ∈ σ}  d(i, j).
+
+Simplices with the same birth time are tie-broken by `(dim, input row
+index)` so the ordering is total and deterministic. This module
+returns the filtration in the order needed by the Z/2 boundary-matrix
+reduction (`_reduction.py`): simplices listed in birth-time order,
+with a per-simplex `(dim, original-index-within-dim)` tag so
+boundary columns can be reconstructed.
+
+References:
+  Edelsbrunner, H., Harer, J. (2010). Computational Topology: An
+    Introduction. American Mathematical Society. §VI.2; filtrations.
+  Bauer, U. (2021). Ripser: efficient computation of Vietoris-Rips
+    persistence barcodes. J. Appl. Comput. Topology 5:391-423.
+    Filtration ordering conventions used here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+from holonomy_lib.simplicial import SparseSimplicialComplex
+
+
+@dataclass(frozen=True)
+class Filtration:
+    """A Vietoris-Rips filtration with simplices in birth-time order.
+
+    Attributes:
+      complex: the underlying simplicial complex (sparse, single-instance).
+      birth_times: `(n_total_simplices,)` float tensor, in filtration order.
+      sorted_dims: `(n_total_simplices,)` int tensor; dim of each simplex.
+      sorted_indices: `(n_total_simplices,)` int tensor; for the j-th
+        simplex in filtration order, its row index within
+        `complex.simplices_by_dim[sorted_dims[j]]`. Used to fetch the
+        simplex's vertex tuple when building the boundary matrix.
+    """
+
+    complex: SparseSimplicialComplex
+    birth_times: torch.Tensor
+    sorted_dims: torch.Tensor
+    sorted_indices: torch.Tensor
+
+
+def build_filtration(
+    distances: torch.Tensor,
+    complex: SparseSimplicialComplex,
+) -> Filtration:
+    """Compute the birth time and sort order of every simplex in a VR complex.
+
+    Args:
+      distances: `(n, n)` pairwise distance matrix for the same vertex
+        set as `complex`.
+      complex: pre-built `SparseSimplicialComplex` (typically from
+        `vietoris_rips_sparse`).
+
+    Returns:
+      A `Filtration` with simplices ordered by (birth_time, dim,
+      input_row_index).
+
+    References:
+      Edelsbrunner, Harer (2010). Computational Topology: An Introduction.
+        AMS, Chapter VI.2, filtrations.
+    """
+    # Gather one record per simplex across all dimensions into flat arrays,
+    # so the sort below can order the whole complex at once.
+    all_birth: list[torch.Tensor] = []
+    all_dim: list[torch.Tensor] = []
+    all_idx: list[torch.Tensor] = []
+
+    for k in sorted(complex.simplices_by_dim.keys()):
+        simplices = complex.simplices_by_dim[k]              # (n_k, k+1)
+        n_k = simplices.shape[0]
+        if n_k == 0:
+            continue
+        if k == 0:
+            # A vertex's birth would be d(i, i) from the general formula below.
+            # That is 0 for any distance matrix, so the gather is skipped.
+            births = torch.zeros(n_k, dtype=distances.dtype,
+                                  device=distances.device)
+        else:
+            # Birth is the largest distance among the simplex's vertices, which
+            # is the max over its (k+1) x (k+1) submatrix of `distances`. Advanced
+            # indexing builds all those submatrices at once:
+            #   pairs[s, i, j] = distances[ simplices[s, i], simplices[s, j] ]
+            v_i = simplices.unsqueeze(-1)                     # (n_k, k+1, 1)
+            v_j = simplices.unsqueeze(-2)                     # (n_k, 1, k+1)
+            # Broadcast to (n_k, k+1, k+1) of vertex pairs.
+            sub = distances[v_i, v_j]                          # (n_k, k+1, k+1)
+            births = sub.flatten(start_dim=1).max(dim=-1).values
+        all_birth.append(births)
+        all_dim.append(torch.full((n_k,), k, dtype=torch.int64,
+                                    device=distances.device))
+        all_idx.append(torch.arange(n_k, dtype=torch.int64,
+                                      device=distances.device))
+
+    # No simplices at all. Return empty tensors in the same dtypes as the
+    # non-empty case, so callers never see a different type here.
+    if not all_birth:
+        empty = torch.zeros(0, dtype=distances.dtype, device=distances.device)
+        empty_i = torch.zeros(0, dtype=torch.int64, device=distances.device)
+        return Filtration(
+            complex=complex, birth_times=empty,
+            sorted_dims=empty_i, sorted_indices=empty_i,
+        )
+
+    birth_times = torch.cat(all_birth)
+    dims = torch.cat(all_dim)
+    indices = torch.cat(all_idx)
+
+    # Sort by (birth_time, dim, row). A stable sort keeps the existing order
+    # among ties, so we sort by the least significant key first. The last pass
+    # sorts by birth time, and simplices with equal birth keep the (dim, row)
+    # order that the passes before it left.
+    order = torch.argsort(indices, stable=True)
+    dims_sorted = dims[order]
+    times_sorted = birth_times[order]
+    indices_sorted = indices[order]
+
+    order2 = torch.argsort(dims_sorted, stable=True)
+    times_sorted = times_sorted[order2]
+    indices_sorted = indices_sorted[order2]
+    dims_sorted = dims_sorted[order2]
+
+    order3 = torch.argsort(times_sorted, stable=True)
+    times_sorted = times_sorted[order3]
+    indices_sorted = indices_sorted[order3]
+    dims_sorted = dims_sorted[order3]
+
+    return Filtration(
+        complex=complex,
+        birth_times=times_sorted,
+        sorted_dims=dims_sorted,
+        sorted_indices=indices_sorted,
+    )

holonomy_lib/topology/_reduction.py

@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Z/2 left-to-right boundary-matrix reduction for persistent homology.
+
+Boundary columns are prepared by tensor face enumeration and row joins.
+The Python backend transfers their indices and filtration metadata to the
+host together, once per filtration. The torch backend keeps columns on the
+input device and transfers only metadata in that bulk operation.
+
+Reduction is sequential: a column's pivot depends on earlier reduced
+columns. Python uses set symmetric differences; torch uses odd occurrence
+counts in concatenated index tensors. The torch backend synchronizes once
+per pivot attempt, including every attempt after an XOR. It is not a fully
+asynchronous GPU reduction. Neither backend implements clearing.
+
+A nonzero reduced column pairs its lowest face with a death. A zero column
+is essential only when no later column has paired that birth with a death.
+
+References:
+  Edelsbrunner, H., Letscher, D., Zomorodian, A. (2002). Topological
+    persistence and simplification. Discrete & Computational Geometry
+    28:511-533. Left-to-right boundary reduction.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import torch
+
+from holonomy_lib.simplicial._face_lookup import enumerate_faces, lookup_rows
+from holonomy_lib.topology._filtration import Filtration
+
+
+def _boundary_columns(filtration: Filtration) -> torch.Tensor:
+    """Build the padded boundary matrix of a filtration, with -1 for unused slots.
+
+    Takes a filtration whose complex is closed under taking faces. Returns an
+    `(n_total, max_dim + 1)` int64 tensor. Row j holds the filtration ids of the
+    faces of the simplex at filtration position j, and vertex rows are all -1.
+    """
+    complex = filtration.complex
+    n_total = filtration.birth_times.numel()
+    device = filtration.birth_times.device
+    columns = torch.full(
+        (n_total, complex.max_dim + 1), -1, dtype=torch.int64, device=device,
+    )
+    filtration_ids = torch.arange(n_total, device=device)
+    inverse_by_dim: dict[int, torch.Tensor] = {}
+    # Map each simplex's row within its dimension to its position in the
+    # filtration. Faces are found by row, so this inverse turns them into
+    # filtration ids.
+    for dim, simplices in complex.simplices_by_dim.items():
+        selected = filtration.sorted_dims == dim
+        inverse = torch.empty(simplices.shape[0], dtype=torch.int64, device=device)
+        inverse[filtration.sorted_indices[selected]] = filtration_ids[selected]
+        inverse_by_dim[dim] = inverse
+    for dim, simplices in complex.simplices_by_dim.items():
+        if dim == 0 or simplices.shape[0] == 0:
+            continue
+        # Each simplex has dim+1 faces. enumerate_faces lists them as vertex
+        # tuples, and lookup_rows finds each one's row in the dimension below.
+        # The reshape gives every simplex its own row of face rows.
+        faces, _ = enumerate_faces(simplices)
+        face_ids = lookup_rows(
+            complex.simplices_by_dim[dim - 1], faces.reshape(-1, dim),
+        ).reshape(simplices.shape[0], dim + 1)
+        columns[inverse_by_dim[dim], :dim + 1] = inverse_by_dim[dim - 1][face_ids]
+    return columns
+
+
+def _host_records(
+    filtration: Filtration, columns: torch.Tensor | None,
+) -> tuple[list[int], list[float], list[list[int]]]:
+    """Copy dims, birth times, and optional boundary columns to host lists.
+
+    Takes a filtration and the padded boundary matrix or None. Returns three
+    lists: the dim of each simplex, its birth time, and the columns as nested
+    lists of filtration ids (empty when `columns` is None). Everything goes
+    over in one device-to-host copy as raw bytes, so int64 indices never pass
+    through a float dtype.
+    """
+    dims = filtration.sorted_dims.contiguous()
+    births = filtration.birth_times.contiguous()
+    chunks = [dims.view(torch.uint8), births.view(torch.uint8)]
+    if columns is not None:
+        chunks.append(columns.contiguous().view(torch.uint8).flatten())
+    host = torch.cat(chunks).cpu()
+    dims_end = dims.numel() * dims.element_size()
+    births_end = dims_end + births.numel() * births.element_size()
+    host_dims = host[:dims_end].view(dims.dtype).tolist()
+    host_births = host[dims_end:births_end].view(births.dtype).tolist()
+    # Float births can leave the columns at a byte offset that is not a
+    # multiple of 8, and an int64 view needs that alignment. Cloning the slice
+    # gives it a fresh host buffer that starts at offset 0. This is a host
+    # copy, not another device transfer.
+    host_columns = (
+        host[births_end:].clone().view(columns.dtype).reshape(columns.shape).tolist()
+        if columns is not None else []
+    )
+    return host_dims, host_births, host_columns
+
+
+def reduce_filtration(
+    filtration: Filtration,
+    backend: Literal["python", "torch"] = "python",
+) -> dict[int, list[tuple[float, float]]]:
+    """Run sequential Z/2 reduction and return persistence pairs by dimension.
+
+    Args:
+      filtration: the simplex ordering produced by `build_filtration`.
+      backend: `"python"` for host set columns, or `"torch"` for index
+        tensors on the input device. Torch synchronizes for each pivot
+        attempt because the next column operation depends on that pivot.
+
+    Returns:
+      A dictionary keyed by homology dimension, holding the finite and
+      essential `(birth, death)` pairs. Essential bars have infinite death;
+      zero-length bars are omitted.
+
+    References:
+      Edelsbrunner, Letscher, Zomorodian (2002). Topological persistence
+        and simplification. Discrete & Computational Geometry 28:511-533.
+    """
+    if backend not in ("python", "torch"):
+        raise ValueError(f"backend must be 'python' or 'torch'; got {backend!r}")
+    boundary = _boundary_columns(filtration)
+    # The python backend needs the boundary on the host as sets. The torch
+    # backend keeps it on the device, so only dims and births are copied.
+    dims, births, host_columns = _host_records(
+        filtration, boundary if backend == "python" else None,
+    )
+    if backend == "torch":
+        pairs, pivots, empty = _reduce_torch(boundary, dims)
+    else:
+        # One set of filtration ids per column. A dim-0 simplex has no
+        # boundary, so its column starts out empty.
+        columns = [set(row[:dim + 1]) if dim else set()
+                   for row, dim in zip(host_columns, dims, strict=True)]
+        pairs, pivots, empty = _reduce_python(columns)
+
+    # Each pair joins a birth simplex to the simplex that kills it. A bar whose
+    # death is not after its birth has zero length and is dropped.
+    pairs_by_dim: dict[int, list[tuple[float, float]]] = {}
+    for birth_id, death_id in pairs:
+        birth, death = births[birth_id], births[death_id]
+        if birth < death:
+            pairs_by_dim.setdefault(dims[birth_id], []).append((birth, death))
+
+    # A zero column creates a class at its own index. If some column later has
+    # that index as its low, the class died there. The rest never die.
+    essential = torch.tensor(empty, dtype=torch.bool)
+    essential[list(pivots)] = False
+    for index in essential.nonzero().flatten().tolist():
+        pairs_by_dim.setdefault(dims[index], []).append((births[index], float("inf")))
+    return pairs_by_dim
+
+
+def _reduce_python(
+    columns: list[set[int]],
+) -> tuple[list[tuple[int, int]], dict[int, int], list[bool]]:
+    """Reduce the boundary columns left to right over Z/2.
+
+    Takes one set of filtration ids per simplex, in filtration order. Returns
+    the (low, index) pairs, a map from each low to the column that owns it,
+    and a flag per column that is True when the reduced column is zero.
+    Assumes the columns are in filtration order, since each column's pivot
+    depends only on the columns before it.
+    """
+    pivot_map: dict[int, int] = {}
+    pairs: list[tuple[int, int]] = []
+    for index, column in enumerate(columns):
+        while column:
+            # The low is the largest filtration id left in the column, which is
+            # the latest-born face. If an earlier column already owns that low,
+            # add that column in over Z/2 to cancel the face, then look again.
+            # Otherwise this column claims the low and is done.
+            low = max(column)
+            if low in pivot_map:
+                column ^= columns[pivot_map[low]]
+            else:
+                pivot_map[low] = index
+                pairs.append((low, index))
+                break
+    return pairs, pivot_map, [not column for column in columns]
+
+
+def _reduce_torch(
+    boundary: torch.Tensor, dims: list[int],
+) -> tuple[list[tuple[int, int]], dict[int, int], list[bool]]:
+    """Reduce the boundary columns on the device; same output as the python path.
+
+    Takes the padded boundary matrix and the dim of each simplex. Returns the
+    same triple as `_reduce_python`. Each pass through the loop reads the pivot
+    back with `.item()`, so every pivot attempt costs one device sync.
+    """
+    # Keep only the real faces of each row. Vertex rows have none, and the -1
+    # padding is cut off.
+    columns = [row[:dim + 1] if dim else row[:0]
+               for row, dim in zip(boundary.unbind(), dims, strict=True)]
+    pivot_map: dict[int, int] = {}
+    pairs: list[tuple[int, int]] = []
+    for index, column in enumerate(columns):
+        while column.numel():
+            # .item() copies the pivot to the host because the branch below
+            # depends on its value. This is the one sync per attempt.
+            low = int(column.max().item())
+            if low in pivot_map:
+                column = _xor_columns(column, columns[pivot_map[low]])
+                columns[index] = column
+            else:
+                pivot_map[low] = index
+                pairs.append((low, index))
+                break
+    return pairs, pivot_map, [column.numel() == 0 for column in columns]
+
+
+def _xor_columns(a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
+    """Return the Z/2 sum of two boundary columns as a sorted index tensor.
+
+    Takes two 1-D index tensors. Returns the entries that appear in exactly one
+    input, sorted ascending. Assumes no repeats within either input, since a
+    repeat would be counted as a second occurrence and cancel wrongly.
+    """
+    unique, counts = torch.unique(torch.cat((a, b)), return_counts=True)
+    return unique[counts % 2 == 1]

holonomy_lib/topology/hodge.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Hodge Laplacians + Betti numbers on simplicial complexes.
+
+The k-th Hodge Laplacian on a simplicial complex `K` is
+
+    L_k = ∂_{k+1} ∂_{k+1}^T + ∂_k^T ∂_k,
+
+acting on the space of k-chains `C_k(K) ≅ ℝ^{n_k}`. It generalizes
+the graph Laplacian (which is `L_0` for a 1-complex) to higher
+dimensions and connects spectral analysis to topology via the Hodge
+decomposition:
+
+    ker(L_k) ≅ H_k(K),   so   β_k = dim(ker(L_k)) = n_k − rank(L_k).
+
+For a topological invariant of `K`, `β_k` is the k-th Betti number:
+`β_0` counts connected components, `β_1` counts independent 1-cycles
+(holes), `β_2` counts independent voids, and so on.
+
+Two paths share the same public function `hodge_laplacian(complex, k)`:
+
+  Dense complex (`DenseSimplicialComplex`)
+    Boundary operators returned as dense `(B, n_{k-1}_max, n_k_max)`
+    tensors. The Hodge Laplacian is built via batched dense matmuls
+    and returned as `(B, n_k_max, n_k_max)`. Boundary and Laplacian
+    storage both scale with the padded batch dimensions.
+
+  Sparse complex (`SparseSimplicialComplex`)
+    Boundary operators returned as `torch.sparse_csc_tensor
+    (n_{k-1}, n_k)`. The Hodge Laplacian is built via sparse matmul
+    and returned as a dense `(n_k, n_k)` tensor. This avoids dense
+    boundary storage but still requires space for the final dense L_k.
+
+`betti_numbers(complex, max_dim)` returns the Betti numbers for dims
+0..max_dim from float64 boundary ranks. Rank tolerances use each
+member's real simplex counts, independently of batch padding.
+
+References:
+  Eckmann, B. (1944). Harmonische Funktionen und Randwertaufgaben in
+    einem Komplex. Commentarii Mathematici Helvetici 17:240–255.
+    The original Hodge-theoretic interpretation on simplicial
+    complexes.
+  Lim, L.-H. (2020). Hodge Laplacians on graphs. SIAM Review
+    62(3):685–715. Modern survey.
+  Schaub, M. T., Benson, A. R., Horn, P., Lippner, G., Jadbabaie, A.
+    (2020). Random walks on simplicial complexes and the normalized
+    Hodge 1-Laplacian. SIAM Review 62(2):353–391.
+  Ribando-Gros, E., Wang, R., Chen, J., Tong, Y., Wei, G.-W. (2024).
+    Combinatorial and Hodge Laplacians: Similarities and differences.
+    SIAM Review 66(3):575–601.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from holonomy_lib.simplicial import (
+    DenseSimplicialComplex,
+    SparseSimplicialComplex,
+)
+
+
+def hodge_laplacian(
+    complex: DenseSimplicialComplex | SparseSimplicialComplex,
+    k: int,
+) -> torch.Tensor:
+    """Hodge Laplacian `L_k = ∂_{k+1} ∂_{k+1}^T + ∂_k^T ∂_k`.
+
+    Args:
+      complex: a `DenseSimplicialComplex` (batched) or
+        `SparseSimplicialComplex` (single-instance).
+      k: simplex dimension. Must be in `[0, complex.max_dim]`.
+
+    Returns:
+      Dense complex  → `(B, n_k_max, n_k_max)` Tensor.
+      Sparse complex → `(n_k, n_k)` dense Tensor. Boundary products
+        are computed sparsely, then materialized for this return contract.
+
+    References:
+      Eckmann (1944). Harmonische Funktionen und Randwertaufgaben in
+        einem Komplex. Comment. Math. Helv. 17:240–255.
+      Lim (2020). Hodge Laplacians on graphs. SIAM Review 62:685–715.
+    """
+    if k < 0:
+        raise ValueError(f"k must be >= 0, got {k}")
+    if isinstance(complex, DenseSimplicialComplex):
+        return _hodge_dense(complex, k)
+    if isinstance(complex, SparseSimplicialComplex):
+        return _hodge_sparse(complex, k)
+    raise TypeError(
+        f"complex must be a Dense or Sparse SimplicialComplex; "
+        f"got {type(complex).__name__}"
+    )
+
+
+def betti_numbers(
+    complex: DenseSimplicialComplex | SparseSimplicialComplex,
+    max_dim: int,
+    threshold: float | None = None,
+) -> torch.Tensor:
+    """Betti numbers `(β_0, β_1, …, β_max_dim)` for a simplicial complex.
+
+    `β_k = n_k - rank(∂_k) - rank(∂_{k+1})`. Boundary entries are
+    exactly 0 or ±1, so ranks are computed in float64 regardless of
+    the complex's storage dtype. This avoids squaring the conditioning
+    by forming a Hodge Laplacian.
+
+    Args:
+      complex: a `DenseSimplicialComplex` or `SparseSimplicialComplex`.
+      max_dim: highest dim to return Betti numbers for. Must satisfy
+        `0 ≤ max_dim ≤ complex.max_dim`.
+      threshold: optional positive relative rank tolerance. With `None`,
+        each boundary uses `max(n_{k-1}, n_k) * eps(float64)`, with
+        real simplex counts for that batch member. An explicit value
+        applies to boundary singular values, with zero absolute tolerance.
+
+    Returns:
+      Dense complex  → `(B, max_dim + 1)` Tensor of int64 Betti numbers.
+      Sparse complex → `(max_dim + 1,)` Tensor.
+
+    Notes:
+      Dense boundaries retain zero padding for batched SVD; it adds only
+      zero singular values and does not enter the per-member tolerance.
+      Sparse boundaries are materialized for the rank computation.
+
+    References:
+      Eckmann (1944); kernel of L_k equals harmonic k-forms.
+      Lim (2020), §4.
+    """
+    if max_dim < 0:
+        raise ValueError(f"max_dim must be >= 0, got {max_dim}")
+    if max_dim > complex.max_dim:
+        raise ValueError(
+            f"max_dim={max_dim} exceeds complex.max_dim={complex.max_dim}"
+        )
+    if threshold is not None and threshold <= 0:
+        raise ValueError(f"threshold must be > 0, got {threshold}")
+
+    if isinstance(complex, DenseSimplicialComplex):
+        B = complex.batch_size
+        ranks = torch.zeros(B, max_dim + 2, dtype=torch.int64,
+                            device=complex.device)
+        for k in range(1, min(max_dim + 1, complex.max_dim) + 1):
+            boundary = complex.boundary(k).to(torch.float64)
+            relative_tol: float | torch.Tensor | None = threshold
+            if relative_tol is None:
+                real_size = torch.maximum(
+                    complex.n_simplices(k - 1), complex.n_simplices(k),
+                )
+                relative_tol = real_size.to(torch.float64) * torch.finfo(
+                    torch.float64,
+                ).eps
+            ranks[:, k] = torch.linalg.matrix_rank(boundary, rtol=relative_tol)
+        counts = torch.stack([
+            complex.n_simplices(k) for k in range(max_dim + 1)
+        ], dim=-1)
+        return counts - ranks[:, :-1] - ranks[:, 1:]
+
+    if isinstance(complex, SparseSimplicialComplex):
+        ranks = torch.zeros(max_dim + 2, dtype=torch.int64, device=complex.device)
+        for k in range(1, min(max_dim + 1, complex.max_dim) + 1):
+            boundary = complex.boundary(k, dtype=torch.float64).to_dense()
+            ranks[k] = torch.linalg.matrix_rank(boundary, rtol=threshold)
+        counts = torch.tensor([
+            complex.n_simplices(k) for k in range(max_dim + 1)
+        ], dtype=torch.int64, device=complex.device)
+        return counts - ranks[:-1] - ranks[1:]
+
+    raise TypeError(
+        f"complex must be a Dense or Sparse SimplicialComplex; "
+        f"got {type(complex).__name__}"
+    )
+
+
+# ============================================================
+# Internal: dispatched paths
+# ============================================================
+
+
+def _hodge_dense(
+    complex: DenseSimplicialComplex, k: int,
+) -> torch.Tensor:
+    """Hodge Laplacian L_k on a dense complex, batched over members.
+
+    Takes a `DenseSimplicialComplex` and k with k <= complex.max_dim. Returns a
+    `(B, n_k_max, n_k_max)` tensor in the complex dtype. Padded simplex rows
+    and columns are zero.
+    """
+    if k > complex.max_dim:
+        raise ValueError(
+            f"k={k} exceeds complex.max_dim={complex.max_dim}"
+        )
+
+    B = complex.batch_size
+    n_k_max = (
+        complex.simplices_by_dim[k].shape[1]
+        if k in complex.simplices_by_dim else 0
+    )
+    L = torch.zeros(B, n_k_max, n_k_max,
+                     device=complex.device, dtype=complex.dtype)
+
+    # The ∂_k^T ∂_k term. It is skipped for k = 0, since there are no
+    # (-1)-simplices.
+    if k > 0:
+        d_k = complex.boundary(k)                    # (B, n_{k-1}, n_k)
+        L = L + torch.matmul(d_k.mT, d_k)
+
+    # The ∂_{k+1} ∂_{k+1}^T term. It is skipped when the complex has no
+    # (k+1)-simplex table.
+    if (k + 1) in complex.simplices_by_dim:
+        d_kp1 = complex.boundary(k + 1)              # (B, n_k, n_{k+1})
+        L = L + torch.matmul(d_kp1, d_kp1.mT)
+
+    return L
+
+
+def _hodge_sparse(
+    complex: SparseSimplicialComplex, k: int,
+    dtype: torch.dtype = torch.float64,
+) -> torch.Tensor:
+    """Hodge Laplacian L_k on a sparse complex, returned as a dense (n_k, n_k).
+
+    Takes a `SparseSimplicialComplex` and k with k <= complex.max_dim. Each
+    boundary product is computed sparsely and densified once, then added into
+    the dense L_k, because the public return contract is dense.
+
+    `SparseSimplicialComplex` has no float dtype attribute, so the dtype is
+    passed in (default `torch.float64`). Both boundary operators are built at
+    this dtype so the matmul sees matching types.
+    """
+    if k > complex.max_dim:
+        raise ValueError(
+            f"k={k} exceeds complex.max_dim={complex.max_dim}"
+        )
+
+    n_k = complex.n_simplices(k)
+    device = complex.device
+    L = torch.zeros(n_k, n_k, device=device, dtype=dtype)
+
+    if k > 0:
+        d_k = complex.boundary(k, dtype=dtype)       # sparse (n_{k-1}, n_k)
+        d_k_coo = d_k.to_sparse_coo().coalesce()
+        L = L + torch.sparse.mm(d_k_coo.mT, d_k_coo).to_dense()
+
+    if (k + 1) in complex.simplices_by_dim:
+        d_kp1 = complex.boundary(k + 1, dtype=dtype).to_sparse_coo().coalesce()
+        L = L + torch.sparse.mm(d_kp1, d_kp1.mT).to_dense()
+
+    return L