holonomy-lib 0.8.0__py3-none-any.whl

holonomy_lib/spectral/diffusion_map.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Diffusion-map embedding (Coifman-Lafon 2006).
+
+Given an undirected weighted graph `A`, the random walk on its nodes
+has a transition matrix `P = D⁻¹ A`. The eigendecomposition of `P`
+gives the long-time behavior of the random walk: for an eigenpair
+(μ_j, φ_j), starting at node `x_i` and taking `t` random-walk steps,
+the probability of arriving at `x_l` is
+
+    P^t(x_i, x_l) = π(x_l) Σ_j μ_j^t · φ_j(x_i) · φ_j(x_l),
+
+where π(x_l) = d_l / vol(A), and the right eigenvectors φ_j are
+orthonormal under the π-weighted inner product.
+
+The **diffusion map** at time `t` lifts each node to a `k`-dimensional
+Euclidean point whose pairwise distances mirror the diffusion-time `t`
+random walk distance:
+
+    Ψ_t(x_i) = ( μ_1^t · φ_1(x_i), …, μ_k^t · φ_k(x_i) )
+
+    D_t(x_i, x_l)² = ‖ Ψ_t(x_i) − Ψ_t(x_l) ‖²
+                   = Σ_j μ_j^{2t} · ( φ_j(x_i) − φ_j(x_l) )²
+
+The trivial top eigenpair (μ_1 = 1, φ_1 = constant) is dropped; it
+encodes only "we're somewhere on the graph", carrying no metric
+information.
+
+Implementation: take the full spectrum of the random-walk Laplacian
+(`laplacian_eigenmaps` with `k = n`), drop its smallest eigenvalue, and
+convert the rest to transition eigenvalues `μ_j = 1 − λ_j`. Keep the k
+modes with the largest |μ_j|. The right eigenvectors are unit-norm
+eigenvectors of L_sym scaled by D^{-1/2}, which makes their π-weighted
+squared norm 1/vol(A). Multiplying by sqrt(vol(A)) puts them in the π
+normalization. Last, each mode is raised to the signed integer power μ_j^t.
+
+Each connected component with edges gives one zero Laplacian eigenvalue,
+and those eigenvectors span the component indicators. Dropping index 0
+removes only one direction from that span, so the others stay in the
+embedding. Callers on disconnected graphs should mask by component
+membership before reading cross-component distances.
+
+References:
+  Coifman, R. R., Lafon, S. (2006). Diffusion maps. Applied and
+    Computational Harmonic Analysis 21(1):5–30. The defining paper.
+  Lafon, S., Lee, A. B. (2006). Diffusion maps and coarse-graining:
+    A unified framework for dimensionality reduction, graph
+    partitioning, and data set parameterization. IEEE PAMI 28(9):
+    1393–1403.
+  Nadler, B., Lafon, S., Coifman, R. R., Kevrekidis, I. G. (2006).
+    Diffusion maps, spectral clustering and reaction coordinates of
+    dynamical systems. Applied and Computational Harmonic Analysis
+    21(1):113–127.
+"""
+
+from __future__ import annotations
+
+import warnings
+from numbers import Integral
+
+import torch
+
+from holonomy_lib._graph_utils import drop_self_loops
+from holonomy_lib.spectral import laplacian as _L
+from holonomy_lib.spectral.embedding import laplacian_eigenmaps
+
+# The normalized Laplacian of a nonnegative undirected graph has spectrum
+# in [0, 2] (Chung, Spectral Graph Theory, 1997, Lemma 1.7).
+NORMALIZED_LAPLACIAN_SPECTRAL_RADIUS = 2.0
+
+
+def diffusion_map(
+    A: torch.Tensor,
+    k: int,
+    t: int = 1,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Diffusion-map embedding at time `t`.
+
+    Args:
+      A: (B, n, n) symmetric non-negative weighted adjacency.
+      k: embedding dimension. Must satisfy `1 ≤ k ≤ n − 1` (we drop the
+        trivial null eigenvector, leaving `n − 1` non-trivial modes).
+      t: nonnegative integer number of random-walk steps. Larger `t`
+        emphasizes modes whose transition eigenvalues have magnitude
+        close to one. Negative eigenvalues retain their signed powers.
+
+    Returns:
+      transition_eigvals: (B, k) eigenvalues μ_j = 1 − λ_j of the
+        transition matrix P (descending in magnitude).
+      embedding: (B, n, k) diffusion coordinates `Ψ_t(x_i)`.
+
+    Notes:
+      Cost is dominated by the eigendecomposition of L_sym, O(B · n³).
+      Disconnected graphs emit a warning and retain all but one stationary
+      mode. Isolated nodes have no positive stationary mass; their coordinates
+      are set to zero, and diffusion distances involving them are undefined.
+
+    References:
+      Coifman, R. R., Lafon, S. (2006). Diffusion maps. Applied and
+        Computational Harmonic Analysis 21(1):5-30, §2.3-2.4.
+    """
+    if A.ndim < 2 or A.shape[-1] != A.shape[-2]:
+        raise ValueError(
+            f"A must be (..., n, n); got A.shape={tuple(A.shape)}"
+        )
+    if not A.is_floating_point():
+        raise ValueError("A must have a real floating-point dtype")
+    # Zero the diagonal so self-loops count neither as walk steps nor toward degree.
+    A = drop_self_loops(A)
+    n = A.shape[-1]
+    if k <= 0 or k > n - 1:
+        raise ValueError(
+            f"k must satisfy 1 <= k <= n - 1 = {n - 1}, got k={k}"
+        )
+    # bool is a subclass of int, so without this check True would pass as t = 1.
+    if isinstance(t, bool) or not isinstance(t, Integral) or t < 0:
+        raise ValueError(f"diffusion time t must be a nonnegative integer, got {t}")
+    if (A < 0).any():
+        raise ValueError("A must have nonnegative weights")
+
+    # The k smallest Laplacian eigenvalues are not enough. A mode with a
+    # strongly negative transition eigenvalue (λ near 2 gives μ near -1)
+    # sits at the top of the spectrum, so take all of it and sort by |μ| below.
+    eigvals, eigvecs = laplacian_eigenmaps(
+        A, k=n, laplacian_type="random_walk",
+    )
+    degree = _L.degree(A)
+    # The normalized Laplacian's spectrum is in [0, 2] whatever the scale of A.
+    # Eigensolver roundoff grows with n, so the zero test uses eps * n * 2,
+    # which does not depend on the weights.
+    tolerance = torch.finfo(A.dtype).eps * n * NORMALIZED_LAPLACIAN_SPECTRAL_RADIUS
+    counts = (eigvals.abs() <= tolerance).sum(dim=-1)
+    # .item() syncs once, so the warning can be decided on the host.
+    n_near_zero = int(counts.max().item()) if counts.numel() else 0
+    has_isolates = bool((degree == 0).any())
+    # Each connected component with edges has one zero eigenvalue. Only index 0
+    # is dropped below, so the other zero modes stay in the embedding and the
+    # warning is raised.
+    if n_near_zero > 1 or has_isolates:
+        warnings.warn(
+            "diffusion_map: input graph is disconnected or has isolated nodes. "
+            "Only one stationary mode is dropped; interpret distances within "
+            "components with positive stationary mass. Isolated coordinates "
+            "are set to zero.",
+            stacklevel=2,
+        )
+    # Index 0 is the smallest eigenvalue, about 0. For a connected graph its
+    # eigenvector is constant, the trivial mode the docstring drops.
+    eigvals_non_null = eigvals[..., 1:]
+    eigvecs_non_null = eigvecs[..., 1:]
+
+    # L_rw = I − P, so each transition eigenvalue is μ = 1 − λ. Signs survive.
+    transition_eigvals = 1.0 - eigvals_non_null
+    # Keep the k modes with the largest |μ|. A kept mode may have μ < 0.
+    order = transition_eigvals.abs().argsort(dim=-1, descending=True)[..., :k]
+    transition_eigvals = transition_eigvals.gather(-1, order)
+    eigvecs_non_null = eigvecs_non_null.gather(
+        -1, order.unsqueeze(-2).expand(*A.shape[:-2], n, k),
+    )
+    # sqrt(vol(A)) brings each eigenvector to unit π-norm (see the module docstring).
+    volume_scale = degree.sum(dim=-1).sqrt().unsqueeze(-1).unsqueeze(-1)
+    embedding = eigvecs_non_null * volume_scale
+    # An isolated node has no stationary mass, so its row is zeroed. Its
+    # eigenvector there is not a diffusion coordinate.
+    embedding = torch.where((degree > 0).unsqueeze(-1), embedding, 0.0)
+    # Ψ_t: each mode scaled by μ_j^t. A negative μ_j keeps its sign for odd t.
+    embedding = embedding * transition_eigvals.pow(int(t)).unsqueeze(-2)
+    return transition_eigvals, embedding

