holonomy-lib 0.8.0__py3-none-any.whl

holonomy_explorer/topology.py

@@ -0,0 +1,118 @@
+"""One persistence computation supplies the complete interactive filtration."""
+
+from __future__ import annotations
+
+import torch
+
+from holonomy_lib.simplicial import pairwise_distances
+from holonomy_lib.topology import persistence_diagrams
+
+from .common import Context, Request
+from .datasets import cloud
+
+
+def reference_check(context: Context) -> Request:
+    """Check the square's sole H1 interval against [1, sqrt(2)).
+
+    References:
+        Edelsbrunner and Harer (2010), Computational Topology, VII.
+    """
+    square = context.tensor([[[0, 0], [1, 0], [1, 1], [0, 1]]])
+    diagrams, masks = context.call(persistence_diagrams, square, max_dim=1)
+    bars = diagrams[1][masks[1]]
+    # Zero-length intervals do not change persistence and may be retained by a
+    # future reduction backend. The check concerns positive-lifetime H1 only.
+    bars = bars[bars[:, 1] > bars[:, 0]]
+    expected = context.tensor([[1, 2**0.5]])
+    passed = bars.shape == expected.shape and torch.allclose(bars, expected)
+    return {"passed": bool(passed), "h1": bars, "expected_h1": expected}
+
+
+@torch.no_grad()
+def compute(request: Request) -> Request:
+    """Return bars and all radius events so slider movement needs no recompute.
+
+    Reduction in the dependency is sequential per batch member and uses CPU
+    bookkeeping even with GPU tensors. Counts below use [birth, death), including
+    all simplices with diameter <= ε at a tied filtration event.
+
+    References:
+        Edelsbrunner, Letscher and Zomorodian (2002), Topological persistence
+        and simplification. Discrete & Computational Geometry 28:511-533.
+    """
+    context = Context.from_request(request)
+    points = cloud(request, context)
+    distances = context.call(pairwise_distances, points[None])[0]
+    if not bool(torch.isfinite(distances).all()):
+        raise ValueError(
+            "pairwise distances overflowed; use smaller coordinates or float64"
+        )
+    diagrams, masks = context.call(persistence_diagrams, points[None], max_dim=1)
+    bars = [diagram[0, mask[0]] for diagram, mask in zip(diagrams, masks, strict=True)]
+    indices = torch.arange(len(points), device=context.device)
+    edges = torch.combinations(indices, r=2)
+    triangles = torch.combinations(indices, r=3)
+    edge_radii = distances[edges[:, 0], edges[:, 1]]
+    triangle_radii = torch.stack(
+        (
+            distances[triangles[:, 0], triangles[:, 1]],
+            distances[triangles[:, 0], triangles[:, 2]],
+            distances[triangles[:, 1], triangles[:, 2]],
+        ),
+        -1,
+    ).amax(-1)
+    events = torch.unique(torch.cat((context.tensor([0]), edge_radii)), sorted=True)
+    betti = torch.stack(
+        [
+            (
+                (bar[None, :, 0] <= events[:, None])
+                & (events[:, None] < bar[None, :, 1])
+            ).sum(-1)
+            for bar in bars
+        ],
+        -1,
+    )
+    finite_h1 = bars[1][torch.isfinite(bars[1][:, 1])]
+    lifetimes = finite_h1[:, 1] - finite_h1[:, 0]
+    finite_h0_deaths = bars[0][torch.isfinite(bars[0][:, 1]), 1]
+    if lifetimes.numel() and bool((lifetimes > 0).any()):
+        # Start inside the longest-lived finite loop, not at an empty complex.
+        longest = finite_h1[lifetimes.argmax()]
+        initial_epsilon = longest[0] + (longest[1] - longest[0]) / 2
+        initial_reason = "Midpoint of the most persistent finite H1 interval"
+    elif finite_h0_deaths.numel():
+        initial_epsilon = finite_h0_deaths.quantile(0.5)
+        initial_reason = "Median finite H0 death"
+    else:
+        initial_epsilon = context.tensor(0)
+        initial_reason = "No finite intervals; starting at zero"
+    initial_event = torch.searchsorted(events, initial_epsilon, right=True) - 1
+    reference = reference_check(context)
+    warnings = (
+        []
+        if reference["passed"]
+        else [
+            "This library checkout fails the square H1 reference: it emits extra "
+            "infinite bars. The bars and Betti counts shown here are provisional "
+            "library results, not corrected by the explorer."
+        ]
+    )
+    return context.finish(
+        points=points,
+        distances=distances,
+        bars=bars,
+        edges=edges,
+        edge_radii=edge_radii,
+        triangles=triangles,
+        triangle_radii=triangle_radii,
+        events=events,
+        betti=betti,
+        initial_epsilon=initial_epsilon,
+        initial_event=initial_event,
+        initial_reason=initial_reason,
+        edge_counts=(edge_radii[None] <= events[:, None]).sum(-1),
+        triangle_counts=(triangle_radii[None] <= events[:, None]).sum(-1),
+        reference_check=reference,
+        warnings=warnings,
+        parameters={key: value for key, value in request.items() if key != "points"},
+    )

