Oineus¶
Oineus
Parallel persistent homology and topology-aware optimization for Python and C++.
Oineus is a C++20 library (with first-class Python bindings) for computing persistent homology on large datasets and for differentiating through the persistence pipeline so you can train models that care about topology. It supports cubical, Vietoris–Rips, and alpha filtrations; kernel / image / cokernel persistence for simplicial maps; Wasserstein barycenters; and a PyTorch-compatible differentiable layer.
Compute your first persistence diagram from a NumPy array. No C++ build
required — pip install oineus.
Walk through sublevel sets, birth/death events, and persistence diagrams on small 2D examples. Runs as a notebook you can edit.
A task-oriented walkthrough: alpha and VR diagrams, function-data diagrams, distances, manual workflow, Fréchet means, plotting, differentiable diagrams, kernel/image/cokernel, zero persistence.
Auto-generated function and class reference for oineus and oineus.diff.
Name and pronunciation¶
Oineus is named after a king in Greek mythology.
Say it OY-neh-oos, IPA /ˈɔɪneʊs/, with the stress on the first syllable:
Oi as in oil or coin.
-eus as in Orpheus, Theseus, or Prometheus, roughly “eh-oos”.
What’s inside¶
Filtrations on cubical complexes, Vietoris–Rips complexes, alpha shapes, and user-specified simplicial complexes.
Parallel persistence reduction with clearing optimization and optional V/U-matrix computation; the core algorithm is from Morozov & Nigmetov, SPAA 2020.
Kernel, image, and cokernel persistence for simplicial maps, including induced matchings.
Topology-aware optimization via the critical-set method from Nigmetov & Morozov, 2022 — solve singleton losses, pick conflict-resolution strategies, and push gradients back into scalar fields or point clouds.
Differentiable diagrams in
oineus.difffor end-to-end PyTorch training with topological loss terms (sliced Wasserstein, matching-based).Wasserstein / bottleneck distances and Fréchet means for diagram datasets (single, multistart, and progressive barycenters).
How the documentation is organized¶
Getting started
User guide
- User guide
- 1. Persistence diagrams of point clouds
- 2. Persistence diagrams of function data on a grid
- 3. Distances between diagrams
- 4. The manual workflow: filtration -> decomposition -> reduce -> diagram
- 5. Wasserstein barycenter / Fréchet mean
- 6. Plotting diagrams
- 7. Differentiable persistence diagrams
- 8. Kernel / image / cokernel diagrams
- 9. Zero-persistence diagrams
- What’s next
Tutorials
Topics
Reference
Citing¶
If you use Oineus in academic work, please cite the two papers listed under What’s inside. A dedicated citation page will appear here once a preferred citation is finalized.