holonomy_lib/spectral/effective_resistance.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Effective resistance and commute-time distances on graphs.
+
+For an undirected weighted graph, the **effective resistance**
+`R(u, v)` between nodes u and v is the resistance the graph presents
+when each edge is treated as a resistor of conductance `A_{ij}`
+(weight) and we measure between nodes u and v. The classical formula
+(Klein-Randić 1993, Doyle-Snell 1984) is
+
+    R(u, v) = (e_u − e_v)ᵀ L⁺ (e_u − e_v)
+            = L⁺[u, u] − 2 L⁺[u, v] + L⁺[v, v]
+
+where `L⁺` is the Moore-Penrose pseudoinverse of the combinatorial
+graph Laplacian `L = D − A`. The **commute time** is
+
+    C(u, v) = 2 · ‖A‖₁ / 2 · R(u, v) = vol(A) · R(u, v)
+
+with `vol(A) = Σ_ij A_{ij}` the total edge weight (Chandra et al. 1996,
+Lovász 1993). Both are metric distances on connected graphs.
+
+These primitives are useful for:
+  - Graph kernels and similarity through the Laplacian pseudoinverse.
+  - Spectral sparsification (Spielman-Srivastava 2008 sample edges by
+    effective resistance).
+  - Random walk analysis (commute time = expected round-trip).
+
+Different connected components have infinite resistance and commute
+time, since no current or random walk can pass between them. Within a
+component, commute time uses that component's volume. Isolated nodes
+have zero distance to themselves and infinite distance to every other node.
+
+References:
+  Doyle, P. G., Snell, J. L. (1984). Random Walks and Electric
+    Networks. Mathematical Association of America (Carus Math.
+    Monographs 22). The foundational electrical-network treatment.
+  Klein, D. J., Randić, M. (1993). Resistance distance. Journal of
+    Mathematical Chemistry 12(1):81–95. Coined the term "resistance
+    distance" and gave the closed-form in terms of L⁺.
+  Chandra, A. K., Raghavan, P., Ruzzo, W. L., Smolensky, R., Tiwari, P.
+    (1996). The electrical resistance of a graph captures its commute
+    and cover times. Computational Complexity 6(4):312–340. The
+    `C(u, v) = vol(A) · R(u, v)` identity.
+  Spielman, D. A., Srivastava, N. (2011). Graph sparsification by
+    effective resistances. SIAM Journal on Computing 40(6):1913–1926.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from holonomy_lib._graph_utils import drop_self_loops
+from holonomy_lib.spectral import laplacian as _L
+
+
+def effective_resistance(A: torch.Tensor) -> torch.Tensor:
+    """Pairwise effective resistance R(u, v) for a batched weighted graph.
+
+    Args:
+      A: (B, n, n) symmetric non-negative weighted adjacency.
+
+    Returns:
+      R: (B, n, n) effective resistance. R[..., u, v] is the resistance
+        between nodes u and v under the electric-network interpretation
+        of A. Diagonal R[..., u, u] = 0 by definition. Pairs in different
+        connected components have infinite resistance.
+
+    Notes:
+      Each component is scaled by its maximum weighted degree. Adding the
+      projector onto component constants makes the scaled Laplacian positive
+      definite; Cholesky inversion and projector subtraction give its
+      pseudoinverse without a spectral rank cutoff. Connectivity uses
+      Boolean reachability by repeated matrix squaring, with O(log n)
+      sequential rounds and O(B · n³ log n) dense work. Each round doubles
+      the path lengths represented, so there are no node or batch loops.
+
+    References:
+      Klein-Randić (1993), Eq. (10) for the L⁺ expression.
+      Doyle-Snell (1984), §1.
+    """
+    A = _checked_adjacency(A)
+    return _resistance_and_reachability(A)[0]
+
+
+def commute_time(A: torch.Tensor) -> torch.Tensor:
+    """Pairwise commute time `C(u, v) = vol(component) · R(u, v)`.
+
+    Commute time is the expected number of steps a random walk takes
+    to go from u to v and back. The Chandra-Raghavan-Ruzzo-Smolensky-
+    Tiwari (1996) identity expresses it as the total edge weight
+    `vol(A) = Σ_{ij} A_{ij}` times the effective resistance on a connected
+    graph. On disconnected graphs the volume is that of the component
+    containing u and v. Self-loops are dropped before computing this volume.
+
+    Args:
+      A: (B, n, n) symmetric non-negative weighted adjacency.
+
+    Returns:
+      C: (B, n, n) commute times. Cross-component pairs are infinite,
+        and the diagonal is zero, including isolated nodes.
+
+    References:
+      Chandra et al. (1996), Theorem 2.1.
+      Lovász (1993), §5.
+    """
+    A = _checked_adjacency(A)
+    resistance, connected = _resistance_and_reachability(A)
+    degree = A.sum(dim=-1)
+    # Row u of `connected` marks the component of u, so this matmul sums the
+    # degrees over that component, which is its volume.
+    volume = (connected.to(A.dtype) @ degree.unsqueeze(-1)).squeeze(-1)
+    # Cross-component entries of `resistance` are inf. An isolated node has
+    # volume 0, and 0 * inf is NaN, so those entries are zeroed before the
+    # multiply. The where below puts inf back on the cross-component pairs.
+    finite_resistance = torch.where(connected, resistance, 0.0)
+    return torch.where(
+        connected, volume.unsqueeze(-1) * finite_resistance, float("inf"),
+    )
+
+
+# ============================================================
+# Internal helpers
+# ============================================================
+
+
+def _checked_adjacency(A: torch.Tensor) -> torch.Tensor:
+    """Validate a dense adjacency and zero its diagonal.
+
+    Takes a dense `(..., n, n)` real floating-point tensor and returns it with
+    the diagonal zeroed. Raises ValueError if it is not square, not floating
+    point, or has a negative off-diagonal entry. Self-loops are dropped before
+    the sign check, so a negative diagonal entry is ignored rather than
+    rejected. Assumes A is symmetric. This function does not check that; the
+    Laplacian it feeds warns when it is not.
+    """
+    if A.ndim < 2 or A.shape[-1] != A.shape[-2]:
+        raise ValueError(f"A must be (..., n, n); got A.shape={tuple(A.shape)}")
+    if not A.is_floating_point():
+        raise ValueError("A must have a real floating-point dtype")
+    A = drop_self_loops(A)
+    if (A < 0).any():
+        raise ValueError("A must have nonnegative conductances")
+    return A
+
+
+def _resistance_and_reachability(
+    A: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Return resistance and connectivity for a validated, loop-free adjacency.
+
+    Takes the output of `_checked_adjacency`: a `(B, n, n)` symmetric,
+    non-negative adjacency with zero diagonal. Returns `(resistance,
+    connected)`, both `(B, n, n)`. `connected` is a Boolean mask of the pairs
+    in the same component, diagonal included. `resistance` is inf wherever
+    `connected` is False. Assumes symmetry; the Laplacian it builds warns
+    otherwise.
+    """
+    n = A.shape[-1]
+    # A node always reaches itself, so the identity goes into the pattern.
+    connected = (A > 0) | torch.eye(n, device=A.device, dtype=torch.bool)
+    # An empty batch or a zero-node graph has nothing to invert. A.clone() is
+    # already the right, possibly empty, shape for the result.
+    if n == 0 or A.numel() == 0:
+        return A.clone(), connected
+    # A simple path has at most n - 1 edges. Each squaring doubles the path
+    # length the mask covers, and all graphs in the batch square together, so
+    # bit_length(n - 1) rounds cover every pair.
+    for _ in range((n - 1).bit_length()):
+        paths = connected.to(A.dtype)
+        connected = connected | (paths @ paths > 0)
+    laplacian = _L.combinatorial(A)
+    degree = A.sum(dim=-1)
+    # Each node takes the largest degree in its own component. Entries outside
+    # the component are zeroed before the max, so they cannot win it.
+    component_scale = torch.where(connected, degree.unsqueeze(-2), 0.0).amax(-1)
+    # Every node in a component gets the same scale, so dividing rows by it
+    # keeps the matrix symmetric. An isolate has degree 0, and dividing its
+    # zero Laplacian row by 0 would give NaN, so its scale is swapped for 1.
+    component_scale = torch.where(
+        component_scale > 0, component_scale, torch.ones_like(component_scale),
+    ).unsqueeze(-1)
+    # Projector onto the constant vectors of each component, P = 1 1^T / |c|.
+    # Adding it turns the zero eigenvalue of each component into 1, which makes
+    # the scaled Laplacian positive definite.
+    projector = connected.to(A.dtype) / connected.sum(dim=-1, keepdim=True)
+    grounded = laplacian / component_scale + projector
+    # grounded^{-1} - P is the pseudoinverse of L / s. Dividing by s undoes the
+    # scaling, since (L / s)^+ = s L^+.
+    inverse = (
+        torch.cholesky_inverse(torch.linalg.cholesky(grounded)) - projector
+    ) / component_scale
+    # Expanding (e_u - e_v)^T L^+ (e_u - e_v) gives the two diagonal entries
+    # minus twice the off-diagonal one.
+    diagonal = inverse.diagonal(dim1=-2, dim2=-1)
+    resistance = diagonal.unsqueeze(-1) + diagonal.unsqueeze(-2) - 2.0 * inverse
+    # The inverse is block diagonal, so a cross-component entry is 0 and its
+    # resistance comes out finite. Those pairs have no path, so they get inf.
+    return torch.where(connected, resistance, float("inf")), connected

holonomy_lib/spectral/embedding.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Spectral embedding via Laplacian eigenmaps, batched-first, GPU-native.
+
+The Laplacian eigenmap (Belkin-Niyogi 2003) embeds a graph into R^k by
+taking the bottom-k eigenvectors of a graph Laplacian. Each row of the
+resulting (n, k) matrix is the k-dimensional coordinate of one node.
+
+This module provides a single primitive
+
+    laplacian_eigenmaps(A, k, laplacian_type)
+
+that returns the bottom-k eigenvalue/eigenvector pairs of the chosen
+Laplacian, with the eigenvectors sorted by eigenvalue ascending. We
+do **not** automatically drop the trivial null eigenvector; that
+choice depends on the use case (it should be dropped for connected
+unsigned graphs but kept for signed Laplacians, where the null
+eigenvector encodes the balance partition; Kunegis 2010). The caller
+decides.
+
+This routine uses dense `torch.linalg.eigh`, with O(n³) cost. For sparse
+operators, use `holonomy_lib.algebra.lanczos_eigsh` or `eigsh_sparse_sa`.
+
+References:
+  Belkin, M., Niyogi, P. (2003). Laplacian eigenmaps for dimensionality
+    reduction and data representation. Neural Computation 15(6):1373–1396.
+  von Luxburg, U. (2007). A tutorial on spectral clustering. Statistics
+    and Computing 17(4):395–416, discussion of which Laplacian to use.
+  Coifman, R. R., Lafon, S. (2006). Diffusion maps. Applied and
+    Computational Harmonic Analysis 21(1):5–30, related embedding.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import torch
+
+from holonomy_lib.spectral import laplacian as _L
+
+LaplacianType = Literal[
+    "combinatorial", "symmetric_normalized", "random_walk", "signed",
+]
+
+
+def laplacian_eigenmaps(
+    A: torch.Tensor,
+    k: int,
+    laplacian_type: LaplacianType = "symmetric_normalized",
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Bottom-k Laplacian eigenmap embedding of a (batched) graph.
+
+    Args:
+      A: (B, n, n) weighted adjacency. Symmetric for the supported
+        Laplacian variants (combinatorial, symmetric_normalized,
+        random_walk, signed).
+      k: number of eigenvectors to return. Must satisfy 1 ≤ k ≤ n.
+      laplacian_type: which Laplacian to diagonalize.
+        - "symmetric_normalized" (default). Belkin-Niyogi (2003) solve
+          the generalized problem L f = λ D f, which is the
+          "random_walk" option below; L_sym has the same eigenvalues.
+        - "combinatorial" (unnormalized)
+        - "random_walk" (non-symmetric; the returned eigenvectors are
+          the L_rw eigenvectors, obtained by D^{−1/2}-scaling the
+          L_sym eigenvectors so they diagonalize L_rw on the right;
+          the scaling is identity on isolated-node coordinates)
+        - "signed" (Kunegis 2010)
+
+    Returns:
+      eigenvalues: (B, k), sorted ascending.
+      eigenvectors: (B, n, k), column j is the eigenvector for
+        eigenvalues[..., j].
+
+    Notes:
+      The trivial null eigenvector (eigenvalue ≈ 0 for connected
+      unsigned graphs) is NOT automatically dropped. Drop it explicitly
+      with `eigvecs[..., 1:]` when you want the embedding to exclude
+      it. For signed Laplacians, do NOT drop it; it encodes the
+      balance partition (Kunegis 2010, Thm 3.4).
+
+    References:
+      Belkin-Niyogi (2003), §2, Laplacian eigenmap.
+      von Luxburg (2007), §5, practical considerations.
+    """
+    if A.ndim < 2 or A.shape[-1] != A.shape[-2]:
+        raise ValueError(
+            f"A must be (..., n, n); got A.shape={tuple(A.shape)}"
+        )
+    n = A.shape[-1]
+    if k <= 0 or k > n:
+        raise ValueError(f"k must satisfy 1 <= k <= n={n}, got k={k}")
+
+    if laplacian_type == "combinatorial":
+        L = _L.combinatorial(A)
+        eigvals, eigvecs = torch.linalg.eigh(L)
+    elif laplacian_type == "symmetric_normalized":
+        L = _L.symmetric_normalized(A)
+        eigvals, eigvecs = torch.linalg.eigh(L)
+    elif laplacian_type == "signed":
+        L = _L.signed(A)
+        eigvals, eigvecs = torch.linalg.eigh(L)
+    elif laplacian_type == "random_walk":
+        # L_rw is similar (in the linear-algebra sense) to L_sym via
+        # L_rw = D^{−1/2} L_sym D^{1/2}. So if u_i is the L_sym
+        # eigenvector for λ_i, then v_i = D^{−1/2} u_i is the L_rw
+        # right-eigenvector for the same λ_i. (Equivalently, v_i is the
+        # solution to the generalized eigenproblem L v = λ D v.)
+        # L_rw is not symmetric, so eigh cannot take it directly. Solving
+        # the symmetric L_sym and mapping its eigenvectors over keeps the
+        # real, sorted eigh output
+        L_sym = _L.symmetric_normalized(A)
+        eigvals, u = torch.linalg.eigh(L_sym)  # (B, n), (B, n, n)
+        d = _L.degree(A, signed=False)
+        # an isolated node has a diagonal entry of one in both L_rw and
+        # L_sym. Using degree 1 there makes the similarity transform the
+        # identity on that coordinate, so its eigenvector survives instead
+        # of being multiplied by a zero (pseudoinverse) degree factor
+        safe_degree = torch.where(d > 0, d, 1.0)
+        d_inv_sqrt = safe_degree.rsqrt()
+        eigvecs = u * d_inv_sqrt.unsqueeze(dim=-1)  # broadcast over columns
+    else:
+        raise ValueError(
+            f"laplacian_type must be one of "
+            f"'combinatorial', 'symmetric_normalized', 'random_walk', 'signed'; "
+            f"got {laplacian_type!r}"
+        )
+
+    # eigh already returns ascending order, so the bottom k are the first k.
+    # contiguous() so the caller gets owning tensors, not strided slices
+    return eigvals[..., :k].contiguous(), eigvecs[..., :, :k].contiguous()