holonomy_lib/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""PyTorch primitives for geometry, graph spectra, and tensor computations.
+
+Subpackages: algebra, convex, discrete_geometry, experimental, hyperbolic,
+info_geometry, lie, manifolds, optimization, sheaf, simplicial, spectral,
+tensor_calculus, and topology.
+"""

holonomy_lib/_graph_utils.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Internal graph-primitive utilities shared across modules.
+
+Conventions enforced here (see `CONVENTIONS.md`):
+
+  Self-loop policy
+  ----------------
+  Graph primitives in this library treat the input adjacency `A` as a
+  simple graph: the diagonal `A[i, i]` is **dropped at entry**, not
+  treated as an edge from node `i` to itself.
+
+  Rationale: most of the math (Forman-Ricci, Ollivier-Ricci, the
+  random-walk and symmetric-normalized Laplacians, magnetic Laplacian)
+  is defined on simple graphs in the source literature. Including a
+  self-loop changes `d_i = Σ_j A[i, j]` and every quantity built from
+  it (normalizers, walk distributions, phase factors). If each
+  primitive left the diagonal to the caller, the same input could give
+  different answers depending on whether that primitive happened to
+  cancel it, so the policy is applied once, at entry.
+
+  The combinatorial Laplacian `L = D − A` happens to be invariant to
+  self-loops (the diagonal subtraction zeroes them), but we still drop
+  them at entry so callers see consistent behavior across the library.
+"""
+
+from __future__ import annotations
+
+import torch
+
+
+def drop_self_loops(A: torch.Tensor) -> torch.Tensor:
+    """Return a tensor with the diagonal of `A` zeroed.
+
+    Args:
+      A: (..., n, n) adjacency-like tensor.
+
+    Returns:
+      Tensor with the same shape as `A`, identical to `A` everywhere
+      except `result[..., i, i] = 0` for all i.
+
+    Notes:
+      Uses `torch.where`, so the zeroing is one vectorized op over the
+      batch. The boolean eye mask leaves the value dtype of `A` unchanged.
+
+    References:
+      Chung (1997). Spectral Graph Theory. AMS, Chapter 1, simple graphs.
+    """
+    n = A.shape[-1]
+    eye = torch.eye(n, device=A.device, dtype=torch.bool).expand_as(A)
+    return torch.where(eye, torch.zeros_like(A), A)

