Holonomy_lib, exact non Euclidean geometry primitives for PyTorch

Independent and Synoros researchers released holonomy_lib, a GPU-native PyTorch library providing exact non-Euclidean geometry primitives for differential geometry, spectral graph theory, discrete Ricci flow, and tensor decompositions. The library contains 12 modules with 1,179 tests, where every numerical constant is derived with a scale-of-validity and every operation is cited to its defining paper, enabling content-addressable provenance for mechanistic interpretability. The library consolidates mathematics that modern machine learning projects repeatedly reinvent, offering Riemannian optimization, simplicial topology, and batched persistent homology under a single audited framework.

A research-grade PyTorch math library: GPU-native, batched-first, audit-clean, with every primitive grounded in a citation. Differential geometry, spectral graph theory, discrete Ricci flow, tensor decompositions, Riemannian optimization, simplicial topology, batched persistent homology, and content-addressable provenance for mechanistic interpretability, all under one roof. Developed by independent and Synoros researchers for thesubstrateresearch. A consolidated PyTorch math library for research at the intersection of differential geometry , spectral graph theory , computational topology , and mechanistic interpretability : the mathematics that modern ML keeps reinventing project by project. Twelve modules, 1179 tests, every numerical constant derived or cataloged with a scale-of-validity, every primitive cited to the paper that defines it. The name holonomy comes from differential geometry: the transformation a vector accumulates when parallel-transported around a closed loop. It captures the library's character: every operation defined by the geometry it preserves, every result traceable back to its inputs through a content-addressable provenance DAG. | Module | Primitives | What it gives you | |---|---|---| manifolds | FixedRankManifold , SPDManifold , LorentzManifold , KappaStereographicManifold , LorentzianManifold , , ProductManifold , HeterogeneousKappaManifold comparison. | Riemannian geometry on low-rank matrices, SPD cones, the hyperboloid model of hyperbolic space at curvature k < 0 , the κ-stereographic model with parametric κ ∈ R interpolating spherical / Euclidean / hyperbolic, the pseudo-Riemannian 1, n-1 -signature Minkowski spacetime, mixed-curvature product manifolds, and per-point-κ heterogeneous geometry for substrate-style embeddings Vandereycken 2013; Pennec et al. 2006; Nickel-Kiela 2018; Bachmann-Bécigneul-Ganea 2020; MTW 1973; O'Neill 1983; Gu-Sala et al. 2019; Skopek et al. 2019; Di Giovanni et al. 2022; Guo et al. AAAI 2025 GraphMoRE , plus Bishop-Gromov model-space sphere-area / ball-volume comparison references at real non-integer dimension and signed curvature | algebra | truncated svd exact + randomized , lanczos eigsh | Halko-Martinsson-Tropp randomized SVD; Eckart-Young exact; Lanczos top-k eigensolver with full reorthogonalization Paige 1972 | tensor calculus | hosvd , mode product , mode unfolding | Truncated HOSVD with Kolda-Bader n-mode product | spectral | combinatorial / symmetric normalized / random walk / signed Laplacians, laplacian eigenmaps , magnetic. directed , heat kernel chebyshev , , effective resistance , commute time , diffusion map spectral dimension | Chung; von Luxburg; Kunegis signed ; Furutani 2020 magnetic Hermitian ; Hammond-Vandergheynst-Gribonval 2011 Chebyshev heat kernel ; Klein-Randić 1993 resistance ; Coifman-Lafon 2006 diffusion maps ; Rammal-Toulouse 1983 spectral dimension | discrete geometry | ollivier ricci curvature , discrete ricci flow , ricci flow with surgery , forman ricci simple , forman ricci augmented | Sinkhorn-W₁ Ollivier on graphs Ollivier 2009; Cuturi 2013; Sia/Ni-Lin-Luo-Gao 2019 , the Perelman-on-networks flow + surgery primitive, and the cheap combinatorial Forman alternative 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 FixedRankManifold / SPDManifold / LorentzManifold via the existing projection + retraction API Absil-Mahony-Sepulchre 2008, §4.1 | simplicial | , DenseSimplicialComplex , SparseSimplicialComplex vietoris rips | Simplicial complex data structures + boundary operators + Vietoris-Rips construction; foundation for Hodge + persistent homology Munkres 1984; Hausmann 1995; Bauer 2021 | topology | , hodge laplacian , betti numbers persistence diagrams | Hodge Laplacians + Betti numbers on simplicial complexes Eckmann 1944; Lim 2020 , plus batched persistent homology H₀+H₁+H₂ of Vietoris-Rips filtrations via union-find + Z/2 matrix reduction Edelsbrunner-Letscher-Zomorodian 2002; Cohen-Steiner-Edelsbrunner-Harer 2007 stability | sheaf | , GraphSheaf , HeterogeneousGraphSheaf , sheaf coboundary , sheaf laplacian sheaf dirichlet energy | Cellular sheaves on graphs and their Laplacians, uniform or per-node heterogeneous stalk dims Hansen-Ghrist 2019 ; reduces to the standard graph Laplacian under trivial stalks; the spectral foundation behind Neural Sheaf Diffusion Bodnar et al. 2022 | lie | , so3.{exp,log,axis angle,random so3,compose} real spherical harmonics | SO 3 primitives: Rodrigues / matrix log with empirically-calibrated near-π branch, Haar-uniform sampling Shoemake 1992 , composition; real spherical harmonics Y lm for l ≤ 4 Edmonds 1957 , the natural basis for SO 3 -equivariant functions on the sphere | provenance | @with provenance , record , ProvenanceRegistry | Content-addressable Merkle DAG of math primitives; substitution / replay / SAELens emission for mech interp | hyperbolic | , frechet mean , hyperbolic laplacian eigenmaps , manifold aware inner hyperbolic heat kernel | Manifold-aware graph operations: Karcher 1977 intrinsic mean, RSGD-based hyperbolic Laplacian eigenmaps Belkin-Niyogi + Nickel-Kiela 2017 , tangent-at-origin inner product Pennec 2006 , and the dimension-dispatched H^n heat kernel closed forms: Davies-Mandouvalos 1988 at n=3, hand-derived operator-chain at n=5 and n=7; Grigor'yan-Noguchi recursion above, seeded from n=7 | Existing libraries cover slices of what's here, but none cover all four properties this library guarantees: Breadth : Riemannian manifolds, spectral graph theory, tensor decompositions, Ricci-curvature, and content-addressable provenance, under one import root. GPU-native, batched-first : every operation takes a leading batch dim, runs on cuda / rocm / mps / cpu , verified for B ∈ {0, 1, 1} . Audit-clean : every numerical constant is derived, a universal invariant, or experimentally tuned with documented scale-of-validity. Enforced by python -m holonomy lib.audit src/ --strict . Cited : every public function has a References: section pointing to the paper that defines its math. No "trust me" implementations. | this lib | geoopt | geomstats | pymanopt | gudhi | ripser | | |---|---|---|---|---|---|---| | Riemannian manifolds + optimizers | ✓ | ✓ | ✓ | ✓ | – | – | | Spectral graph theory 4+ Laplacians | ✓ | – | – | – | – | – | | Magnetic Laplacian directed graphs | ✓ | – | – | – | – | – | | Ollivier-Ricci + Forman-Ricci curvature | ✓ | – | – | – | – | – | | Discrete Ricci flow + surgery | ✓ | – | – | – | – | – | | Tucker / HOSVD | ✓ | – | – | – | – | – | | Chebyshev heat kernel + diffusion maps | ✓ | – | – | – | – | – | | Simplicial complexes + Hodge Laplacians | ✓ | – | – | – | ✓ | – | | Batched persistent homology H₀+H₁+H₂ | ✓ | – | – | – | – | – | | GPU-native PyTorch | ✓ | ✓ | partial | – | – | – | | Batched-first | ✓ | ✓ | partial | – | – | – | | Content-addressable provenance | ✓ | – | – | – | – | – | | Audit / no-magic-numbers | ✓ | – | – | – | – | – | | Information geometry Bregman + KL | ✓ | – | ✓ | – | – | – | Differentiable hyperbolic heat kernel all n | ✓ | – | – | – | – | – | | Pseudo-Riemannian Lorentzian manifold | ✓ | – | – | – | – | – | | Per-point κ heterogeneous curvature | ✓ | – | – | – | – | – | | Mixed-curvature product manifold | ✓ | – | – | – | – | – | | Learnable κ that can cross 0 mid-training | ✓ | – | – | – | – | – | The library has a small dependency surface: torch = 2.0 , numpy , scipy . Everything else, Riemannian optimizers, simplicial complexes, Hodge Laplacians, persistent homology, is shipped natively. You do not need to install pymanopt , geoopt , gudhi , ripser , or similar to use the corresponding primitives. pip install holonomy-lib This pulls torch's default wheel CPU or CUDA 12, depending on platform automatically. Python ≥ 3.12. Install your preferred torch wheel first , then the library. pip / uv will respect the already-installed torch: AMD ROCm 6.4: pip install --index-url https://download.pytorch.org/whl/rocm6.4 torch pip install holonomy-lib CUDA 12.1 specifically: pip install --index-url https://download.pytorch.org/whl/cu121 torch pip install holonomy-lib CPU only: pip install --index-url https://download.pytorch.org/whl/cpu torch pip install holonomy-lib git clone https://github.com/Synoros-io/holonomy lib cd holonomy lib uv venv uv pip install -e ". dev " holonomy-lib provenance-extras : blake3 faster hash , networkx DAG export , pandas DataFrame export . Used only inside specific provenance helpers; the library degrades gracefully without them. holonomy-lib comparison : pymanopt, geoopt, geomstats, tensorly, gudhi, ripser, GraphRicciCurvature, networkx, autograd. Required ONLY for running the cross-comparison test suite locally; the library itself never imports these. holonomy-lib dev : pytest, ruff, mypy. holonomy-lib all : provenance-extras + dev the typical contributor install . python import torch from holonomy lib.manifolds import SPDManifold from holonomy lib.optimization import RiemannianSGD from holonomy lib.spectral import laplacian, laplacian eigenmaps from holonomy lib.discrete geometry import ricci flow with surgery from holonomy lib.topology import persistence diagrams from holonomy lib import provenance 1. Riemannian geometry on SPD covariance matrices mfd = SPDManifold n=8, dtype=torch.float64 S = mfd.random point batch size=4 4, 8, 8 SPD T = mfd.random point batch size=4 d = mfd.distance S, T affine-invariant geodesic V = mfd.log S, T Lie-algebra-style log T recon = mfd.exp S, V exp S log S T ≈ T 2. Riemannian gradient descent ON the SPD manifold opt = RiemannianSGD mfd, lr=0.5 point = S.clone for in range 50 : ambient grad = -mfd.log point, T gradient of 1/2 d point, T ^2 point = opt.step point, ambient grad point now sits on the SPD manifold, close to T. 3. Graph spectral embedding A = torch.rand 1, 50, 50 0.7 .double A = A + A.mT 0.5 symmetrize vals, vecs = laplacian eigenmaps A, k=4, laplacian type="symmetric normalized" 4. Perelman-on-networks: community detection via Ricci flow + surgery 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. 5. Batched persistent homology on point clouds points = torch.randn 8, 30, 2, dtype=torch.float64 8 point clouds of 30 pts diagrams, masks = persistence diagrams points, max dim=2, max radius=2.5, diagrams 0 : 8, max h0, 2 birth/death pairs for H 0 components diagrams 1 : 8, max h1, 2 for H 1 loops diagrams 2 : 8, max h2, 2 for H 2 voids masks k tells you which pair-slots are valid per batch element. 6. Mech-interp-style provenance: every primitive emits a Merkle DAG node with provenance.record cache tensors=True as reg: L = laplacian.combinatorial A vals, vecs = laplacian eigenmaps A, k=4 Look up any operation by content-addressable hex for node in reg: print f"{node.hex} {node.op id}" See CONTENTS.md for the complete inventory of primitives, signatures, and citations. Benchmarks: notes/benchmark baseline.md before optimization , notes/benchmark optimized.md post-Phase-3 fixes , and notes/benchmark 2026-05-26 roadmap sweep.md v0.1 roadmap items . All times CPU, single-thread, PyTorch 2.12, float64. The signature primitive, Ollivier-Ricci curvature via batched log-domain Sinkhorn over all-pairs shortest-path costs, got two optimizations: Pair tiling : the Sinkhorn dual update used to materialize a B, n², n, n intermediate 128 MB per iter at n=64 . Tiled implementation processes pairs in chunks of SINKHORN TILE DEFAULT = 256 , capping the inner broadcast at ~16 MB. Sync cadence : the .item convergence check used to fire every iter, forcing a GPU→CPU sync. Now checks every 8 iters; same asymptotic work, 8× fewer host syncs. | graph size n | before | after | speedup | |---|---|---|---| | 16 | 34.0 ms | 18.0 ms | 1.9× | | 32 | 273 ms | 133 ms | 2.1× | 64 | 22.6 s | 1.7 s | 13× | FixedRankManifold.retraction used to do a full SVD then slice top-r. At low r/min m, n ratios the common case for the fixed-rank manifold , it now auto-switches to Halko-Martinsson-Tropp randomized SVD with documented oversampling. | m × n × r | before full SVD | after auto | speedup | |---|---|---|---| | 64 × 64 × 8 | 0.31 ms | 0.31 ms | 1.0× parity | | 256 × 256 × 16 | 7.4 ms | 1.3 ms | 5.8× | 1024 × 1024 × 32 | 193 ms | 7.6 ms | 25× | The library's algebra.lanczos eigsh with full reorthogonalization beats torch.linalg.eigvalsh once the matrix is big enough that computing the full spectrum becomes wasteful. Single-batch top-1 eigenvalue at CPU, float64: | n | dense eigvalsh | lanczos eigsh n iter=30 | speedup | |---|---|---|---| | 128 | 0.44 ms | 2.66 ms | 0.2× Lanczos overhead dominates | | 512 | 7.62 ms | 4.84 ms | 1.6× | 1024 | 46.5 ms | 11.0 ms | 4.2× | The same lanczos eigsh accepts sparse-CSC inputs via the dispatch added in Phase 3 , so it's the natural top-k path on the sparse-Hodge Laplacians produced by the topology module. lanczos eigsh A, k, which="SA", sigma=σ runs Lanczos on A − σI ^{-1} so the dominant Ritz values converge to the eigenvalues of A closest to σ Ericsson-Ruhe 1980 . LU-factor is done once outside the iteration; each step is a lu solve . Where the factorization cost is amortized over enough iterations, it beats both LA Lanczos which has to do many iterations to converge on the small end of the spectrum and dense eigvalsh which always pays O n³ : | n | dense eigvalsh | lanczos eigsh LA, n iter=60 | lanczos eigsh SA, n iter=40 | |---|---|---|---| | 64 | 0.23 ms | 2.83 ms | 2.56 ms | | 256 | 3.34 ms | 4.89 ms | 4.77 ms | 1024 | 80.9 ms | 24.5 ms | 18.9 ms | SA mode raises RuntimeError "shift-invert breakdown" if σ coincides with an eigenvalue of A — for graph Laplacians which have 0 in spectrum use a small negative shift. All four Laplacian variants combinatorial, symmetric-normalized, random-walk, signed accept sparse-COO/CSR/CSC adjacency and return a sparse-COO Laplacian on the same device. Combined with the sparse lanczos eigsh path, you get end-to-end sparse spectral chains without materializing the dense n, n . The crossover is at very small n because sparse construction time stays nearly flat while dense scales O n² : | n | density | dense L = D − A | sparse L | |---|---|---|---| | 256 | 0.05 | 0.25 ms | 0.21 ms | | 1024 | 0.01 | 3.2 ms | 0.23 ms 14× | | 4096 | 0.003 | n/a 16 GB | 0.30 ms | topology.persistence diagrams computes H₀ + H₁ + H₂ for a batch of point clouds in parallel. H₀ runs via union-find on sorted filtration edges no boundary-matrix reduction needed . H₁ and H₂ use Z/2 left-to-right reduction Edelsbrunner-Letscher-Zomorodian 2002 on sparse-CSC boundary matrices, batching across point clouds. Closed-form verification: a noisy 30-point unit circle reliably recovers one persistent H₁ bar the loop with persistence 0.2 in the default max radius range; the bottleneck stability theorem Cohen-Steiner-Edelsbrunner-Harer 2007 is verified under ε-perturbation in the test suite. The reduction backend="torch" path runs end-to-end on the filtration's device CPU or GPU — but is not yet a custom CUDA kernel , just a torch-tensor port of the same sequential algorithm. For small inputs CPython sets are faster 43 ms vs 903 ms on an 80-point circle ; the torch path is a foundation for the v0.2 GPU kernel rather than an immediate win. The default backend stays "python" . Every numerical constant must be in one of three categories: | Category | Example | |---|---| ✅ Derived from inputs | 1 / N for normalization; 1 / sqrt d for Laplacian normalization | ⚖️ Universal invariant | 1e-9 numerical floor; 0.5 halving; 2π ; 1024 KB↔MB | 🔬 Experimentally tuned | SINKHORN TILE DEFAULT = 256 , cataloged with scale-of-validity | Each constant in category 🔬 has a row in notes/magic numbers.md /Synoros-io/holonomy lib/blob/master/notes/magic numbers.md with the procedure used to pick it, the regime where it's valid, and what to re-derive when scale changes. The audit tool python -m holonomy lib.audit src/ --strict fails on any uncataloged literal; run it before every commit.Every public primitive is decorated with @with provenance . Inside a provenance.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 . This unlocks TransformerLens-style activation patching and SAELens- style dataset emission for the mathematical primitives, not just neural network internals: with provenance.record cache tensors=True as reg: out = pipeline A Find a specific operation lap node = reg.where op id="holonomy lib.spectral.laplacian.combinatorial" 0 Ablation: substitute zeros and replay only the downstream computation new = reg.replay {lap node.hex: torch.zeros like reg.get tensor lap node.hex } new contains the re-executed outputs of every node downstream of the substitution. Emit a SAELens-style dataset for training feature extractors for tensor, metadata in reg.to sae dataset op id="holonomy lib.algebra.linear.truncated svd" : yield tensor, metadata Pluggable hash function blake3 if installed, else SHA-256 . Persist the DAG with reg.save path / ProvenanceRegistry.load path . Performance modes v0.3 : record hash mode="sketch" swaps the byte-level content hash for an O 1 -bytes sketch shape + dtype + 64 strided samples + sum + std . About 15× faster than full mode on 8 MB tensors; crossover at ~n=256. record cache to disk=path mirrors the output cache to torch.save'd files, so memory eviction from max cache size doesn't lose tensors: get tensor reloads on demand. Both default off. Inspection v0.3 : reg.to mermaid , reg.to graphviz for visualization; reg.diff summary other for "did my refactor preserve semantics" comparisons; reg.to llm context for a compact text summary suitable for an agent prompt. Agent access v0.3, optional extras : pip install 'holonomy-lib mcp ' adds an MCP server python -m holonomy lib.provenance.mcp that exposes the registry as agent tools for Claude, GPT, or any MCP client. pip install 'holonomy-lib jupyter ' adds a %%record provenance cell magic that records and renders the DAG inline. Full test suite uv run pytest Just one module uv run pytest tests/manifolds Run the audit build gate uv run python -m holonomy lib.audit src/ --strict Run benchmarks excluded from the test suite; runs on demand uv run python -m tests.benchmarks.run --out notes/benchmark latest.md Run on a GPU machine; parity tests light up automatically uv run pytest tests/test device parity.py Comparison tests run against established libraries when installed: pymanopt for FixedRankManifold, geoopt for SPDManifold, tensorly for HOSVD, scipy.sparse.csgraph for Laplacians, GraphRicciCurvature + networkx for Ollivier-Ricci. The tests skip silently if a comparison library isn't installed. holonomy lib/ ├── src/holonomy lib/ the library │ ├── manifolds/ FixedRank, SPD, Lorentz, κ-stereographic, Lorentzian, Product, heterogeneous-κ │ ├── hyperbolic/ manifold-aware graph ops: Fréchet mean, eigenmaps, heat kernel │ ├── algebra/ truncated svd, lanczos eigsh LA + shift-invert SA │ ├── tensor calculus/ hosvd, mode product, mode unfolding │ ├── spectral/ 4 Laplacians incl. magnetic + sign-magnetic , eigenmaps, heat kernel, resistance, diffusion maps │ ├── discrete geometry/ Ollivier-Ricci, discrete Ricci flow, surgery, Forman-Ricci │ ├── info geometry/ Bregman + KL divergences, Fisher metric, natural gradient │ ├── optimization/ RiemannianSGD on FixedRank / SPD │ ├── simplicial/ Dense + Sparse complexes, Vietoris-Rips │ ├── topology/ Hodge Laplacians, Betti, persistence diagrams H₀+H₁+H₂ │ ├── sheaf/ cellular sheaves on graphs, sheaf Laplacians │ ├── lie/ SO 3 primitives, real spherical harmonics l ≤ 4 │ ├── provenance/ content-addressable hex protocol │ └── audit.py audit gate: no magic numbers ├── tests/ 1179 tests across all modules │ └── benchmarks/ device-agnostic timing harness ├── notes/ │ ├── magic numbers.md cataloged constants with scale-of-validity │ ├── scrutiny.md findings + fixes from review passes │ ├── benchmark baseline.md before optimization │ └── benchmark optimized.md after ├── CHANGELOG.md release history └── CONTENTS.md primitive inventory and quick reference See CHANGELOG.md /Synoros-io/holonomy lib/blob/master/CHANGELOG.md for the full release history. v0.5.2 current : measurement + structure primitives. manifolds.comparison — Bishop-Gromov model-space sphere area / ball volume at real non-integer dimension and signed curvature. spectral.spectral dimension — spectral dimension d s from a Laplacian spectrum non-integer / fractal dimensions supported . sheaf.HeterogeneousGraphSheaf — cellular sheaf with per-node heterogeneous stalk dimensions; reduces to GraphSheaf under uniform dims.- Closed-form H^7 heat kernel, one operator-chain step beyond H^5 ; the odd-n heat-kernel recursion now seeds from it. v0.5.0 : hyperbolic / pseudo-Riemannian / mixed-curvature manifold pass. - Five new manifold classes: LorentzManifold hyperboloid model of H^n k , KappaStereographicManifold parametric κ interpolating spherical / Euclidean / hyperbolic, with learnable κ that can cross 0 mid-training via dynamic sign dispatch , LorentzianManifold pseudo-Riemannian 1, n-1 Minkowski spacetime with causal structure + flat-background curvature tensors , ProductManifold mixed-curvature direct product , and HeterogeneousKappaManifold per-point κ with a configurable pair-κ combiner . - New holonomy lib.hyperbolic module of manifold-agnostic graph operations: manifold aware inner , frechet mean Karcher iteration , hyperbolic laplacian eigenmaps RSGD embedding , and hyperbolic heat kernel dimension-dispatched H^n heat kernel . - Correctness: found and fixed a missing spectral-shift factor in the heat-kernel dimension recursion that appears in some references; added a closed-form n=5 kernel ~3 orders of magnitude tighter PDE residual ; even-n now works via the corrected recursion seeded from the n=2 integral form; autograd-finite gradients at every boundary input, established across all new manifolds. - Test count 707 → 1143; audit clean. v0.4.1 : end-to-end MCP transport fixes. mcp.py eagerly imports all op-defining submodules at server startup so OP REGISTRY is populated before replay with runs loaded registries reference ops the server process otherwise never touches . bind registry now inspects each tool's signature and only pre-binds the registry argument when the function actually declares one op docstring queries global state and doesn't .- List-returning tools wrap their return in {"results": ... } on the MCP transport so FastMCP serializes a single JSON content item instead of one per element. Python callers still see the underlying list via the unwrapped function — normalization is transport-only. v0.4.0 : provenance agent-API redesign. - New holonomy lib.provenance.agent module holds the canonical agent tool inventory. Each tool is a Python function decorated with @agent tool ; to anthropic schema / to openai schema emit native LLM tool-use JSON. - Inspection tools each callable as a native LLM tool, an MCP tool, or directly from Python : tensor slice numpy-syntax indexing , tensor per batch summary , tensor eigenvalues , tensor singular values , tensor norm , tensor compare , op docstring . Replaces v0.3.0's global-stats-only get tensor summary , which couldn't see per-batch anomalies. replay with target hex, recipe substitution DSL: kinds are zeros like , from hex , perturb Gaussian noise with required seed , scale , swap batch , literal . Replaces v0.3.0's zero-fill-only MCP replay . mcp.py refactored to pure transport: iterates the agent inventory and pre-binds the registry argument. Same v0.3 nav tools by name back-compat ; the new inspection + replay with tools land alongside. v0.3.0 : provenance module sweep. - Performance: opt-in sketch hashing 15× faster on 8 MB tensors via shape + dtype + 64 strided samples + sum + std and on-disk tensor cache memory eviction retains the disk copy; get tensor reloads on demand . - Robustness: replay now works for class-method calls and tuple-of-tensor inputs FixedRankPoint = U, S, Vt . Op-version drift detector on load emits ProvenanceVersionWarning with optional strict=True escalation. - Visualization: to mermaid , to graphviz , diff summary other with Cache hits / Drift / Only-in-self / Only-in-other categories, ancestors with tensors hex convenience. - Agent access: to llm context text summary; MCP server pip install 'holonomy-lib mcp ' ; Jupyter %record provenance cell magic pip install 'holonomy-lib jupyter ' . v0.2.0 : six new modules and several extensions since the v0.1.0 seed. - New modules: optimization RiemannianSGD , simplicial Dense / Sparse complexes + Vietoris-Rips , topology Hodge Laplacians + Betti + batched persistent homology H₀+H₁+H₂ , info geometry Bregman + KL + Fisher metric + natural gradient , sheaf cellular sheaves on graphs + sheaf Laplacians , lie SO 3 primitives + real spherical harmonics for l ≤ 4 . - Spectral additions: Forman-Ricci curvature, magnetic Laplacian, sign-magnetic Laplacian, Chebyshev heat kernel, effective resistance, commute time, diffusion maps, and sparse-COO/CSR/CSC paths for all four Laplacian variants. - Algebra additions: lanczos eigsh with LA largest algebraic and shift-and-invert SA smallest algebraic modes. - Class-method provenance for FixedRankManifold / SPDManifold ; device-agnostic torch reduction backend for persistent homology foundation for a future custom CUDA kernel . v0.1.0 : initial public release. manifolds , algebra , tensor calculus , spectral 4 Laplacians + eigenmaps , discrete geometry Ollivier-Ricci + flow + surgery , provenance . Frontiers v0.6+ : Wigner-D matrices real basis to complete the SO 3 equivariance story so spherical-harmonic features mix correctly under rotation; optimal transport extensions Gromov-Wasserstein for metric-measure-space comparison, Sinkhorn divergences for de-biased OT ; GPU-resident custom CUDA kernel for the Z/2 PH reduction current torch path is sequential with a per-column CPU sync ; 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 group primitives. Contributions welcome via PR. If this library helps your research, please cite it: @software{holonomy lib, author = {John Vaught}, title = {holonomy\ lib: GPU-native research math for differential geometry, spectral graph theory, and mechanistic interpretability}, year = {2026}, url = {https://github.com/Synoros-io/holonomy lib}, } The library implements algorithms from many sources; please also cite the original paper for the specific primitive you use each public function lists its references in its docstring . See CONVENTIONS.md /Synoros-io/holonomy lib/blob/master/CONVENTIONS.md for the full coding standards batched-first API shape, self-loop policy, numerical conventions, performance patterns, magic-numbers catalog, citation requirements, provenance, testing . Contributions welcome. Hard constraints binding for any code in this repo : Citations are non-optional. Every public function has a References: section pointing to the paper for its math. Every numerical constant has a derivation or a catalog entry in notes/magic numbers.md . The audit tool enforces this. Tests before merge : unit tests for correctness, property tests for invariants, comparison tests against established libraries where one exists. GPU-first, batched-first : operations take a leading batch dim, work on torch.Tensor on cuda / rocm / cpu . Verify shapes for B ∈ {0, 1, 1} . Open an issue first for non-trivial additions so we can align on approach. holonomy lib is free software under the GNU Affero General Public License v3.0 or later AGPL-3.0-or-later . See LICENSE /Synoros-io/holonomy lib/blob/master/LICENSE . Note the AGPL's network clause §13 : anyone who runs a modified version to provide a network service must make their modified source available to that service's users. Copyright © 2026 Synoros. Commercial licensing. The AGPL is not the only option. The copyright holder offers holonomy lib under separate commercial terms for uses the AGPL does not permit — for example, embedding it in a proprietary product or network service without the AGPL's source-disclosure obligations. For a commercial license, contact contact@synoros.io mailto:contact@synoros.io .