Synoros researchgithub.com/synoros-io/holonomy_libRead the paper: Meaning on a Video Card
holonomy_lib
A GPU-native PyTorch math library for differential geometry, spectral graph theory, computational topology, and mechanistic interpretability.
Modules
13
Version
v0.6
Citations
every public function
License
BSD 3-Clause
From the paper
Meaning on a Video Card10³×
more precise ℍ⁵ / ℍ⁷ heat kernel
4.48×
silent error the dual-check caught
0
backward NaNs, no ε clamp
10⁶
points on a single consumer GPU
Interactive demos
Hyperbolic and mixed-curvature manifolds
Five manifold classes. The κ-stereographic model interpolates spherical, Euclidean, and hyperbolic geometry through a single curvature parameter, and κ is learnable: dynamic sign dispatch lets it cross zero during training, shown here. A pseudo-Riemannian Lorentzian manifold carries causal structure; product and per-point-κ manifolds give mixed-curvature embeddings.
With the κ-crossing dispatch, continuous per-point curvature, and an autograd-safe arcsinh reparameterization that keeps every manifold finite at its boundary inputs, the geometry stays exact under float64 and automatic differentiation.
Modules
| Module | Primitives | What it gives you | Citations |
|---|---|---|---|
| manifolds | FixedRankManifold, SPDManifold, LorentzManifold, KappaStereographicManifold, LorentzianManifold, ProductManifold, HeterogeneousKappaManifold | Riemannian geometry on low-rank matrices and SPD cones; the hyperboloid model of hyperbolic space; the κ-stereographic model interpolating spherical / Euclidean / hyperbolic with learnable κ that can cross 0 mid-training; pseudo-Riemannian Minkowski spacetime with causal structure; mixed-curvature products; per-point-κ heterogeneous geometry. | Vandereycken 2013; Pennec et al. 2006; Nickel-Kiela 2018; Bachmann-Bécigneul-Ganea 2020; MTW 1973; O'Neill 1983; Gu-Sala 2019; Guo et al. 2025 |
| algebra | truncated_svd, lanczos_eigsh | Halko-Martinsson-Tropp randomized SVD; Eckart-Young exact; Lanczos top-k with full reorthogonalization; shift-and-invert SA mode. | Halko-Martinsson-Tropp 2011; Paige 1972; Ericsson-Ruhe 1980 |
| tensor_calculus | hosvd, mode_product, mode_unfolding | Truncated higher-order SVD with Kolda-Bader n-mode product. | Kolda-Bader 2009 |
| spectral | combinatorial / symmetric_normalized / random_walk / signed Laplacians, magnetic Hermitian, heat_kernel_chebyshev, effective_resistance, commute_time, diffusion_map | Four Laplacians, directed-graph magnetic variant, Chebyshev heat kernel, effective resistance, commute time, diffusion maps. | Chung 1997; von Luxburg 2007; Kunegis 2010; Furutani 2020; Hammond-Vandergheynst-Gribonval 2011; Klein-Randić 1993; Coifman-Lafon 2006 |
| discrete_geometry | ollivier_ricci_curvature, discrete_ricci_flow, ricci_flow_with_surgery, forman_ricci_simple, forman_ricci_augmented | Sinkhorn-W₁ Ollivier on graphs, the Perelman-on-networks flow with surgery, and the cheap combinatorial Forman alternative. | Ollivier 2009; Cuturi 2013; Sia / Ni-Lin-Luo-Gao 2019; Sreejith et al. 2016; Samal et al. 2018 |
| info_geometry | bregman_divergence, kl_divergence_categorical, kl_divergence_gaussian | Bregman divergence for any convex generator plus closed-form KL for the standard exponential families. | Bregman 1967; Banerjee et al. 2005; Amari 2016 |
| optimization | RiemannianSGD | Steepest descent on FixedRank and SPD via the projection-plus-retraction API. | Absil-Mahony-Sepulchre 2008 |
| simplicial | DenseSimplicialComplex, SparseSimplicialComplex, vietoris_rips_* | Simplicial complex data structures, boundary operators, Vietoris-Rips construction. | Munkres 1984; Hausmann 1995; Bauer 2021 |
| topology | hodge_laplacian, betti_numbers, persistence_diagrams | Hodge Laplacians and Betti numbers on simplicial complexes plus batched persistent homology H₀ + H₁ + H₂ via union-find and Z/2 matrix reduction. | Eckmann 1944; Lim 2020; Edelsbrunner-Letscher-Zomorodian 2002; Cohen-Steiner-Edelsbrunner-Harer 2007 |
| sheaf | GraphSheaf, sheaf_coboundary, sheaf_laplacian, sheaf_dirichlet_energy | Cellular sheaves on graphs and their Laplacians. Reduces to the standard graph Laplacian under trivial stalks; the spectral foundation behind Neural Sheaf Diffusion. | Hansen-Ghrist 2019; Bodnar et al. 2022 |
| lie | so3.{exp, log, axis_angle, random_so3, compose}, real_spherical_harmonics | SO(3) primitives: Rodrigues, matrix log with calibrated near-π branch, Haar-uniform sampling, composition. Real spherical harmonics Y_lm for l ≤ 4. | Shoemake 1992; Edmonds 1957 |
| hyperbolic | manifold_aware_inner, frechet_mean, hyperbolic_laplacian_eigenmaps, hyperbolic_heat_kernel | Manifold-agnostic graph operations: Karcher intrinsic mean, RSGD Laplacian eigenmaps, tangent-at-origin inner product, and a dimension-dispatched H^n heat kernel (closed forms at n = 3, 5; corrected spectral-shift recursion for higher n). | Karcher 1977; Pennec 2006; Belkin-Niyogi 2003; Nickel-Kiela 2017; Davies-Mandouvalos 1988; Grigor'yan 2009 |
| provenance | @with_provenance, record(), ProvenanceRegistry | Content-addressable Merkle DAG of math primitives. Substitution, replay, SAELens emission for mech interp. | Synoros |
Benchmarks
CPU, single-thread, PyTorch 2.12, float64.
| Primitive | Size | Before | After | Speedup | Optimization |
|---|---|---|---|---|---|
| Ollivier-Ricci curvature | n = 16 | 34.0 ms | 18.0 ms | 1.9x | pair tiling, sync cadence |
| Ollivier-Ricci curvature | n = 32 | 273 ms | 133 ms | 2.1x | pair tiling, sync cadence |
| Ollivier-Ricci curvature | n = 64 | 22.6 s | 1.7 s | 13x | pair tiling, sync cadence |
| FixedRank retraction | 256² rank-16 | 7.4 ms | 1.3 ms | 5.8x | auto-randomized SVD |
| FixedRank retraction | 1024² rank-32 | 193 ms | 7.6 ms | 25x | auto-randomized SVD |
| Lanczos top-1 eigh | n = 1024 | 46.5 ms | 11.0 ms | 4.2x | vs dense eigvalsh |
| Lanczos shift-and-invert SA | n = 1024 | 80.9 ms | 18.9 ms | 4.3x | smallest eigenvalues |
| Sparse Laplacian | n = 1024 | 3.2 ms | 0.23 ms | 14x | vs dense L = D − A |
Vs alternatives
Existing libraries cover slices. None cover all four properties this library guarantees: breadth, GPU-native batched-first, audit-clean, cited.
| Feature | holonomy_lib | geoopt | geomstats | pymanopt | gudhi | ripser |
|---|---|---|---|---|---|---|
| Riemannian manifolds + optimizers | · | · | ||||
| Spectral graph theory (4+ Laplacians) | · | · | · | · | · | |
| Magnetic Laplacian (directed) | · | · | · | · | · | |
| Ollivier-Ricci + Forman-Ricci | · | · | · | · | · | |
| Discrete Ricci flow + surgery | · | · | · | · | · | |
| Tucker / HOSVD | · | · | · | · | · | |
| Chebyshev heat kernel + diffusion maps | · | · | · | · | · | |
| Simplicial complexes + Hodge Laplacians | · | · | · | · | ||
| Batched persistent homology | · | · | · | · | · | |
| GPU-native (PyTorch) | partial | · | · | · | ||
| Batched-first | partial | · | · | · | ||
| Content-addressable provenance | · | · | · | · | · | |
| Audit (no magic numbers) | · | · | · | · | · | |
| Information geometry | · | · | · | · | ||
| Differentiable hyperbolic heat kernel (all n) | · | · | · | · | · | |
| Per-point κ (heterogeneous curvature) | · | · | · | · | · | |
| Learnable κ that crosses 0 mid-training | partial | · | · | · | · |
Discipline
Audit: no magic numbers
Every numerical constant must fall into one of three categories. The audit tool fails on any uncataloged literal; it runs as a build gate.
| derived | Computed from inputs. 1 / N for normalization, 1 / sqrt(d) for Laplacian normalization. |
| invariant | Universal. 1e-9 numerical floor, 0.5, 2π, 1024 for KB↔MB. |
| tuned | Experimentally chosen. SINKHORN_TILE_DEFAULT = 256 with a documented scale of validity and re-tuning procedure. |
The same discipline runs end to end: every change clears four gates before it lands.
- pytest1,143 tests: unit, property, and cross-library comparison against geoopt, pymanopt, tensorly, scipy, and GraphRicciCurvature.
- audit --strictBuild gate. Fails on any uncataloged numerical literal before the commit lands.
- benchmarksDevice-agnostic timing harness; baseline and post-optimization numbers recorded each release.
- validationReference-free dual checks (operator residual + conserved quantity) and a scrutiny review pass before merge.
Mechanistic interpretability
Content-addressable provenance
Every public primitive is wrapped with @with_provenance. Inside a record() block, calls emit Merkle-DAG nodes whose hex identity is
hash(op_id || op_version || canonical(params) || input_hexes)
Same op, same inputs, same hex. Deterministic, content-addressable. Unlocks TransformerLens-style activation patching and SAELens-style dataset emission for mathematical primitives, not just neural network internals. Pluggable hash (blake3 if installed, else SHA-256).
Provenance agent API
- ·New holonomy_lib.provenance.agent module: every tool decorated with @agent_tool. to_anthropic_schema() and to_openai_schema() emit native LLM tool-use JSON.
- ·Inspection tools usable as LLM tools, MCP tools, or plain Python: tensor_slice (numpy-syntax indexing), tensor_per_batch_summary, tensor_eigenvalues, tensor_singular_values, tensor_norm, tensor_compare, op_docstring. Replaces v0.3 global-stats-only get_tensor_summary.
- ·replay_with(target_hex, recipe) substitution DSL: kinds zeros_like, from_hex, perturb (seeded Gaussian), scale, swap_batch, literal. Replaces v0.3 zero-fill-only MCP replay.
- ·mcp.py refactored to pure transport: iterates the agent inventory and pre-binds the registry. Same v0.3 nav tools by name for back-compat; new inspection and replay tools land alongside.
Install
pip install holonomy-lib
Small dependency surface: torch ≥ 2.0, numpy, scipy. Everything else is shipped natively. Python ≥ 3.12. ROCm and specific CUDA wheels: install torch first, then the library.
# Standard (CPU or default CUDA) pip install holonomy-lib # AMD ROCm 6.4 pip install --index-url https://download.pytorch.org/whl/rocm6.4 torch pip install holonomy-lib # Development git clone https://github.com/synoros-io/holonomy_lib cd holonomy_lib uv venv && uv pip install -e ".[dev]"
Quick start
Ricci flow community detection
import torch
from holonomy_lib.discrete_geometry import (
ricci_flow_with_surgery,
)
A = (torch.rand(1, 50, 50) > 0.7).double()
A = (A + A.mT) * 0.5
A_after = ricci_flow_with_surgery(
A,
n_steps=20,
surgery_period=5,
surgery_threshold=3.0,
dt=0.5,
alpha=0.0,
)
# Disconnected components in A_after
# correspond to detected communities.v0.6 (current): the paper
- +Closed forms for the ℍ⁵ and ℍ⁷ heat kernels, hand-derived from the operator chain: about three orders of magnitude more precise than the dimension recursion, and faster.
- +arcsinh reparameterization of hyperbolic distance: exact to machine precision at small separations where the textbook arccosh loses all bits, with no ε clamp.
- +Continuous, learnable per-point curvature: a sign dispatch carries κ across zero mid-training, beating a discrete curvature bank on a controlled identifiability task.
- +Reference-free dual-check gate (operator-equation residual plus a conserved quantity) that certifies primitives where no reference solution exists, and caught the dropped spectral-shift factor.
- +spectral_dimension as a representational-collapse diagnostic, and a content-addressable provenance layer for native activation tracing and ablation.
- +Demonstrated at 10⁶-point scale on a single consumer GPU (RTX 3060, RX 9060 XT), no datacenter accelerator.
v0.5: hyperbolic + mixed-curvature manifolds
- +Five manifold classes: LorentzManifold, KappaStereographicManifold (learnable, sign-crossing κ), LorentzianManifold, ProductManifold, HeterogeneousKappaManifold.
- +New hyperbolic module: manifold_aware_inner, frechet_mean, hyperbolic_laplacian_eigenmaps, hyperbolic_heat_kernel.
- +Heat-kernel correctness: found and fixed a missing spectral-shift factor in the dimension recursion; added a closed-form n = 5 kernel; re-enabled even n.
- +Autograd-finite at every manifold boundary input. Test count 707 → 1,143.
v0.4: provenance agent API
- ·New provenance.agent module with @agent_tool; emits Anthropic and OpenAI tool-use schemas.
- ·Inspection tools (tensor_slice, per-batch summary, eigenvalues, …) and the replay_with substitution DSL.
- ·mcp.py refactored to pure transport; v0.4.1 closed out end-to-end MCP transport bugs.
v0.3: provenance sweep
- ·Sketch hash (~15× on 8 MB tensors); on-disk tensor cache with reload on demand.
- ·to_mermaid(), to_graphviz(), diff_summary(); first MCP server and Jupyter cell magic.
Frontiers (next)
- ·Wigner-D matrices (real basis) to complete the SO(3) equivariance story.
- ·Optimal transport extensions: Gromov-Wasserstein, Sinkhorn divergences.
- ·GPU-resident custom CUDA kernel for the Z/2 persistent-homology reduction.
- ·Sparse-input shift-and-invert via iterative solver (CG / MINRES).
- ·Higher-dim cellular sheaves on simplicial complexes.
- ·Further manifolds: sphere, Stiefel, Grassmann; SE(3), SU(2), SL(n) Lie groups.