{"slug": "holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch", "title": "Holonomy_lib, exact non Euclidean geometry primitives for PyTorch", "summary": "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.", "body_md": "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.\n\nA consolidated PyTorch math library for research at the intersection of\n**differential geometry**, **spectral graph theory**, **computational\ntopology**, and **mechanistic interpretability**: the mathematics that\nmodern ML keeps reinventing project by project. Twelve modules, 1179\ntests, every numerical constant derived or cataloged with a\nscale-of-validity, every primitive cited to the paper that defines it.\n\nThe name **holonomy** comes from differential geometry: the\ntransformation a vector accumulates when parallel-transported around a\nclosed loop. It captures the library's character: every operation\ndefined by the geometry it preserves, every result traceable back to\nits inputs through a content-addressable provenance DAG.\n\n| Module | Primitives | What it gives you |\n|---|---|---|\n`manifolds` |\n`FixedRankManifold` , `SPDManifold` , `LorentzManifold` , `KappaStereographicManifold` , `LorentzianManifold` , , `ProductManifold` , `HeterogeneousKappaManifold` `comparison.*` |\nRiemannian 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 |\n`algebra` |\n`truncated_svd` (exact + randomized), `lanczos_eigsh` |\nHalko-Martinsson-Tropp randomized SVD; Eckart-Young exact; Lanczos top-k eigensolver with full reorthogonalization (Paige 1972) |\n`tensor_calculus` |\n`hosvd` , `mode_product` , `mode_unfolding` |\nTruncated HOSVD with Kolda-Bader n-mode product |\n`spectral` |\n`combinatorial` /`symmetric_normalized` /`random_walk` /`signed` Laplacians, `laplacian_eigenmaps` , `magnetic.*` (directed), `heat_kernel_chebyshev` , , `effective_resistance` , `commute_time` , `diffusion_map` `spectral_dimension` |\nChung; 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) |\n`discrete_geometry` |\n`ollivier_ricci_curvature` , `discrete_ricci_flow` , `ricci_flow_with_surgery` , `forman_ricci_simple` , `forman_ricci_augmented` |\nSinkhorn-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) |\n`info_geometry` |\n, `bregman_divergence` , `kl_divergence_categorical` `kl_divergence_gaussian` |\nBregman divergence for any convex generator plus closed-form KL for the standard exponential families (Bregman 1967; Banerjee et al. 2005; Amari 2016) |\n`optimization` |\n`RiemannianSGD` |\nSteepest descent on `FixedRankManifold` / `SPDManifold` / `LorentzManifold` via the existing projection + retraction API (Absil-Mahony-Sepulchre 2008, §4.1) |\n`simplicial` |\n, `DenseSimplicialComplex` , `SparseSimplicialComplex` `vietoris_rips_*` |\nSimplicial complex data structures + boundary operators + Vietoris-Rips construction; foundation for Hodge + persistent homology (Munkres 1984; Hausmann 1995; Bauer 2021) |\n`topology` |\n, `hodge_laplacian` , `betti_numbers` `persistence_diagrams` |\nHodge 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) |\n`sheaf` |\n, `GraphSheaf` , `HeterogeneousGraphSheaf` , `sheaf_coboundary` , `sheaf_laplacian` `sheaf_dirichlet_energy` |\nCellular 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) |\n`lie` |\n, `so3.{exp,log,axis_angle,random_so3,compose}` `real_spherical_harmonics` |\nSO(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 |\n`provenance` |\n`@with_provenance` , `record()` , `ProvenanceRegistry` |\nContent-addressable Merkle DAG of math primitives; substitution / replay / SAELens emission for mech interp |\n`hyperbolic` |\n, `frechet_mean` , `hyperbolic_laplacian_eigenmaps` , `manifold_aware_inner` `hyperbolic_heat_kernel` |\nManifold-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) |\n\nExisting libraries cover slices of what's here, but none cover all four properties this library guarantees:\n\n**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`\n\n/`rocm`\n\n/`mps`\n\n/`cpu`\n\n, verified for`B ∈ {0, 1, > 1}`\n\n.**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`\n\n.**Cited**: every public function has a`References:`\n\nsection pointing to the paper that defines its math. No \"trust me\" implementations.\n\n| this lib | geoopt | geomstats | pymanopt | gudhi | ripser | |\n|---|---|---|---|---|---|---|\n| Riemannian manifolds + optimizers | ✓ | ✓ | ✓ | ✓ | – | – |\n| Spectral graph theory (4+ Laplacians) | ✓ | – | – | – | – | – |\n| Magnetic Laplacian (directed graphs) | ✓ | – | – | – | – | – |\n| Ollivier-Ricci + Forman-Ricci curvature | ✓ | – | – | – | – | – |\n| Discrete Ricci flow + surgery | ✓ | – | – | – | – | – |\n| Tucker / HOSVD | ✓ | – | – | – | – | – |\n| Chebyshev heat kernel + diffusion maps | ✓ | – | – | – | – | – |\n| Simplicial complexes + Hodge Laplacians | ✓ | – | – | – | ✓ | – |\n| Batched persistent homology (H₀+H₁+H₂) | ✓ | – | – | – | – | – |\n| GPU-native (PyTorch) | ✓ | ✓ | partial | – | – | – |\n| Batched-first | ✓ | ✓ | partial | – | – | – |\n| Content-addressable provenance | ✓ | – | – | – | – | – |\n| Audit / no-magic-numbers | ✓ | – | – | – | – | – |\n| Information geometry (Bregman + KL) | ✓ | – | ✓ | – | – | – |\nDifferentiable hyperbolic heat kernel (all `n` ) |\n✓ | – | – | – | – | – |\n| Pseudo-Riemannian (Lorentzian) manifold | ✓ | – | – | – | – | – |\n| Per-point κ (heterogeneous curvature) | ✓ | – | – | – | – | – |\n| Mixed-curvature product manifold | ✓ | – | – | – | – | – |\n| Learnable κ that can cross 0 mid-training | ✓ | – | – | – | – | – |\n\nThe library has a small dependency surface: `torch >= 2.0`\n\n, `numpy`\n\n,\n`scipy`\n\n. Everything else, Riemannian optimizers, simplicial complexes,\nHodge Laplacians, persistent homology, is shipped natively. You do\n**not** need to install `pymanopt`\n\n, `geoopt`\n\n, `gudhi`\n\n, `ripser`\n\n, or\nsimilar to use the corresponding primitives.\n\n```\npip install holonomy-lib\n```\n\nThis pulls torch's default wheel (CPU or CUDA 12, depending on platform) automatically. Python ≥ 3.12.\n\nInstall your preferred torch wheel **first**, then the library. pip /\nuv will respect the already-installed torch:\n\n```\n# AMD ROCm 6.4:\npip install --index-url https://download.pytorch.org/whl/rocm6.4 torch\npip install holonomy-lib\n\n# CUDA 12.1 specifically:\npip install --index-url https://download.pytorch.org/whl/cu121 torch\npip install holonomy-lib\n\n# CPU only:\npip install --index-url https://download.pytorch.org/whl/cpu torch\npip install holonomy-lib\ngit clone https://github.com/Synoros-io/holonomy_lib\ncd holonomy_lib\nuv venv\nuv pip install -e \".[dev]\"\n```\n\n`holonomy-lib[provenance-extras]`\n\n:`blake3`\n\n(faster hash),`networkx`\n\n(DAG export),`pandas`\n\n(DataFrame export). Used only inside specific provenance helpers; the library degrades gracefully without them.`holonomy-lib[comparison]`\n\n: 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]`\n\n: pytest, ruff, mypy.`holonomy-lib[all]`\n\n: provenance-extras + dev (the typical contributor install).\n\n``` python\nimport torch\nfrom holonomy_lib.manifolds import SPDManifold\nfrom holonomy_lib.optimization import RiemannianSGD\nfrom holonomy_lib.spectral import laplacian, laplacian_eigenmaps\nfrom holonomy_lib.discrete_geometry import ricci_flow_with_surgery\nfrom holonomy_lib.topology import persistence_diagrams\nfrom holonomy_lib import provenance\n\n# 1. Riemannian geometry on SPD covariance matrices\nmfd = SPDManifold(n=8, dtype=torch.float64)\nS = mfd.random_point(batch_size=4)       # (4, 8, 8) SPD\nT = mfd.random_point(batch_size=4)\nd = mfd.distance(S, T)                    # affine-invariant geodesic\nV = mfd.log(S, T)                         # Lie-algebra-style log\nT_recon = mfd.exp(S, V)                   # exp_S(log_S(T)) ≈ T\n\n# 2. Riemannian gradient descent ON the SPD manifold\nopt = RiemannianSGD(mfd, lr=0.5)\npoint = S.clone()\nfor _ in range(50):\n    ambient_grad = -mfd.log(point, T)     # gradient of (1/2) d(point, T)^2\n    point = opt.step(point, ambient_grad)\n# `point` now sits on the SPD manifold, close to T.\n\n# 3. Graph spectral embedding\nA = (torch.rand(1, 50, 50) > 0.7).double()\nA = (A + A.mT) * 0.5                      # symmetrize\nvals, vecs = laplacian_eigenmaps(A, k=4, laplacian_type=\"symmetric_normalized\")\n\n# 4. Perelman-on-networks: community detection via Ricci flow + surgery\nA_after = ricci_flow_with_surgery(\n    A, n_steps=20, surgery_period=5, surgery_threshold=3.0,\n    dt=0.5, alpha=0.0,\n)\n# Disconnected components in A_after correspond to detected communities.\n\n# 5. Batched persistent homology on point clouds\npoints = torch.randn(8, 30, 2, dtype=torch.float64)   # 8 point clouds of 30 pts\ndiagrams, masks = persistence_diagrams(\n    points, max_dim=2, max_radius=2.5,\n)\n# diagrams[0]: (8, max_h0, 2)  birth/death pairs for H_0 (components)\n# diagrams[1]: (8, max_h1, 2)  for H_1 (loops)\n# diagrams[2]: (8, max_h2, 2)  for H_2 (voids)\n# masks[k] tells you which pair-slots are valid per batch element.\n\n# 6. Mech-interp-style provenance: every primitive emits a Merkle DAG node\nwith provenance.record(cache_tensors=True) as reg:\n    L = laplacian.combinatorial(A)\n    vals, vecs = laplacian_eigenmaps(A, k=4)\n\n# Look up any operation by content-addressable hex\nfor node in reg:\n    print(f\"{node.hex}  {node.op_id}\")\n```\n\nSee `CONTENTS.md`\n\nfor the complete inventory of primitives, signatures,\nand citations.\n\nBenchmarks: `notes/benchmark_baseline.md`\n\n(before optimization),\n`notes/benchmark_optimized.md`\n\n(post-Phase-3 fixes), and\n`notes/benchmark_2026-05-26_roadmap_sweep.md`\n\n(v0.1 roadmap items).\nAll times CPU, single-thread, PyTorch 2.12, float64.\n\nThe signature primitive, Ollivier-Ricci curvature via batched log-domain Sinkhorn over all-pairs shortest-path costs, got two optimizations:\n\n**Pair tiling**: the Sinkhorn dual update used to materialize a`(B, n², n, n)`\n\nintermediate (128 MB per iter at n=64). Tiled implementation processes pairs in chunks of`SINKHORN_TILE_DEFAULT = 256`\n\n, capping the inner broadcast at ~16 MB.**Sync cadence**: the`.item()`\n\nconvergence check used to fire every iter, forcing a GPU→CPU sync. Now checks every 8 iters; same asymptotic work, 8× fewer host syncs.\n\n| graph size (n) | before | after | speedup |\n|---|---|---|---|\n| 16 | 34.0 ms | 18.0 ms | 1.9× |\n| 32 | 273 ms | 133 ms | 2.1× |\n64 |\n22.6 s |\n1.7 s |\n13× |\n\n`FixedRankManifold.retraction`\n\nused to do a full SVD then slice top-r.\nAt low `r/min(m, n)`\n\nratios (the common case for the fixed-rank\nmanifold), it now auto-switches to Halko-Martinsson-Tropp randomized\nSVD with documented oversampling.\n\n| m × n × r | before (full SVD) | after (auto) | speedup |\n|---|---|---|---|\n| 64 × 64 × 8 | 0.31 ms | 0.31 ms | 1.0× (parity) |\n| 256 × 256 × 16 | 7.4 ms | 1.3 ms | 5.8× |\n1024 × 1024 × 32 |\n193 ms |\n7.6 ms |\n25× |\n\nThe library's `algebra.lanczos_eigsh`\n\nwith full reorthogonalization\nbeats `torch.linalg.eigvalsh`\n\nonce the matrix is big enough that\ncomputing the full spectrum becomes wasteful. Single-batch top-1\neigenvalue at CPU, float64:\n\n| n | dense `eigvalsh` |\n`lanczos_eigsh` (n_iter=30) |\nspeedup |\n|---|---|---|---|\n| 128 | 0.44 ms | 2.66 ms | 0.2× (Lanczos overhead dominates) |\n| 512 | 7.62 ms | 4.84 ms | 1.6× |\n1024 |\n46.5 ms |\n11.0 ms |\n4.2× |\n\nThe same `lanczos_eigsh`\n\naccepts sparse-CSC inputs (via the dispatch\nadded in Phase 3), so it's the natural top-k path on the sparse-Hodge\nLaplacians produced by the `topology`\n\nmodule.\n\n`lanczos_eigsh(A, k, which=\"SA\", sigma=σ)`\n\nruns Lanczos on\n`(A − σI)^{-1}`\n\nso the dominant Ritz values converge to the\neigenvalues of `A`\n\nclosest to σ (Ericsson-Ruhe 1980). LU-factor is\ndone once outside the iteration; each step is a `lu_solve`\n\n. Where the\nfactorization cost is amortized over enough iterations, it beats both\nLA Lanczos (which has to do many iterations to converge on the small\nend of the spectrum) and dense `eigvalsh`\n\n(which always pays `O(n³)`\n\n):\n\n| n | dense `eigvalsh` |\n`lanczos_eigsh` LA, n_iter=60 |\n`lanczos_eigsh` SA, n_iter=40 |\n|---|---|---|---|\n| 64 | 0.23 ms | 2.83 ms | 2.56 ms |\n| 256 | 3.34 ms | 4.89 ms | 4.77 ms |\n1024 |\n80.9 ms |\n24.5 ms | 18.9 ms |\n\nSA mode raises `RuntimeError(\"shift-invert breakdown\")`\n\nif σ coincides\nwith an eigenvalue of `A`\n\n— for graph Laplacians (which have 0 in\nspectrum) use a small negative shift.\n\nAll four Laplacian variants (combinatorial, symmetric-normalized,\nrandom-walk, signed) accept sparse-COO/CSR/CSC adjacency and return\na sparse-COO Laplacian on the same device. Combined with the sparse\n`lanczos_eigsh`\n\npath, you get end-to-end sparse spectral chains\nwithout materializing the dense `(n, n)`\n\n. The crossover is at very\nsmall `n`\n\nbecause sparse construction time stays nearly flat while\ndense scales `O(n²)`\n\n:\n\n| n | density | dense `L = D − A` |\nsparse `L` |\n|---|---|---|---|\n| 256 | 0.05 | 0.25 ms | 0.21 ms |\n| 1024 | 0.01 | 3.2 ms | 0.23 ms (14×) |\n| 4096 | 0.003 | n/a (16 GB) | 0.30 ms |\n\n`topology.persistence_diagrams`\n\ncomputes H₀ + H₁ + H₂ for a batch of\npoint clouds in parallel. H₀ runs via union-find on sorted filtration\nedges (no boundary-matrix reduction needed). H₁ and H₂ use Z/2\nleft-to-right reduction (Edelsbrunner-Letscher-Zomorodian 2002) on\nsparse-CSC boundary matrices, batching across point clouds.\n\nClosed-form verification: a noisy 30-point unit circle reliably\nrecovers one persistent H₁ bar (the loop) with persistence > 0.2 in\nthe default `max_radius`\n\nrange; the bottleneck stability theorem\n(Cohen-Steiner-Edelsbrunner-Harer 2007) is verified under\nε-perturbation in the test suite.\n\nThe `reduction_backend=\"torch\"`\n\npath runs end-to-end on the\nfiltration's device (CPU or GPU) — but is **not yet a custom CUDA\nkernel**, just a torch-tensor port of the same sequential algorithm.\nFor small inputs CPython sets are faster (43 ms vs 903 ms on an\n80-point circle); the torch path is a foundation for the v0.2 GPU\nkernel rather than an immediate win. The default backend stays\n`\"python\"`\n\n.\n\nEvery numerical constant must be in one of three categories:\n\n| Category | Example |\n|---|---|\n✅ Derived from inputs |\n`1 / N` for normalization; `1 / sqrt(d)` for Laplacian normalization |\n⚖️ Universal invariant |\n`1e-9` numerical floor; `0.5` halving; `2π` ; `1024` (KB↔MB) |\n🔬 Experimentally tuned |\n`SINKHORN_TILE_DEFAULT = 256` , cataloged with scale-of-validity |\n\nEach constant in category 🔬 has a row in [ notes/magic_numbers.md](/Synoros-io/holonomy_lib/blob/master/notes/magic_numbers.md)\nwith the procedure used to pick it, the regime where it's valid, and what\nto re-derive when scale changes. The audit tool\n(\n\n`python -m holonomy_lib.audit src/ --strict`\n\n) fails on any uncataloged\nliteral; run it before every commit.Every public primitive is decorated with `@with_provenance`\n\n. Inside a\n`provenance.record()`\n\nblock, calls emit Merkle-DAG nodes whose hex\nidentity is `hash(op_id || op_version || canonical(params) || input_hexes)`\n\n. Same op, same inputs ⇒ same hex (deterministic, content-\naddressable).\n\nThis unlocks TransformerLens-style activation patching and SAELens- style dataset emission for the mathematical primitives, not just neural network internals:\n\n```\nwith provenance.record(cache_tensors=True) as reg:\n    out = pipeline(A)\n\n# Find a specific operation\nlap_node = reg.where(op_id=\"holonomy_lib.spectral.laplacian.combinatorial\")[0]\n\n# Ablation: substitute zeros and replay only the downstream computation\nnew = reg.replay({lap_node.hex: torch.zeros_like(reg.get_tensor(lap_node.hex))})\n# `new` contains the re-executed outputs of every node downstream of the substitution.\n\n# Emit a SAELens-style dataset for training feature extractors\nfor tensor, metadata in reg.to_sae_dataset(op_id=\"holonomy_lib.algebra.linear.truncated_svd\"):\n    yield tensor, metadata\n```\n\nPluggable hash function (blake3 if installed, else SHA-256). Persist\nthe DAG with `reg.save(path)`\n\n/ `ProvenanceRegistry.load(path)`\n\n.\n\n**Performance modes** (v0.3): `record(hash_mode=\"sketch\")`\n\nswaps the\nbyte-level content hash for an O(1)-bytes sketch (shape + dtype + 64\nstrided samples + sum + std). About 15× faster than full mode on 8 MB\ntensors; crossover at ~n=256. `record(cache_to_disk=path)`\n\nmirrors the\noutput cache to torch.save'd files, so memory eviction from\n`max_cache_size`\n\ndoesn't lose tensors: `get_tensor()`\n\nreloads on\ndemand. Both default off.\n\n**Inspection** (v0.3): `reg.to_mermaid()`\n\n, `reg.to_graphviz()`\n\nfor\nvisualization; `reg.diff_summary(other)`\n\nfor \"did my refactor preserve\nsemantics\" comparisons; `reg.to_llm_context()`\n\nfor a compact text\nsummary suitable for an agent prompt.\n\n**Agent access** (v0.3, optional extras): `pip install 'holonomy-lib[mcp]'`\n\nadds an MCP server (`python -m holonomy_lib.provenance.mcp`\n\n) that\nexposes the registry as agent tools for Claude, GPT, or any MCP\nclient. `pip install 'holonomy-lib[jupyter]'`\n\nadds a\n`%%record_provenance`\n\ncell magic that records and renders the DAG\ninline.\n\n```\n# Full test suite\nuv run pytest\n\n# Just one module\nuv run pytest tests/manifolds\n\n# Run the audit (build gate)\nuv run python -m holonomy_lib.audit src/ --strict\n\n# Run benchmarks (excluded from the test suite; runs on demand)\nuv run python -m tests.benchmarks.run --out notes/benchmark_latest.md\n\n# Run on a GPU machine; parity tests light up automatically\nuv run pytest tests/test_device_parity.py\n```\n\n**Comparison tests** run against established libraries when installed:\n`pymanopt`\n\nfor FixedRankManifold, `geoopt`\n\nfor SPDManifold, `tensorly`\n\nfor HOSVD, `scipy.sparse.csgraph`\n\nfor Laplacians,\n`GraphRicciCurvature`\n\n+ `networkx`\n\nfor Ollivier-Ricci. The tests skip\nsilently if a comparison library isn't installed.\n\n```\nholonomy_lib/\n├── src/holonomy_lib/          # the library\n│   ├── manifolds/             # FixedRank, SPD, Lorentz, κ-stereographic, Lorentzian, Product, heterogeneous-κ\n│   ├── hyperbolic/            # manifold-aware graph ops: Fréchet mean, eigenmaps, heat kernel\n│   ├── algebra/               # truncated_svd, lanczos_eigsh (LA + shift-invert SA)\n│   ├── tensor_calculus/       # hosvd, mode_product, mode_unfolding\n│   ├── spectral/              # 4 Laplacians (incl. magnetic + sign-magnetic), eigenmaps, heat kernel, resistance, diffusion maps\n│   ├── discrete_geometry/     # Ollivier-Ricci, discrete Ricci flow, surgery, Forman-Ricci\n│   ├── info_geometry/         # Bregman + KL divergences, Fisher metric, natural gradient\n│   ├── optimization/          # RiemannianSGD on FixedRank / SPD\n│   ├── simplicial/            # Dense + Sparse complexes, Vietoris-Rips\n│   ├── topology/              # Hodge Laplacians, Betti, persistence diagrams (H₀+H₁+H₂)\n│   ├── sheaf/                 # cellular sheaves on graphs, sheaf Laplacians\n│   ├── lie/                   # SO(3) primitives, real spherical harmonics (l ≤ 4)\n│   ├── provenance/            # content-addressable hex protocol\n│   └── audit.py               # audit gate: no magic numbers\n├── tests/                     # 1179 tests across all modules\n│   └── benchmarks/            # device-agnostic timing harness\n├── notes/\n│   ├── magic_numbers.md       # cataloged constants with scale-of-validity\n│   ├── scrutiny.md            # findings + fixes from review passes\n│   ├── benchmark_baseline.md  # before optimization\n│   └── benchmark_optimized.md # after\n├── CHANGELOG.md               # release history\n└── CONTENTS.md                # primitive inventory and quick reference\n```\n\nSee [ CHANGELOG.md](/Synoros-io/holonomy_lib/blob/master/CHANGELOG.md) for the full release history.\n\n**v0.5.2** (current): measurement + structure primitives.\n\n`manifolds.comparison`\n\n— Bishop-Gromov model-space sphere area / ball volume at real (non-integer) dimension and signed curvature.`spectral.spectral_dimension`\n\n— spectral dimension`d_s`\n\nfrom a Laplacian spectrum (non-integer / fractal dimensions supported).`sheaf.HeterogeneousGraphSheaf`\n\n— cellular sheaf with per-node (heterogeneous) stalk dimensions; reduces to`GraphSheaf`\n\nunder uniform dims.- Closed-form\n`H^7`\n\nheat kernel, one operator-chain step beyond`H^5`\n\n; the odd-n heat-kernel recursion now seeds from it.\n\n**v0.5.0**: hyperbolic / pseudo-Riemannian / mixed-curvature\nmanifold pass.\n\n- Five new manifold classes:\n`LorentzManifold`\n\n(hyperboloid model of`H^n_k`\n\n),`KappaStereographicManifold`\n\n(parametric κ interpolating spherical / Euclidean / hyperbolic, with learnable κ that can cross 0 mid-training via dynamic sign dispatch),`LorentzianManifold`\n\n(pseudo-Riemannian`(1, n-1)`\n\nMinkowski spacetime with causal structure + flat-background curvature tensors),`ProductManifold`\n\n(mixed-curvature direct product), and`HeterogeneousKappaManifold`\n\n(per-point κ with a configurable pair-κ combiner). - New\n`holonomy_lib.hyperbolic`\n\nmodule of manifold-agnostic graph operations:`manifold_aware_inner`\n\n,`frechet_mean`\n\n(Karcher iteration),`hyperbolic_laplacian_eigenmaps`\n\n(RSGD embedding), and`hyperbolic_heat_kernel`\n\n(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.\n- Test count 707 → 1143; audit clean.\n\n**v0.4.1**: end-to-end MCP transport fixes.\n\n`mcp.py`\n\neagerly imports all op-defining submodules at server startup so`OP_REGISTRY`\n\nis populated before`replay_with`\n\nruns (loaded registries reference ops the server process otherwise never touches).`_bind_registry`\n\nnow inspects each tool's signature and only pre-binds the`registry`\n\nargument when the function actually declares one (`op_docstring`\n\nqueries global state and doesn't).- List-returning tools wrap their return in\n`{\"results\": [...]}`\n\non 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.\n\n**v0.4.0**: provenance agent-API redesign.\n\n- New\n`holonomy_lib.provenance.agent`\n\nmodule holds the canonical agent tool inventory. Each tool is a Python function decorated with`@agent_tool`\n\n;`to_anthropic_schema()`\n\n/`to_openai_schema()`\n\nemit native LLM tool-use JSON. - Inspection tools (each callable as a native LLM tool, an MCP tool,\nor directly from Python):\n`tensor_slice`\n\n(numpy-syntax indexing),`tensor_per_batch_summary`\n\n,`tensor_eigenvalues`\n\n,`tensor_singular_values`\n\n,`tensor_norm`\n\n,`tensor_compare`\n\n,`op_docstring`\n\n. Replaces v0.3.0's global-stats-only`get_tensor_summary`\n\n, which couldn't see per-batch anomalies. `replay_with(target_hex, recipe)`\n\nsubstitution DSL: kinds are`zeros_like`\n\n,`from_hex`\n\n,`perturb`\n\n(Gaussian noise with required seed),`scale`\n\n,`swap_batch`\n\n,`literal`\n\n. Replaces v0.3.0's zero-fill-only MCP`replay`\n\n.`mcp.py`\n\nrefactored 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.\n\n**v0.3.0**: provenance module sweep.\n\n- Performance: opt-in sketch hashing (15× faster on 8 MB tensors via\nshape + dtype + 64 strided samples + sum + std) and on-disk tensor\ncache (memory eviction retains the disk copy;\n`get_tensor()`\n\nreloads on demand). - Robustness:\n`replay()`\n\nnow works for class-method calls and tuple-of-tensor inputs (FixedRankPoint = (U, S, Vt)). Op-version drift detector on`load()`\n\nemits`ProvenanceVersionWarning`\n\nwith optional`strict=True`\n\nescalation. - Visualization:\n`to_mermaid()`\n\n,`to_graphviz()`\n\n,`diff_summary(other)`\n\nwith Cache hits / Drift / Only-in-self / Only-in-other categories,`ancestors_with_tensors(hex)`\n\nconvenience. - Agent access:\n`to_llm_context()`\n\ntext summary; MCP server (`pip install 'holonomy-lib[mcp]'`\n\n); Jupyter`%record_provenance`\n\ncell magic (`pip install 'holonomy-lib[jupyter]'`\n\n).\n\n**v0.2.0**: six new modules and several extensions since\nthe v0.1.0 seed.\n\n- New modules:\n`optimization`\n\n(RiemannianSGD),`simplicial`\n\n(Dense / Sparse complexes + Vietoris-Rips),`topology`\n\n(Hodge Laplacians + Betti + batched persistent homology H₀+H₁+H₂),`info_geometry`\n\n(Bregman + KL + Fisher metric + natural gradient),`sheaf`\n\n(cellular sheaves on graphs + sheaf Laplacians),`lie`\n\n(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.\n- Algebra additions:\n`lanczos_eigsh`\n\nwith LA (largest algebraic) and shift-and-invert SA (smallest algebraic) modes. - Class-method provenance for\n`FixedRankManifold`\n\n/`SPDManifold`\n\n; device-agnostic torch reduction backend for persistent homology (foundation for a future custom CUDA kernel).\n\n**v0.1.0**: initial public release. `manifolds`\n\n, `algebra`\n\n,\n`tensor_calculus`\n\n, `spectral`\n\n(4 Laplacians + eigenmaps),\n`discrete_geometry`\n\n(Ollivier-Ricci + flow + surgery), `provenance`\n\n.\n\n**Frontiers** (v0.6+): Wigner-D matrices (real basis) to complete the\nSO(3) equivariance story so spherical-harmonic features mix\ncorrectly under rotation; optimal transport extensions\n(Gromov-Wasserstein for metric-measure-space comparison, Sinkhorn\ndivergences for de-biased OT); GPU-resident custom CUDA kernel for\nthe Z/2 PH reduction (current torch path is sequential with a\nper-column CPU sync); sparse-input shift-and-invert via iterative\nsolver (CG/MINRES); higher-dim cellular sheaves on simplicial\ncomplexes; further manifolds (sphere, Stiefel, Grassmann);\nSE(3) / SU(2) / SL(n) Lie group primitives.\nContributions welcome via PR.\n\nIf this library helps your research, please cite it:\n\n```\n@software{holonomy_lib,\n  author = {John Vaught},\n  title = {holonomy\\_lib: GPU-native research math for differential\n           geometry, spectral graph theory, and mechanistic interpretability},\n  year = {2026},\n  url = {https://github.com/Synoros-io/holonomy_lib},\n}\n```\n\nThe 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).\n\nSee [ CONVENTIONS.md](/Synoros-io/holonomy_lib/blob/master/CONVENTIONS.md) for the full coding standards\n(batched-first API shape, self-loop policy, numerical conventions,\nperformance patterns, magic-numbers catalog, citation requirements,\nprovenance, testing). Contributions welcome. Hard constraints\n(binding for any code in this repo):\n\n**Citations are non-optional.** Every public function has a`References:`\n\nsection pointing to the paper for its math.**Every numerical constant has a derivation or a catalog entry** in`notes/magic_numbers.md`\n\n. 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`\n\non`cuda`\n\n/`rocm`\n\n/`cpu`\n\n. Verify shapes for`B ∈ {0, 1, > 1}`\n\n.\n\nOpen an issue first for non-trivial additions so we can align on approach.\n\nholonomy_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.\n\nCopyright © 2026 Synoros.\n\n**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).", "url": "https://wpnews.pro/news/holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch", "canonical_source": "https://github.com/Synoros-io/holonomy_lib", "published_at": "2026-05-30 09:24:56+00:00", "updated_at": "2026-05-30 09:48:35.457456+00:00", "lang": "en", "topics": ["machine-learning", "neural-networks", "ai-research", "ai-tools", "ai-infrastructure"], "entities": ["PyTorch", "Synoros", "Holonomy_lib", "thesubstrateresearch"], "alternates": {"html": "https://wpnews.pro/news/holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch", "markdown": "https://wpnews.pro/news/holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch.md", "text": "https://wpnews.pro/news/holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch.txt", "jsonld": "https://wpnews.pro/news/holonomy-lib-exact-non-euclidean-geometry-primitives-for-pytorch.jsonld"}}