holonomy_lib/_quadrature.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Cached Gauss-Legendre quadrature nodes (internal).
+
+`scipy.special.roots_legendre` recomputes the rule on every call (the
+Golub-Welsch tridiagonal eigensolve plus Newton refinement); it does NOT
+cache (only `scipy.integrate.fixed_quad`'s private wrapper does). The
+library's quadrature call sites (`manifolds.comparison.model_ball_volume`,
+`hyperbolic.heat_kernel`) sit inside batched paths where the same `n_quad`
+recurs on every invocation, so the recompute plus the numpy-to-torch
+round-trip is pure per-call overhead. This module keeps one float64 CPU
+master copy per `n_quad` and hands out dtype/device casts.
+
+Callers must treat the returned tensors as read-only: when the requested
+dtype/device match the master copy, `Tensor.to` returns the cached tensor
+itself, not a copy.
+
+References:
+  Golub, G. H., Welsch, J. H. (1969). Calculation of Gauss quadrature
+    rules. Mathematics of Computation 23(106):221-230. (The algorithm
+    underlying `scipy.special.roots_legendre`.)
+"""
+
+from __future__ import annotations
+
+import functools
+
+import torch
+from scipy.special import roots_legendre
+
+
+@functools.cache
+def _gauss_legendre_float64_cpu(n_quad: int) -> tuple[torch.Tensor, torch.Tensor]:
+    """Master copy: float64 CPU `(nodes, weights)` of the `n_quad`-point rule.
+
+    Input is `n_quad >= 1`. Output is two float64 CPU tensors of shape
+    `(n_quad,)`. The cache key is `n_quad` alone, so every caller gets the
+    same tensors and none of them may write into them.
+    """
+    nodes_np, weights_np = roots_legendre(n_quad)
+    return (
+        torch.as_tensor(nodes_np, dtype=torch.float64),
+        torch.as_tensor(weights_np, dtype=torch.float64),
+    )
+
+
+def gauss_legendre_nodes(
+    n_quad: int, *, dtype: torch.dtype, device: torch.device,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """`(nodes, weights)` of the `n_quad`-point Gauss-Legendre rule on (-1, 1).
+
+    The float64 CPU master is computed once per `n_quad` (`functools.cache`); the
+    per-call `.to(dtype, device)` is a cheap cast/copy (no-op when they match).
+
+    Args:
+      n_quad: node count of the rule.
+      dtype: floating dtype of the returned tensors.
+      device: device of the returned tensors.
+
+    Returns:
+      `(nodes, weights)`, each `(n_quad,)`, read-only by convention.
+
+    References:
+      Golub-Welsch (1969); see module docstring.
+    """
+    nodes, weights = _gauss_legendre_float64_cpu(n_quad)
+    # The cast comes last so the cache always holds float64 on CPU, whatever
+    # the caller asked for. When the request matches the master, `.to` hands
+    # back the cached tensor itself, which is why callers must not mutate it.
+    return (
+        nodes.to(dtype=dtype, device=device),
+        weights.to(dtype=dtype, device=device),
+    )

holonomy_lib/algebra/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""holonomy_lib.algebra: audit-clean wrappers around torch.linalg + extras.
+
+Currently implemented:
+  linear.truncated_svd:  batched truncated SVD (exact + randomized).
+  lanczos_eigsh:         largest/smallest algebraic eigenpairs of dense or
+                         sparse A; an explicit sigma (with which="SA")
+                         targets nearby modes.
+                         Full subspaces use torch.linalg.eigh.
+                         Sparse SA uses the backends in eigsh_sparse
+                         (bounded-pole SciPy eigsh / preconditioned
+                         SciPy LOBPCG / torch.lobpcg).
+  eigsh_sparse.eigsh_sparse_sa: the sparse smallest-k backend, callable
+                         directly for backend control.
+  solvers.cg:            conjugate gradient for SPD systems: batched
+                         dense, sparse, or callable-operator form.
+  solvers.lsqr:          iterative (damped) least squares via
+                         Golub-Kahan bidiagonalization.
+
+Planned:
+  Einstein notation helpers, group representations (cyclic, dihedral),
+  Lie algebras (su(n), so(n)), exterior algebra (wedge products).
+"""
+
+from holonomy_lib.algebra.eigsh_sparse import eigsh_sparse_sa
+from holonomy_lib.algebra.lanczos import lanczos_eigsh
+from holonomy_lib.algebra.linear import truncated_svd
+from holonomy_lib.algebra.solvers import cg, lsqr
+
+__all__ = ["cg", "eigsh_sparse_sa", "lanczos_eigsh", "lsqr", "truncated_svd"]

