Research

holonomy_lib

holonomy_lib is a GPU-native, batched-first PyTorch library of geometric, spectral, and topological primitives: Riemannian manifolds, spectral graph theory, discrete Ricci curvature and flow, tensor decompositions, simplicial topology and batched persistent homology, cellular sheaves, and content-addressable provenance for mechanistic interpretability. Every public function carries a citation to the paper that defines its math, and every numerical constant is derived, a universal invariant, or cataloged with a documented scale of validity. It is developed by independent and Synoros researchers for the substrate research program.

Version	v0.7.0
Modules	14
Tests	1220 passing
License	AGPL-3.0-or-later, with commercial dual licensing (contact@synoros.io)

github.com/Synoros-io/holonomy_lib · read the paper: Meaning on a Video Card

Modules

Module	What it gives you
`manifolds`	Riemannian geometry on low-rank matrices and SPD cones, the hyperboloid and κ-stereographic models of hyperbolic space, pseudo-Riemannian Minkowski spacetime, mixed-curvature products, and per-point-κ heterogeneous geometry.
`algebra`	Randomized and exact truncated SVD, Lanczos top-k and shift-and-invert eigensolvers (dense and sparse), conjugate gradient, and LSQR.
`convex`	Problem-level convex optimization; ridge/Tikhonov least squares dispatching to Cholesky, CG, or LSQR depending on problem shape.
`tensor_calculus`	Truncated HOSVD with Kolda-Bader n-mode product.
`spectral`	Four graph Laplacians including magnetic (directed) and signed variants, Chebyshev heat kernel, effective resistance, commute time, diffusion maps, spectral dimension.
`discrete_geometry`	Sinkhorn-based Ollivier-Ricci curvature, discrete Ricci flow with surgery (community detection), and the cheaper Forman-Ricci alternative.
`info_geometry`	Bregman divergence for any convex generator plus closed-form KL divergence for the standard exponential families.
`optimization`	Riemannian SGD on fixed-rank, SPD, and Lorentz manifolds via projection and retraction.
`simplicial`	Dense and sparse simplicial complex data structures, boundary operators, Vietoris-Rips construction.
`topology`	Hodge Laplacians and Betti numbers, plus batched persistent homology (H₀+H₁+H₂) of Vietoris-Rips filtrations.
`sheaf`	Cellular sheaves on graphs, uniform or per-node stalk dimensions, dense and sparse Laplacians, sparse bottom-k spectral read.
`lie`	SO(3) primitives (Rodrigues exp/log, Haar-uniform sampling, composition) and real spherical harmonics up to l = 4.
`provenance`	Content-addressable Merkle DAG of math primitives: substitution, replay, and SAELens-style dataset emission for mech interp.
`hyperbolic`	Manifold-aware graph operations: Fréchet mean, RSGD-based hyperbolic Laplacian eigenmaps, tangent-at-origin inner product, dimension-dispatched H^n heat kernel.

New in 0.7.0

v0.7.0 adds a new convex package seeded with regularized_lstsq (Tikhonov/ridge least squares with method-auto dispatch across Cholesky, CG, and LSQR), a sparse-COO sheaf spectral pipeline (sheaf_coboundary_sparse, sheaf_laplacian_sparse, sheaf_bottom_spectrum) for sheaves past the dense byte cap, and a sparse shift-and-invert Lanczos backend (eigsh_sparse_sa) that dispatches to SciPy shift-invert, SciPy LOBPCG with ILU preconditioning, or torch.lobpcg depending on problem size and device. Test count rose from 1187 to 1220; the audit stayed clean.

Performance

All numbers are CPU, single-thread, PyTorch 2.12, float64, from the library's benchmark notes. These are the highlighted wins, not an average case.

Primitive	Size	Speedup	Note
Ollivier-Ricci curvature	n = 64	13×	Sinkhorn pair-tiling plus reduced sync cadence
FixedRank retraction	1024×1024 rank-32	25×	auto-switches to randomized SVD at low rank ratio
Lanczos top-1 eigenvalue	n = 1024	4.2×	vs dense `eigvalsh`
Sparse Laplacian construction	n = 1024	14×	vs dense `L = D − A`

The gains are real but scale-dependent: at small n, Lanczos and sparse-vs-dense crossovers can run the other way (dense wins at n = 128, for instance), because iterative methods pay fixed overhead that only amortizes once the problem is big enough. The benchmark notes document where each crossover sits.

Vs alternatives

Existing libraries cover slices of what's here. geoopt and pymanopt cover Riemannian manifolds and optimizers; geomstats adds information geometry; gudhi covers simplicial complexes and Hodge Laplacians. None combine breadth, GPU-native batched-first execution, an audit gate against uncataloged numerical constants, and citations on every public function.

Feature	holonomy_lib	geoopt	geomstats	pymanopt	gudhi
Riemannian manifolds + optimizers	yes	yes	yes	yes	no
Spectral graph theory (4+ Laplacians)	yes	no	no	no	no
Ollivier-Ricci + Forman-Ricci curvature	yes	no	no	no	no
Simplicial complexes + Hodge Laplacians	yes	no	no	no	yes
Batched persistent homology (H₀+H₁+H₂)	yes	no	no	no	no
GPU-native, batched-first	yes	yes	partial	no	no
Content-addressable provenance	yes	no	no	no	no
Audit gate (no uncataloged constants)	yes	no	no	no	no

Audit discipline

Every numerical constant in the codebase has to fall into one of three categories: derived from inputs (like 1 / N for normalization), a universal invariant (like a 1e-9 numerical floor or 2π), or experimentally tuned and cataloged with a scale of validity (like SINKHORN_TILE_DEFAULT = 256). A custom audit CLI, python -m holonomy_lib.audit src/ --strict, fails the build on any uncataloged literal and runs before every commit. The library ships 1220 tests: unit tests for correctness, property tests for invariants, and comparison tests against geoopt, pymanopt, tensorly, scipy, and GraphRicciCurvature where a comparable implementation exists.

Provenance for mechanistic interpretability

Every public primitive is decorated with @with_provenance. Inside a provenance.record() block, calls emit nodes in a content-addressable Merkle DAG, whose hex identity is a hash of the operation id, version, canonical parameters, and input hexes. Same operation, same inputs, same hex: deterministic and reproducible. This is what unlocks TransformerLens-style activation patching and SAELens-style dataset emission for mathematical primitives, not just neural network internals: substitute a node's value with reg.replay() and only the downstream computation re-executes. The registry can be exported as a Mermaid or Graphviz diagram, diffed against another run, or summarized as compact text for an agent prompt.

License

holonomy_lib is free software under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), including the AGPL's network clause: anyone running a modified version as a network service must make that modified source available to the service's users. The copyright holder also offers a commercial license for uses the AGPL does not permit, such as embedding the library in a proprietary product without the AGPL's source-disclosure obligations. For a commercial license, contact contact@synoros.io.