holonomy-lib 0.8.0__tar.gz

holonomy_lib-0.8.0/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Synoros
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

holonomy_lib-0.8.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: holonomy-lib
+Version: 0.8.0
+Summary: Batched PyTorch primitives for Riemannian geometry, spectral graph theory, discrete curvature, topology, and tensor decompositions.
+Author: Synoros
+License-Expression: FSL-1.1-ALv2
+Project-URL: Homepage, https://github.com/Synoros-io/holonomy_lib
+Project-URL: Repository, https://github.com/Synoros-io/holonomy_lib
+Project-URL: Issues, https://github.com/Synoros-io/holonomy_lib/issues
+Keywords: pytorch,differential-geometry,riemannian-manifolds,hyperbolic-geometry,riemannian-optimization,spectral-graph-theory,graph-laplacian,magnetic-laplacian,heat-kernel,diffusion-maps,effective-resistance,ricci-curvature,ricci-flow,cellular-sheaves,simplicial-complex,hodge-laplacian,persistent-homology,topological-data-analysis,information-geometry,tensor-decomposition,numerical-linear-algebra
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: torch>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11.2
+Provides-Extra: comparison
+Requires-Dist: pymanopt; extra == "comparison"
+Requires-Dist: geoopt; extra == "comparison"
+Requires-Dist: geomstats; extra == "comparison"
+Requires-Dist: autograd; extra == "comparison"
+Requires-Dist: tensorly; extra == "comparison"
+Requires-Dist: networkx; extra == "comparison"
+Requires-Dist: gudhi; extra == "comparison"
+Requires-Dist: ripser; extra == "comparison"
+Requires-Dist: GraphRicciCurvature; extra == "comparison"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: scipy-stubs; extra == "dev"
+Dynamic: license-file
+
+# holonomy_lib
+
+Geometry, graph and topology primitives for PyTorch. Most functions take a batch
+of inputs (a leading batch dimension) and run on the device and dtype you pass in.
+
+## Install
+
+Python 3.12 or later. Install PyTorch for your hardware first, using the
+[PyTorch selector](https://pytorch.org/get-started/locally/), then:
+
+```bash
+pip install holonomy-lib
+```
+
+## Example
+
+Effective resistance between the ends of a three-node path and of a triangle,
+computed as one batch:
+
+```python
+import torch
+from holonomy_lib.spectral import effective_resistance
+
+device = "cuda" if torch.cuda.is_available() else "cpu"  # ROCm builds also use "cuda"
+adjacency = torch.tensor([
+    [[0, 1, 0], [1, 0, 1], [0, 1, 0]],  # path 0-1-2
+    [[0, 1, 1], [1, 0, 1], [1, 1, 0]],  # triangle
+], dtype=torch.float64, device=device)
+
+R = effective_resistance(adjacency)
+print(R.shape)        # torch.Size([2, 3, 3])
+print(R[:, 0, 2])     # tensor([2.0000, 0.6667], dtype=torch.float64)
+```
+
+## What's in it
+
+[CONTENTS.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CONTENTS.md) lists every function with its signature and the
+paper it implements.
+
+| Subpackage | Contents |
+|---|---|
+| `manifolds` | Fixed-rank, SPD, Lorentz, Lorentzian, stereographic and product manifolds; model-space volumes. |
+| `optimization` | Riemannian SGD. |
+| `hyperbolic` | Fréchet means, manifold-aware inner products, hyperbolic heat kernels. |
+| `lie` | SO(3) exponential and logarithm, rotations, real spherical harmonics. |
+| `info_geometry` | Bregman and KL divergences, Fisher information, natural gradients. |
+| `tensor_calculus` | Mode unfolding, mode products, HOSVD. |
+| `algebra` | Truncated SVD, dense and sparse eigensolvers, conjugate gradient, LSQR. |
+| `convex` | Regularized least squares. |
+| `spectral` | Graph Laplacians, embeddings, heat diffusion, effective resistance, spectral dimension. |
+| `discrete_geometry` | Ollivier and Forman curvature, Ricci flow with surgery. |
+| `sheaf` | Graph sheaves, coboundaries, sheaf Laplacians and their spectra. |
+| `simplicial` | Dense and sparse simplicial complexes, boundary operators, Vietoris-Rips. |
+| `topology` | Hodge Laplacians, Betti numbers, persistent homology. |
+
+## Explorer
+
+`holonomy-explorer` opens a local page that runs the library live: curvature
+and diffusion on graphs, geodesics as curvature passes through zero,
+persistent homology of point clouds, and batch-size timings on your hardware.
+Options: `--device`, `--dtype`, `--port`, `--no-browser`.
+
+![The explorer's graph view](https://raw.githubusercontent.com/Synoros-io/holonomy_lib/master/docs/explorer.png)
+
+## Experimental
+
+`holonomy_lib.experimental` holds two unfinished pieces that are not part of
+the stable API:
+
+- `hyperbolic_laplacian_eigenmaps`: nothing in its objective keeps nodes apart,
+  so an embedding can collapse to a point.
+- `HeterogeneousKappaManifold`: a curvature per point. Its `dissimilarity` is
+  not a metric.
+
+## Limits
+
+- Use `float64` when accuracy matters.
+- Sparse eigensolvers, sparse simplicial complexes and sheaves handle one
+  instance at a time. Sparse eigensolvers are not differentiable.
+- Persistent homology runs its reduction one batch member at a time on the CPU.
+- Ollivier curvature uses entropy-regularized transport, so it is close to the
+  exact value rather than equal to it, and it warns if the solver did not
+  converge. Edge weights act as both lengths and random-walk weights.
+- Gradients through `cg` can be wrong when it converges in very few iterations.
+- Effective resistance and commute time are `inf` between disconnected components.
+
+## Development
+
+```bash
+uv sync --extra dev
+python -m pytest -q
+python -m ruff check src/ tests/
+python -m mypy src/
+python tools/audit.py src/holonomy_lib --strict
+```
+
+[CONVENTIONS.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CONVENTIONS.md) has the coding and numerical rules;
+[CHANGELOG.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CHANGELOG.md) has the release history.
+
+## Citation
+
+```bibtex
+@software{holonomy_lib,
+  author = {John Vaught},
+  title = {holonomy\_lib: Batched PyTorch primitives for geometry and topology},
+  version = {0.8.0},
+  year = {2026},
+  url = {https://github.com/Synoros-io/holonomy_lib},
+}
+```
+
+Please also cite the papers named in the docstrings of the functions you use.
+
+## License
+
+[FSL-1.1-ALv2](https://github.com/Synoros-io/holonomy_lib/blob/master/LICENSE.md). You can use and modify it freely; competing
+commercial use is reserved to Synoros. Each release becomes Apache-2.0 two
+years after it ships. Releases up to 0.7.0 remain AGPL-3.0-or-later. For other
+terms, contact [contact@synoros.io](mailto:contact@synoros.io).

holonomy_lib-0.8.0/README.md

@@ -0,0 +1,119 @@
+# holonomy_lib
+
+Geometry, graph and topology primitives for PyTorch. Most functions take a batch
+of inputs (a leading batch dimension) and run on the device and dtype you pass in.
+
+## Install
+
+Python 3.12 or later. Install PyTorch for your hardware first, using the
+[PyTorch selector](https://pytorch.org/get-started/locally/), then:
+
+```bash
+pip install holonomy-lib
+```
+
+## Example
+
+Effective resistance between the ends of a three-node path and of a triangle,
+computed as one batch:
+
+```python
+import torch
+from holonomy_lib.spectral import effective_resistance
+
+device = "cuda" if torch.cuda.is_available() else "cpu"  # ROCm builds also use "cuda"
+adjacency = torch.tensor([
+    [[0, 1, 0], [1, 0, 1], [0, 1, 0]],  # path 0-1-2
+    [[0, 1, 1], [1, 0, 1], [1, 1, 0]],  # triangle
+], dtype=torch.float64, device=device)
+
+R = effective_resistance(adjacency)
+print(R.shape)        # torch.Size([2, 3, 3])
+print(R[:, 0, 2])     # tensor([2.0000, 0.6667], dtype=torch.float64)
+```
+
+## What's in it
+
+[CONTENTS.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CONTENTS.md) lists every function with its signature and the
+paper it implements.
+
+| Subpackage | Contents |
+|---|---|
+| `manifolds` | Fixed-rank, SPD, Lorentz, Lorentzian, stereographic and product manifolds; model-space volumes. |
+| `optimization` | Riemannian SGD. |
+| `hyperbolic` | Fréchet means, manifold-aware inner products, hyperbolic heat kernels. |
+| `lie` | SO(3) exponential and logarithm, rotations, real spherical harmonics. |
+| `info_geometry` | Bregman and KL divergences, Fisher information, natural gradients. |
+| `tensor_calculus` | Mode unfolding, mode products, HOSVD. |
+| `algebra` | Truncated SVD, dense and sparse eigensolvers, conjugate gradient, LSQR. |
+| `convex` | Regularized least squares. |
+| `spectral` | Graph Laplacians, embeddings, heat diffusion, effective resistance, spectral dimension. |
+| `discrete_geometry` | Ollivier and Forman curvature, Ricci flow with surgery. |
+| `sheaf` | Graph sheaves, coboundaries, sheaf Laplacians and their spectra. |
+| `simplicial` | Dense and sparse simplicial complexes, boundary operators, Vietoris-Rips. |
+| `topology` | Hodge Laplacians, Betti numbers, persistent homology. |
+
+## Explorer
+
+`holonomy-explorer` opens a local page that runs the library live: curvature
+and diffusion on graphs, geodesics as curvature passes through zero,
+persistent homology of point clouds, and batch-size timings on your hardware.
+Options: `--device`, `--dtype`, `--port`, `--no-browser`.
+
+![The explorer's graph view](https://raw.githubusercontent.com/Synoros-io/holonomy_lib/master/docs/explorer.png)
+
+## Experimental
+
+`holonomy_lib.experimental` holds two unfinished pieces that are not part of
+the stable API:
+
+- `hyperbolic_laplacian_eigenmaps`: nothing in its objective keeps nodes apart,
+  so an embedding can collapse to a point.
+- `HeterogeneousKappaManifold`: a curvature per point. Its `dissimilarity` is
+  not a metric.
+
+## Limits
+
+- Use `float64` when accuracy matters.
+- Sparse eigensolvers, sparse simplicial complexes and sheaves handle one
+  instance at a time. Sparse eigensolvers are not differentiable.
+- Persistent homology runs its reduction one batch member at a time on the CPU.
+- Ollivier curvature uses entropy-regularized transport, so it is close to the
+  exact value rather than equal to it, and it warns if the solver did not
+  converge. Edge weights act as both lengths and random-walk weights.
+- Gradients through `cg` can be wrong when it converges in very few iterations.
+- Effective resistance and commute time are `inf` between disconnected components.
+
+## Development
+
+```bash
+uv sync --extra dev
+python -m pytest -q
+python -m ruff check src/ tests/
+python -m mypy src/
+python tools/audit.py src/holonomy_lib --strict
+```
+
+[CONVENTIONS.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CONVENTIONS.md) has the coding and numerical rules;
+[CHANGELOG.md](https://github.com/Synoros-io/holonomy_lib/blob/master/CHANGELOG.md) has the release history.
+
+## Citation
+
+```bibtex
+@software{holonomy_lib,
+  author = {John Vaught},
+  title = {holonomy\_lib: Batched PyTorch primitives for geometry and topology},
+  version = {0.8.0},
+  year = {2026},
+  url = {https://github.com/Synoros-io/holonomy_lib},
+}
+```
+
+Please also cite the papers named in the docstrings of the functions you use.
+
+## License
+
+[FSL-1.1-ALv2](https://github.com/Synoros-io/holonomy_lib/blob/master/LICENSE.md). You can use and modify it freely; competing
+commercial use is reserved to Synoros. Each release becomes Apache-2.0 two
+years after it ships. Releases up to 0.7.0 remain AGPL-3.0-or-later. For other
+terms, contact [contact@synoros.io](mailto:contact@synoros.io).

holonomy_lib-0.8.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "holonomy-lib"
+version = "0.8.0"
+description = "Batched PyTorch primitives for Riemannian geometry, spectral graph theory, discrete curvature, topology, and tensor decompositions."
+readme = "README.md"
+license = "FSL-1.1-ALv2"
+license-files = ["LICENSE.md"]
+authors = [{ name = "Synoros" }]
+requires-python = ">=3.12"
+keywords = [
+    "pytorch",
+    "differential-geometry",
+    "riemannian-manifolds",
+    "hyperbolic-geometry",
+    "riemannian-optimization",
+    "spectral-graph-theory",
+    "graph-laplacian",
+    "magnetic-laplacian",
+    "heat-kernel",
+    "diffusion-maps",
+    "effective-resistance",
+    "ricci-curvature",
+    "ricci-flow",
+    "cellular-sheaves",
+    "simplicial-complex",
+    "hodge-laplacian",
+    "persistent-homology",
+    "topological-data-analysis",
+    "information-geometry",
+    "tensor-decomposition",
+    "numerical-linear-algebra",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+
+# The floors are the first releases that ship Python 3.12 wheels; nothing in
+# the source needs anything newer. torch decides the hardware: pip picks the
+# default CUDA wheel, so for ROCm, a specific CUDA version or CPU-only, install
+# torch first from https://pytorch.org/get-started/locally/ and pip will keep it.
+dependencies = [
+    "torch>=2.2",
+    "numpy>=1.26",
+    "scipy>=1.11.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Synoros-io/holonomy_lib"
+Repository = "https://github.com/Synoros-io/holonomy_lib"
+Issues = "https://github.com/Synoros-io/holonomy_lib/issues"
+
+[project.scripts]
+holonomy-explorer = "holonomy_explorer.__main__:main"
+
+[tool.setuptools.package-data]
+holonomy_explorer = ["static/*"]
+
+[project.optional-dependencies]
+# Libraries the cross-check tests compare against. None of them are needed at
+# runtime; each comparison test skips itself when its library is missing.
+comparison = [
+    "pymanopt",
+    "geoopt",
+    "geomstats",
+    "autograd",
+    "tensorly",
+    "networkx",
+    "gudhi",
+    "ripser",
+    "GraphRicciCurvature",
+]
+
+# Development toolchain: tests, lint, type checks (with SciPy's stubs so mypy
+# can see through the sparse and quadrature fallbacks).
+dev = ["pytest", "ruff", "mypy", "scipy-stubs"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+extend-exclude = [".scratch", "archive", "notes"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src"]
+check_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true

holonomy_lib-0.8.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

holonomy_lib-0.8.0/src/holonomy_explorer/__init__.py

@@ -0,0 +1 @@
+"""Local, offline views of computations performed by holonomy_lib."""

holonomy_lib-0.8.0/src/holonomy_explorer/__main__.py

@@ -0,0 +1,79 @@
+"""Launch with holonomy-explorer or python -m holonomy_explorer."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import webbrowser
+
+import torch
+
+from .common import Context
+from .server import create_server
+
+# Local-only defaults requested by the explorer brief; every deployment can override.
+DEFAULT_HOST = "127.0.0.1"
+WILDCARD_HOST = "0.0.0.0"  # IPv4 bind-all address; browse via loopback instead.
+DEFAULT_PORT = 8765
+DEFAULT_DTYPE = "float64"
+MAX_PORT = 65535  # TCP port field is an unsigned 16-bit integer.
+
+
+def main() -> None:
+    """Parse deployment settings, print the bound URL, and serve until Ctrl-C."""
+    parser = argparse.ArgumentParser(
+        description="Local holonomy_lib explorer. Offline UI; CPU/CUDA tensors.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--host",
+        default=os.getenv("HOLONOMY_EXPLORER_HOST", DEFAULT_HOST),
+        help="bind address; env HOLONOMY_EXPLORER_HOST",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=os.getenv("HOLONOMY_EXPLORER_PORT", str(DEFAULT_PORT)),
+        help="TCP port, 0 chooses a free port; env HOLONOMY_EXPLORER_PORT",
+    )
+    parser.add_argument(
+        "--device",
+        default=os.getenv(
+            "HOLONOMY_EXPLORER_DEVICE",
+            "cuda" if torch.cuda.is_available() else "cpu",
+        ),
+        help="torch device; env HOLONOMY_EXPLORER_DEVICE; ROCm also uses cuda",
+    )
+    parser.add_argument(
+        "--dtype",
+        choices=("float32", "float64"),
+        default=os.getenv("HOLONOMY_EXPLORER_DTYPE", DEFAULT_DTYPE),
+        help="tensor precision; env HOLONOMY_EXPLORER_DTYPE",
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="print URL without opening a browser"
+    )
+    args = parser.parse_args()
+    if not 0 <= args.port <= MAX_PORT:
+        parser.error(f"port must be between 0 and {MAX_PORT}")
+    try:
+        context = Context.from_request({"device": args.device, "dtype": args.dtype})
+        server = create_server(args.host, args.port, str(context.device), args.dtype)
+    except (OSError, ValueError, RuntimeError) as error:
+        parser.error(str(error))
+    # Wildcard bindings are not navigable destinations; loopback reaches this server.
+    browser_host = DEFAULT_HOST if args.host == WILDCARD_HOST else args.host
+    url = f"http://{browser_host}:{server.server_address[1]}"
+    print(f"Holonomy explorer: {url} ({context.device}, {args.dtype})", flush=True)
+    if not args.no_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()