holonomy_lib/algebra/eigsh_sparse.py

@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: FSL-1.1-ALv2
+# Copyright 2026 Synoros
+
+"""Smallest-algebraic eigenpairs of sparse real symmetric matrices.
+
+By default, CPU inputs use SciPy shift-invert eigsh or preconditioned LOBPCG,
+and other devices use torch.lobpcg. The SciPy boundary computes in CPU float64
+and casts the result back. All backends are nondifferentiable. A Gershgorin
+lower bound places the default shift-invert pole below the spectrum, including
+for indefinite inputs. Full requests, and LOBPCG requests with n < 3k, use
+dense eigh.
+
+References:
+  Ericsson, T., Ruhe, A. (1980). The spectral transformation Lanczos
+    method for the numerical solution of large sparse generalized
+    symmetric eigenvalue problems. Math. Comp. 35(152):1251-1268.
+  Knyazev, A. V. (2001). Toward the optimal preconditioned eigensolver:
+    locally optimal block preconditioned conjugate gradient method.
+    SIAM J. Sci. Comput. 23(2):517-541.
+  Saad, Y. (2011). Numerical Methods for Large Eigenvalue Problems,
+    2nd ed. SIAM, §3.2 (spectral transformation).
+  Golub, G. H., Van Loan, C. F. (2013). Matrix Computations, 4th ed.
+    Johns Hopkins University Press, §7.2 (Gershgorin bounds).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Literal
+
+import torch
+
+# Existing throughput threshold from substrate's sheaf_scale.py (2026-06).
+# Its measurements concern Laplacian-like CPU sparsity, not every operator.
+SPARSE_SA_ITER_SOLVER_N: int = 8000
+
+# Existing cataloged convergence/preconditioner knobs from sheaf_scale.py.
+SPILU_EPS_FRAC: float = 1e-3
+SPILU_DROP_TOL: float = 1e-3
+SPILU_FILL_FACTOR: int = 10
+LOBPCG_TOL: float = 1e-6
+LOBPCG_MAXITER: int = 100
+
+# LOBPCG works in a Ritz subspace built from three blocks: the current
+# vectors, their residuals, and the previous search directions. That subspace
+# has up to 3k columns, so it needs n >= 3k. Smaller problems go to dense eigh.
+LOBPCG_SUBSPACE_BLOCKS: int = len(("iterate", "residual", "search_direction"))
+
+_SPARSE_LAYOUTS = (torch.sparse_coo, torch.sparse_csr, torch.sparse_csc)
+Solver = Literal["auto", "eigsh", "lobpcg", "torch_lobpcg"]
+
+
+def eigsh_sparse_sa(
+    A: torch.Tensor,
+    k: int,
+    sigma: float | None = None,
+    solver: Solver = "auto",
+    generator: torch.Generator | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Return the smallest algebraic eigenpairs of sparse symmetric ``A``.
+
+    Args:
+      A: real sparse ``(n, n)`` COO/CSR/CSC. Asymmetry emits a warning.
+        Grad-requiring inputs raise an error; detach explicitly to use
+        this nondifferentiable solver.
+      k: number of eigenpairs, ``1 <= k <= n``. Full requests, and LOBPCG
+        requests with n < 3k, use dense eigh because the iterative subspace
+        does not fit.
+      sigma: optional eigsh pole, strictly below the Gershgorin lower
+        bound. The default is that bound minus a dtype-scaled margin.
+        LOBPCG does not use a pole; explicit sigma is rejected there.
+      solver: ``auto`` selects torch.lobpcg off CPU, SciPy eigsh on CPU
+        up to ``SPARSE_SA_ITER_SOLVER_N``, then SciPy LOBPCG with shifted
+        incomplete-LU preconditioning. The three explicit names are
+        ``eigsh``, ``lobpcg`` and ``torch_lobpcg``.
+      generator: random-start generator compatible with ``A.device``.
+        Used by every iterative backend, including native LOBPCG.
+
+    Returns:
+      Ascending eigenvalues ``(k,)`` and orthonormal eigenvector columns
+      ``(n, k)``, on ``A.device`` with ``A.dtype``. SciPy computes in
+      float64 on CPU; its transfer is an explicit backend boundary.
+
+    Notes:
+      Native LOBPCG is unpreconditioned; clustered eigenvalues can need
+      more iterations than the fixed cataloged limit. SciPy's shifted
+      ILU preconditioner is intended for Laplacian-like sparse problems.
+
+    References:
+      Ericsson and Ruhe (1980); Knyazev (2001); Saad (2011), §3.2;
+      Golub and Van Loan (2013), §7.2. Full citations above.
+    """
+    if A.ndim != 2 or A.shape[0] != A.shape[1]:
+        raise ValueError(f"sparse A must be (n, n); got {A.shape}")
+    if A.layout not in _SPARSE_LAYOUTS:
+        raise ValueError("A must be a sparse tensor (COO/CSR/CSC)")
+    if not A.is_floating_point():
+        raise ValueError("A must have a real floating dtype")
+    n = A.shape[0]
+    if not isinstance(k, int) or isinstance(k, bool) or not 1 <= k <= n:
+        raise ValueError(f"k must satisfy 1 <= k <= n={n}; got k={k}")
+    if solver not in ("auto", "eigsh", "lobpcg", "torch_lobpcg"):
+        raise ValueError("solver must be auto, eigsh, lobpcg or torch_lobpcg")
+    if A.requires_grad:
+        raise ValueError(
+            "sparse eigensolvers do not support autograd; detach A explicitly"
+        )
+    if sigma is not None and not math.isfinite(sigma):
+        raise ValueError("sigma must be finite")
+    from holonomy_lib.algebra.lanczos import _warn_asymmetric
+
+    _warn_asymmetric(A)
+    # Coalesce first so duplicate entries are summed before the Gershgorin sums
+    # below read the values. A nonfinite entry would poison the bounds and the
+    # SciPy conversion, so it is rejected here.
+    coo = A.to_sparse_coo().coalesce()
+    if not torch.isfinite(coo.values()).all():
+        raise ValueError("A must have finite entries")
+    # Auto: non-CPU devices take torch.lobpcg. On CPU, eigsh's sparse LU is used
+    # up to SPARSE_SA_ITER_SOLVER_N, past which its fill-in grows too fast.
+    if solver == "auto":
+        if A.device.type != "cpu":
+            solver = "torch_lobpcg"
+        elif n <= SPARSE_SA_ITER_SOLVER_N:
+            solver = "eigsh"
+        else:
+            solver = "lobpcg"
+    if sigma is not None and solver != "eigsh":
+        raise ValueError("sigma is only used by the eigsh backend")
+
+    # Gershgorin discs: row i is centered on its diagonal entry, with radius
+    # equal to the sum of its off-diagonal magnitudes. Every eigenvalue lies in
+    # some disc, so the leftmost disc edge, `lower`, bounds the spectrum from
+    # below. `scale` is the largest |center| + radius and sizes the margins.
+    row, column = coo.indices()
+    entries = coo.values()
+    diagonal = entries.new_zeros(n).scatter_add(0, row, entries * (row == column))
+    radius = entries.new_zeros(n).scatter_add(0, row, entries.abs() * (row != column))
+    lower = (diagonal - radius).amin()
+    scale = (diagonal.abs() + radius).amax()
+    if sigma is not None and not bool(sigma < lower):
+        raise ValueError("sigma must be strictly below the Gershgorin lower bound")
+    # With scale zero the default pole lands exactly on the zero spectrum, so
+    # shift-invert would factor a singular matrix. Every vector is an
+    # eigenvector of the zero operator, so the first k identity columns work.
+    if not bool(scale):
+        return entries.new_zeros(k), torch.eye(n, k, dtype=A.dtype, device=A.device)
+    # Dense eigh when there is no room for an iterative subspace: k == n, or
+    # LOBPCG with n below its 3k requirement.
+    if k == n or (solver != "eigsh" and n < LOBPCG_SUBSPACE_BLOCKS * k):
+        values, vectors = torch.linalg.eigh(A.to_dense())
+        return values[:k], vectors[:, :k]
+
+    if solver == "torch_lobpcg":
+        initial = torch.randn(n, k, dtype=A.dtype, device=A.device, generator=generator)
+        values, vectors = torch.lobpcg(
+            coo,
+            k=k,
+            X=initial,
+            largest=False,
+            tol=LOBPCG_TOL,
+            niter=LOBPCG_MAXITER,
+        )
+        # torch.lobpcg does not promise an order, so sort to return ascending
+        # values like the other backends.
+        order = values.argsort()
+        return values[order], vectors[:, order]
+
+    import numpy as np
+    import scipy.sparse as sp
+    import scipy.sparse.linalg as spla
+
+    # SciPy works in host float64. The COO data is copied out here, and the
+    # results are cast back to A's device and dtype on return.
+    indices_np = coo.indices().cpu().numpy()
+    A_sp = sp.coo_matrix(
+        (entries.to(torch.float64).cpu().numpy(), (indices_np[0], indices_np[1])),
+        shape=(n, n),
+    ).tocsr()
+    if solver == "eigsh":
+        if sigma is None:
+            # The nextafter step keeps the pole strictly below the bound
+            # even if subtraction rounds back to the bound at this scale.
+            pole_tensor = lower - torch.finfo(A.dtype).eps ** 0.5 * scale
+            pole = float(
+                torch.nextafter(pole_tensor, torch.full_like(lower, -torch.inf))
+            )
+        else:
+            pole = sigma
+        # ARPACK's random start, drawn on A's device and moved to host float64.
+        initial_vector = (
+            torch.randn(
+                n,
+                device=A.device,
+                dtype=A.dtype,
+                generator=generator,
+            )
+            .to(torch.float64)
+            .cpu()
+            .numpy()
+        )
+        # Shift-invert with the pole below the spectrum. ARPACK's largest inverse
+        # eigenvalues are the eigenvalues of A nearest the pole. Every eigenvalue
+        # is above the pole, so those are the k smallest.
+        values_np, vectors_np = spla.eigsh(
+            A_sp,
+            k=k,
+            sigma=pole,
+            which="LM",
+            v0=initial_vector,
+        )
+    else:
+        # Shift below the Gershgorin bound. The matrix being factored, A - shift I,
+        # is then positive definite even when A is indefinite, and LOBPCG's
+        # preconditioner is its incomplete LU.
+        shift = float(lower - SPILU_EPS_FRAC * scale)
+        ilu = spla.spilu(
+            (A_sp - shift * sp.identity(n, format="csc")).tocsc(),
+            drop_tol=SPILU_DROP_TOL,
+            fill_factor=SPILU_FILL_FACTOR,
+        )
+        # The preconditioner applies the ILU solve, which approximates (A - shift I)^-1.
+        preconditioner = spla.LinearOperator((n, n), matvec=ilu.solve)
+        initial_block = (
+            torch.randn(
+                n,
+                k,
+                device=A.device,
+                dtype=A.dtype,
+                generator=generator,
+            )
+            .to(torch.float64)
+            .cpu()
+            .numpy()
+        )
+        values_np, vectors_np = spla.lobpcg(
+            A_sp,
+            initial_block,
+            M=preconditioner,
+            largest=False,
+            tol=LOBPCG_TOL,
+            maxiter=LOBPCG_MAXITER,
+        )
+    # The backends don't promise an order, so sort ascending before returning.
+    order_np = np.argsort(values_np)
+    return (
+        torch.from_numpy(values_np[order_np].copy()).to(device=A.device, dtype=A.dtype),
+        torch.from_numpy(vectors_np[:, order_np].copy()).to(
+            device=A.device, dtype=A.dtype
+        ),
+    )