holonomy-lib 0.8.0__py3-none-any.whl

holonomy_lib/simplicial/complex.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""DenseSimplicialComplex : batched simplicial complex with padded
+dense simplex tables.
+
+Used by Hodge Laplacians on small complexes (where batched dense
+eigh is fast) and by tutorials / illustration code. For large
+single-instance complexes (persistent homology), use
+`SparseSimplicialComplex`.
+
+Layout:
+  `simplices_by_dim[k]` is an `(B, n_k_max, k+1)` int64 tensor.
+  Each row holds a sorted tuple of vertex indices. Padding rows
+  (beyond the valid count for that batch element) are filled with
+  `-1` and masked off via `valid_mask[k]: (B, n_k_max) bool`.
+
+  This shape makes boundary operators naturally batched: one
+  `(B, n_{k-1}_max, n_k_max)` matrix per dim. Padding rows and columns
+  stay zero because only valid simplices write entries into it.
+
+References:
+  Munkres, J. R. (1984). Elements of Algebraic Topology. Westview
+    Press. §1 : simplicial complexes and chain complexes.
+  Kolda, T. G., Bader, B. W. (2009). Tensor decompositions and
+    applications. SIAM Review 51(3):455-500. (Tensor-layout
+    conventions reused here.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import torch
+
+from holonomy_lib.simplicial._face_lookup import enumerate_faces, lookup_rows
+
+if TYPE_CHECKING:
+    from holonomy_lib.simplicial.sparse_complex import SparseSimplicialComplex
+
+
+@dataclass(frozen=True)
+class DenseSimplicialComplex:
+    """Batched, padded simplicial complex.
+
+    Attributes:
+      simplices_by_dim: `dict[k, Tensor (B, n_k_max, k+1)]` of sorted
+        vertex tuples. Padding rows are -1.
+      valid_mask: `dict[k, Tensor (B, n_k_max) bool]` : True for real
+        simplices, False for padding.
+      n_vertices: vertex count (identical across batch elements).
+      device, dtype: tensor placement + float dtype used for boundary
+        operator returns.
+    """
+
+    simplices_by_dim: dict[int, torch.Tensor]
+    valid_mask: dict[int, torch.Tensor]
+    n_vertices: int
+    device: torch.device = field(default=torch.device("cpu"))
+    dtype: torch.dtype = field(default=torch.float64)
+
+    @property
+    def batch_size(self) -> int:
+        """Leading batch dim. All dims must agree on this."""
+        for tensor in self.simplices_by_dim.values():
+            return tensor.shape[0]
+        return 0
+
+    @property
+    def max_dim(self) -> int:
+        """Highest dimension with a table, including an empty table."""
+        return max(self.simplices_by_dim) if self.simplices_by_dim else -1
+
+    def n_simplices(self, k: int) -> torch.Tensor:
+        """Per-batch count of valid k-simplices: shape `(B,)`."""
+        if k not in self.simplices_by_dim:
+            return torch.zeros(self.batch_size, dtype=torch.int64,
+                                device=self.device)
+        return self.valid_mask[k].sum(dim=-1)
+
+    def boundary(self, k: int) -> torch.Tensor:
+        """Boundary operator `∂_k: C_k → C_{k-1}`.
+
+        Returns a dense `(B, n_{k-1}_max, n_k_max)` matrix; entries
+        `± 1` mark face → simplex incidences with the Koszul sign
+        `(-1)^i` (i = dropped-vertex position). Padding rows/columns
+        are zero.
+
+        Args:
+          k: simplex dimension. For k=0 the result is a `(B, 0, n_0_max)`
+            zero tensor, since vertices have an empty boundary in the chain
+            complex.
+
+        References:
+          Munkres, J. R. (1984). Elements of Algebraic Topology, §1.
+
+        Notes:
+          Assumes the complex is closed under faces. A face missing from
+          the (k-1) table raises ValueError from the lookup.
+        """
+        if k == 0:
+            # ∂_0 maps to the (-1)-chain group; conventionally zero.
+            # Return a (B, 0, n_0_max) zero tensor so downstream
+            # arithmetic (Hodge L_0 = ∂_0^T ∂_0 + ∂_1 ∂_1^T) reduces
+            # cleanly to ∂_1 ∂_1^T.
+            B = self.batch_size
+            n_0_max = (
+                self.simplices_by_dim[0].shape[1]
+                if 0 in self.simplices_by_dim else 0
+            )
+            return torch.zeros(B, 0, n_0_max,
+                                device=self.device, dtype=self.dtype)
+        if k not in self.simplices_by_dim or k - 1 not in self.simplices_by_dim:
+            raise ValueError(
+                f"boundary(k={k}): complex lacks simplices at dim {k} "
+                f"or {k - 1}"
+            )
+
+        B = self.batch_size
+        k_simplices = self.simplices_by_dim[k]            # (B, n_k_max, k+1)
+        prev_simplices = self.simplices_by_dim[k - 1]     # (B, n_{k-1}_max, k)
+        n_k_max = k_simplices.shape[1]
+        n_prev_max = prev_simplices.shape[1]
+        k_valid = self.valid_mask[k]                      # (B, n_k_max)
+        prev_valid = self.valid_mask[k - 1]
+
+        D = torch.zeros(B, n_prev_max, n_k_max,
+                         device=self.device, dtype=self.dtype)
+
+        # Keys are (batch id, vertices), so a face in another batch member
+        # cannot stand in for a missing face here. lookup_rows indexes only
+        # the valid rows of the previous dimension, so prev_row maps that
+        # index back to the padded row position.
+        simplex_batch, simplex_col = torch.where(k_valid)  # padded columns
+        prev_batch, prev_row = torch.where(prev_valid)
+        faces, signs = enumerate_faces(k_simplices[k_valid])
+        face_keys = torch.cat((
+            simplex_batch[:, None, None].expand(-1, k + 1, 1), faces,
+        ), dim=-1).reshape(-1, k + 1)
+        prev_keys = torch.cat((prev_batch[:, None], prev_simplices[prev_valid]),
+                              dim=-1)
+        face_rows = prev_row[lookup_rows(prev_keys, face_keys)]
+        # One entry per (simplex, face) pair, flattened simplex-major and
+        # face-minor. repeat_interleave builds the index lists in that order,
+        # and repeat builds the signs in the same order.
+        D[simplex_batch.repeat_interleave(k + 1), face_rows,
+          simplex_col.repeat_interleave(k + 1)] = signs.to(self.dtype).repeat(
+              simplex_col.shape[0],
+          )
+        return D
+
+    def to_sparse(self) -> SparseSimplicialComplex:
+        """Convert to a single-instance sparse complex. Requires `B = 1`."""
+        from holonomy_lib.simplicial.sparse_complex import SparseSimplicialComplex
+        if self.batch_size != 1:
+            raise ValueError(
+                f"to_sparse() requires batch_size == 1, got {self.batch_size}"
+            )
+        sparse_simplices: dict[int, torch.Tensor] = {}
+        for k, table in self.simplices_by_dim.items():
+            valid = self.valid_mask[k][0]
+            sparse_simplices[k] = table[0][valid]
+        return SparseSimplicialComplex(
+            simplices_by_dim=sparse_simplices,
+            n_vertices=self.n_vertices,
+            device=self.device,
+        )

holonomy_lib/simplicial/sparse_complex.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""SparseSimplicialComplex : single-instance simplicial complex with
+sparse-CSC boundary operators.
+
+Used by persistent homology (where the matrix-reduction kernel walks
+the sparse boundary matrix column by column) and by Hodge Laplacians
+on large complexes where dense `(n, n)` doesn't fit.
+
+No batch dimension: persistent homology operates on one complex at a
+time (the batching for PH happens at a higher level, calling this
+class once per point cloud). For batched small complexes, use
+`DenseSimplicialComplex` and the dense Hodge path.
+
+References:
+  Saad, Y. (2003). Iterative Methods for Sparse Linear Systems, 2nd
+    ed. SIAM. §3.4 : CSR and CSC formats.
+  Edelsbrunner, H., Letscher, D., Zomorodian, A. (2002). Topological
+    persistence and simplification. Discrete & Computational Geometry
+    28:511-533. Original sparse-boundary reduction algorithm.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import torch
+
+from holonomy_lib.simplicial._face_lookup import enumerate_faces, lookup_rows
+
+if TYPE_CHECKING:
+    from holonomy_lib.simplicial.complex import DenseSimplicialComplex
+
+
+@dataclass(frozen=True)
+class SparseSimplicialComplex:
+    """Single-instance simplicial complex.
+
+    Attributes:
+      simplices_by_dim: `dict[k, Tensor (n_k, k+1)]` of sorted vertex
+        tuples. No batch dim, no padding.
+      n_vertices: vertex count.
+      device: tensor placement.
+    """
+
+    simplices_by_dim: dict[int, torch.Tensor]
+    n_vertices: int
+    device: torch.device = field(default=torch.device("cpu"))
+
+    @property
+    def max_dim(self) -> int:
+        """Highest dimension with a table, including an empty table."""
+        return max(self.simplices_by_dim) if self.simplices_by_dim else -1
+
+    def n_simplices(self, k: int) -> int:
+        """Number of k-simplices. Returns 0 when there is no table for dimension k."""
+        if k not in self.simplices_by_dim:
+            return 0
+        return self.simplices_by_dim[k].shape[0]
+
+    def boundary(
+        self, k: int, dtype: torch.dtype = torch.float64,
+    ) -> torch.Tensor:
+        """Sparse-CSC boundary operator `∂_k: C_k → C_{k-1}`.
+
+        Returns a sparse-CSC `(n_{k-1}, n_k)` tensor; entries are
+        `± 1` with the Koszul sign for each face → simplex incidence.
+
+        Args:
+          k: simplex dimension. `k = 0` returns an empty `(0, n_0)`
+            sparse tensor (vertices have empty boundary).
+          dtype: float dtype for the matrix values.
+
+        References:
+          Munkres, J. R. (1984). Elements of Algebraic Topology, §1.
+
+        Notes:
+          Assumes the complex is closed under faces. A face missing from
+          the (k-1) table raises ValueError from the lookup.
+        """
+        if k == 0:
+            n_0 = self.n_simplices(0)
+            # No row indices and every column pointer is 0, so each of the
+            # n_0 columns is empty.
+            return torch.sparse_csc_tensor(
+                ccol_indices=torch.zeros(n_0 + 1, dtype=torch.int64,
+                                          device=self.device),
+                row_indices=torch.zeros(0, dtype=torch.int64,
+                                         device=self.device),
+                values=torch.zeros(0, dtype=dtype, device=self.device),
+                size=(0, n_0),
+            )
+        if k not in self.simplices_by_dim or k - 1 not in self.simplices_by_dim:
+            raise ValueError(
+                f"boundary(k={k}): complex lacks simplices at dim {k} "
+                f"or {k - 1}"
+            )
+
+        k_simplices = self.simplices_by_dim[k]            # (n_k, k+1)
+        prev_simplices = self.simplices_by_dim[k - 1]     # (n_{k-1}, k)
+        n_k = k_simplices.shape[0]
+        n_prev = prev_simplices.shape[0]
+
+        faces, signs = enumerate_faces(k_simplices)
+        rows = lookup_rows(prev_simplices, faces.reshape(-1, k))
+        cols = torch.arange(n_k, device=self.device).repeat_interleave(k + 1)
+        vals = signs.to(dtype).repeat(n_k)
+
+        # Build the entries as COO, which takes (row, column) pairs directly.
+        # coalesce sorts them by row then column, and to_sparse_csc then
+        # compresses the column indices into the CSC layout.
+        coo = torch.sparse_coo_tensor(
+            indices=torch.stack([rows, cols]),
+            values=vals,
+            size=(n_prev, n_k),
+        ).coalesce()
+        return coo.to_sparse_csc()
+
+    def to_dense(
+        self, dtype: torch.dtype = torch.float64,
+    ) -> DenseSimplicialComplex:
+        """Convert to a batched-with-B=1 dense complex.
+
+        Args:
+          dtype: float dtype for boundary matrix returns in the dense
+            complex.
+        """
+        from holonomy_lib.simplicial.complex import DenseSimplicialComplex
+        dense_simplices: dict[int, torch.Tensor] = {}
+        valid_masks: dict[int, torch.Tensor] = {}
+        for k, table in self.simplices_by_dim.items():
+            dense_simplices[k] = table.unsqueeze(0)         # (1, n_k, k+1)
+            # A single complex has no padding, so every row is a real simplex.
+            valid_masks[k] = torch.ones(
+                1, table.shape[0], dtype=torch.bool, device=self.device,
+            )
+        return DenseSimplicialComplex(
+            simplices_by_dim=dense_simplices,
+            valid_mask=valid_masks,
+            n_vertices=self.n_vertices,
+            device=self.device,
+            dtype=dtype,
+        )

holonomy_lib/simplicial/vietoris_rips.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Vietoris-Rips complex from a point cloud or distance matrix.
+
+The Vietoris-Rips complex `VR(X, r)` of a metric space `X` at scale
+`r` is the simplicial complex whose k-simplex `[v_0, ..., v_k]`
+exists iff `d(v_i, v_j) ≤ r` for every pair `(i, j)`. It's the
+standard finite-scale approximation to the (typically infinite)
+Čech complex and the input to most persistent-homology pipelines.
+
+Construction extends each existing simplex by larger vertex indices.
+Candidates are checked in configurable tiles; no batch, vertex, or simplex
+is traversed individually in Python. Dimension progression is sequential
+because a k-simplex is extended from a (k-1)-simplex. The worst case still
+has combinatorial output size. Tiles bound candidate working memory, not
+the size of the returned complex.
+
+References:
+  Hausmann, J.-C. (1995). On the Vietoris-Rips complexes and a
+    cohomology theory for metric spaces. In Prospects in Topology,
+    Annals of Math Studies 138.
+  Bauer, U. (2021). Ripser: efficient computation of Vietoris-Rips
+    persistence barcodes. J. Appl. Comput. Topology 5:391-423.
+    Implementation references for incremental k-simplex construction.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from holonomy_lib.simplicial.complex import DenseSimplicialComplex
+from holonomy_lib.simplicial.sparse_complex import SparseSimplicialComplex
+
+# Each tile evaluates at most this many extension candidates, so the temporary
+# index and bool tables stay at O(tile * simplex_width) entries. It is a memory
+# budget with no effect on results. Raise it on large-memory devices for fewer
+# kernel launches. Cataloged in notes/magic_numbers.md.
+VR_CANDIDATE_TILE_DEFAULT = 1024
+
+
+def _rips_tables(
+    distances: torch.Tensor, max_radius: float, max_dim: int,
+    candidate_tile_size: int,
+) -> dict[int, tuple[torch.Tensor, torch.Tensor]]:
+    """Build the simplex table of every dimension up to `max_dim`.
+
+    Takes `(B, n, n)` distances, the radius cap, the top dimension, and the
+    candidate tile size. Returns a dict from dimension to `(batch_ids, simplices)`,
+    where `batch_ids` is `(m,)` and `simplices` is `(m, dim + 1)` vertex indices.
+    Rows are grouped by batch member and sorted lexicographically within each
+    member. Only pairs with i < j are read, so the distances are assumed symmetric.
+    """
+    if distances.ndim != 2 + 1 or distances.shape[-1] != distances.shape[-2]:
+        raise ValueError(
+            f"distances must be (B, n, n); got {tuple(distances.shape)}"
+        )
+    if not distances.is_floating_point():
+        raise ValueError("distances must have a real floating dtype")
+    if not isinstance(max_dim, int) or max_dim < 0:
+        raise ValueError(f"max_dim must be a nonnegative integer, got {max_dim}")
+    if not isinstance(candidate_tile_size, int) or candidate_tile_size <= 0:
+        raise ValueError("candidate_tile_size must be a positive integer")
+    if max_radius < 0:
+        raise ValueError("max_radius must be nonnegative")
+
+    batch_size, n_vertices, _ = distances.shape
+    device = distances.device
+    vertex_ids = torch.arange(n_vertices, device=device)
+    batch_ids = torch.arange(batch_size, device=device)
+    tables = {0: (
+        batch_ids.repeat_interleave(n_vertices),
+        vertex_ids.expand(batch_size, -1).reshape(-1, 1),
+    )}
+    if max_dim == 0:
+        return tables
+
+    # Pairs within the cap. The diagonal passes too, but the i < j mask below
+    # removes it.
+    adjacency = distances <= max_radius
+    # torch.where returns indices in row-major order, so edges come out grouped
+    # by batch member and sorted by (i, j).
+    edge_batch, edge_left, edge_right = torch.where(
+        adjacency & (vertex_ids[:, None] < vertex_ids[None, :]),
+    )
+    tables[1] = (edge_batch, torch.stack((edge_left, edge_right), dim=-1))
+    for dim in range(2, max_dim + 1):
+        previous_batch, previous = tables[dim - 1]
+        chunks: list[torch.Tensor] = []
+        batch_chunks: list[torch.Tensor] = []
+        # A candidate is a parent simplex plus one extra vertex. Requiring the
+        # extra vertex to exceed the parent's largest vertex gives every simplex
+        # exactly one parent: the simplex with its largest vertex removed.
+        n_candidates = previous.shape[0] * n_vertices
+        for start in range(0, n_candidates, candidate_tile_size):
+            candidate_ids = torch.arange(
+                start, min(start + candidate_tile_size, n_candidates),
+                device=device,
+            )
+            # Each candidate id encodes (parent row, extra vertex) as
+            # parent * n_vertices + extra.
+            parent_ids = candidate_ids // n_vertices
+            extra_vertices = candidate_ids % n_vertices
+            # Only extra vertices above the parent's largest vertex are canonical.
+            ordered = extra_vertices > previous[parent_ids, -1]
+            parent_ids = parent_ids[ordered]
+            extra_vertices = extra_vertices[ordered]
+            parents = previous[parent_ids]
+            batches = previous_batch[parent_ids]
+            # The parent's own edges already passed, so only the new vertex's
+            # edges to the parent's vertices need checking.
+            cofaceable = adjacency[
+                batches[:, None], parents, extra_vertices[:, None],
+            ].all(dim=-1)
+            chunks.append(torch.cat((
+                parents[cofaceable], extra_vertices[cofaceable, None],
+            ), dim=-1))
+            batch_chunks.append(batches[cofaceable])
+        tables[dim] = (
+            torch.cat(batch_chunks) if batch_chunks else batch_ids[:0],
+            torch.cat(chunks) if chunks else torch.empty(
+                (0, dim + 1), device=device, dtype=torch.int64,
+            ),
+        )
+    return tables
+
+
+def vietoris_rips_sparse(
+    distances: torch.Tensor,
+    max_radius: float,
+    max_dim: int,
+    *,
+    candidate_tile_size: int = VR_CANDIDATE_TILE_DEFAULT,
+) -> SparseSimplicialComplex:
+    """Vietoris-Rips complex from a single distance matrix.
+
+    Args:
+      distances: `(n, n)` symmetric real distance matrix.
+      max_radius: include only pairs with `d <= max_radius`.
+      max_dim: build simplex tables through this dimension, including
+        empty tables where no simplex exists.
+      candidate_tile_size: maximum number of simplex-extension candidates
+        evaluated at once. It bounds temporary storage, not output size.
+
+    Returns:
+      Single-instance complex on the input device.
+
+    Notes:
+      Dimensions are constructed sequentially because each extension uses
+      the preceding dimension. Candidates within a tile are tensorized.
+
+    References:
+      Hausmann, J.-C. (1995). On the Vietoris-Rips complexes and a
+        cohomology theory for metric spaces. In Prospects in Topology,
+        Annals of Math Studies 138.
+      Bauer, U. (2021). Ripser: efficient computation of Vietoris-Rips
+        persistence barcodes. J. Appl. Comput. Topology 5:391-423.
+    """
+    if distances.ndim != 2 or distances.shape[0] != distances.shape[1]:
+        raise ValueError(
+            f"distances must be (n, n); got {tuple(distances.shape)}"
+        )
+    tables = _rips_tables(
+        distances.unsqueeze(0), max_radius, max_dim, candidate_tile_size,
+    )
+    return SparseSimplicialComplex(
+        simplices_by_dim={dim: table for dim, (_, table) in tables.items()},
+        n_vertices=distances.shape[-1], device=distances.device,
+    )
+
+
+def vietoris_rips_dense(
+    distances: torch.Tensor,
+    max_radius: float,
+    max_dim: int,
+    dtype: torch.dtype | None = None,
+    *,
+    candidate_tile_size: int = VR_CANDIDATE_TILE_DEFAULT,
+) -> DenseSimplicialComplex:
+    """Batched Vietoris-Rips construction with padded simplex tables.
+
+    Args:
+      distances: `(B, n, n)` symmetric real distance matrices.
+      max_radius: include pairs with `d <= max_radius`.
+      max_dim: build tables through this dimension, including empty ones.
+      dtype: boundary-operator dtype; defaults to the distances' dtype.
+      candidate_tile_size: maximum number of simplex-extension candidates
+        evaluated at once. It bounds temporary storage, not output size.
+
+    Returns:
+      A complex with per-batch padded simplex tables on the input device.
+      Empty batches retain all requested dimensions.
+
+    Notes:
+      Batch members share tensor candidate evaluation and packing. Only
+      dimensions and memory tiles are traversed in Python. Dimension
+      progression is sequential because extensions require their parents.
+
+    References:
+      Hausmann, J.-C. (1995). On the Vietoris-Rips complexes and a
+        cohomology theory for metric spaces.
+      Bauer, U. (2021). Ripser: efficient computation of Vietoris-Rips
+        persistence barcodes. J. Appl. Comput. Topology 5:391-423.
+    """
+    tables = _rips_tables(distances, max_radius, max_dim, candidate_tile_size)
+    batch_size = distances.shape[0]
+    device = distances.device
+    simplices_by_dim: dict[int, torch.Tensor] = {}
+    valid_mask: dict[int, torch.Tensor] = {}
+    for dim, (batches, table) in tables.items():
+        counts = torch.bincount(batches, minlength=batch_size)
+        # The padded width is the largest count over batch members, which only
+        # the data can tell us. int() syncs the device once per dimension
+        # before the output table is allocated.
+        width = int(counts.max()) if batch_size else 0
+        # Every member has exactly n vertices, so dim 0 uses n directly. That
+        # also keeps the width right when the batch is empty.
+        if dim == 0:
+            width = distances.shape[-1]
+        padded = torch.full(
+            (batch_size, width, dim + 1), -1,
+            dtype=torch.int64, device=device,
+        )
+        mask = torch.zeros(batch_size, width, dtype=torch.bool, device=device)
+        # Tables are sorted by batch id, so member b's rows are contiguous and
+        # start at offsets[b]. columns is each row's slot inside its member's
+        # padded block.
+        offsets = counts.cumsum(0) - counts
+        columns = torch.arange(table.shape[0], device=device) - offsets[batches]
+        padded[batches, columns] = table
+        mask[batches, columns] = True
+        simplices_by_dim[dim] = padded
+        valid_mask[dim] = mask
+    return DenseSimplicialComplex(
+        simplices_by_dim=simplices_by_dim, valid_mask=valid_mask,
+        n_vertices=distances.shape[-1], device=device,
+        dtype=distances.dtype if dtype is None else dtype,
+    )
+
+
+def pairwise_distances(points: torch.Tensor) -> torch.Tensor:
+    """Pairwise Euclidean distances.
+
+    Args:
+      points: `(n, d)` or `(B, n, d)`.
+
+    Returns:
+      `(n, n)` or `(B, n, n)` distance matrix on the input device and dtype.
+
+    Notes:
+      Half and bfloat16 inputs use float32 intermediates because cdist's
+      direct CPU kernel does not support these dtypes.
+
+    References:
+      Standard Euclidean distance. See e.g. Hartle, J. B. (2003),
+        Gravity: An Introduction to Einstein's General Relativity,
+        §2.1 for the abstract metric formulation; computationally
+        we use `||p - q||_2` directly.
+    """
+    if points.ndim != 2 and points.ndim != 2 + 1:
+        raise ValueError(
+            f"points must be (n, d) or (B, n, d); got {tuple(points.shape)}"
+        )
+    if not points.is_floating_point():
+        raise ValueError("points must have a real floating dtype")
+    # cdist's CPU kernel only accepts float32/float64. Evaluate low-precision
+    # inputs in float32 and return their original dtype on the same device.
+    working = (
+        points.float() if points.dtype in (torch.float16, torch.bfloat16) else points
+    )
+    # The direct kernel avoids the cancellation in the matrix-multiplication
+    # identity ||p||^2 + ||q||^2 - 2 p.q, which loses digits for nearly
+    # coincident points. Those small distances are the first edges the
+    # filtration adds.
+    return torch.cdist(
+        working, working, compute_mode="donot_use_mm_for_euclid_dist",
+    ).to(points.dtype)

holonomy_lib/spectral/__init__.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""holonomy_lib.spectral: graph Laplacians and spectral utilities.
+
+Public names:
+  laplacian.combinatorial(A)        : L = D - A
+  laplacian.symmetric_normalized(A)   : L_sym = I - D^{-1/2} A D^{-1/2}
+  laplacian.random_walk(A)            : L_rw = I - D^{-1} A
+  laplacian.signed(A)                 : L^sigma = D^{|sigma|} - A
+                                          (Kunegis 2010)
+  laplacian.degree(A)                 : degree vector (signed-aware)
+  magnetic.combinatorial(A, q)        : Hermitian Laplacian on directed
+                                          graphs (Furutani 2020, Fanuel 2017)
+  magnetic.symmetric_normalized(A, q) : normalized magnetic Laplacian,
+                                          spectrum in [0, 2]
+  magnetic.sign_magnetic_combinatorial(A, q)
+                                      : signed-directed Hermitian
+                                          Laplacian; unifies Kunegis
+                                          signed and magnetic
+                                          (He et al. 2022, MSGNN)
+  magnetic.sign_magnetic_symmetric_normalized(A, q)
+                                      : normalized signed-directed form
+  laplacian_eigenmaps(A, k, ...)      : bottom-k spectral embedding
+  spectral_dimension(eigenvalues, t)  : d_s = -2 d log p / d log t from the
+                                          heat-kernel return decay
+                                          (Rammal-Toulouse 1983)
+  diffusion_map(A, k, t)              : diffusion-map embedding at time t
+                                          (Coifman-Lafon 2006)
+  effective_resistance(A)             : pairwise effective resistance
+  commute_time(A)                     : pairwise commute time, vol(component) R
+  heat_kernel_chebyshev(L, t, signal=None) : exp(-t L), or exp(-t L) @ signal,
+                                          by a Chebyshev polynomial expansion
+"""
+
+from holonomy_lib.spectral import laplacian, magnetic
+from holonomy_lib.spectral.diffusion_map import diffusion_map
+from holonomy_lib.spectral.effective_resistance import (
+    commute_time,
+    effective_resistance,
+)
+from holonomy_lib.spectral.embedding import laplacian_eigenmaps
+from holonomy_lib.spectral.heat_kernel import heat_kernel_chebyshev
+from holonomy_lib.spectral.spectral_dimension import spectral_dimension
+
+__all__ = [
+    "commute_time",
+    "diffusion_map",
+    "effective_resistance",
+    "heat_kernel_chebyshev",
+    "laplacian",
+    "laplacian_eigenmaps",
+    "magnetic",
+    "spectral_dimension",
+]