Find structure across scales. Cocycle turns point clouds and pairwise dissimilarities into persistence diagrams: which components and loops appear, and how long they last. A general-purpose TDA library in pure Rust, with no runtime dependencies and no unsafe code.
- Rips persistence — dimension-generic ordinary persistence over prime fields, with a specialized F₂ H₀/H₁ path. Euclidean points or borrowed matrix layouts.
- Inspectable construction — exact threshold graphs, supplied weighted flag filtrations, and frozen simplicial complexes with boundary/cofacet queries.
- Supplied complexes — validated simplicial storage and a small filtered-cell trait for boundary reduction, including signed scales and unequal vertex births.
- Sparse approximation — deterministic sampling, modified edges and higher-simplex blockers, with explicit metric hypotheses and approximation provenance.
- Optional representatives — owned persistent cycle bases and query-scale dual cocycles, associated with intervals and original vertex IDs.
- Meaningful results — owned diagrams preserve multiplicity and distinguish finite deaths, essential classes, and right-censored intervals. Explicit computed dimension sets distinguish empty results from uncomputed dimensions; common diagram/context data can be shared by specialized result types.
- Useful summaries — finite lifetimes, persistence entropy in nats, and Betti curves, computed directly from a diagram.
- Diagram distances — exact bottleneck (L-infinity), W1 (L-infinity) and W2 (Euclidean) matching of complete diagrams, preserving essential multiplicity.
Quick start
Rust 1.91+ · MIT. Add Cocycle to your application's Cargo.toml:
[]
= "0.1.1"
use betti_curve;
use PointCloudView;
use RipsBuilder;
use PersistenceExt;
The square's H₁ interval is [1, sqrt(2)). Scales are edge lengths; a class
surviving an incomplete cutoff is censored, not dead. See the
user guide for cutoffs, input layouts, and result semantics.
The 0.1.1 release notes describe the latest maintenance fixes;
the initial release notes describe the supported scope,
limitations and migration from development Git revisions. See the
version policy and release procedure for
compatibility and publishing.
Explore
API reference · Guides and documentation · Filtered complexes · Rips guide · Graph construction · Mathematics · Architecture · Benchmarks · Rips comparison · Contributing · Roadmap
Contributing an algorithm? Start with the research-area navigation
and the diagram-analysis or
complex-construction walkthrough.
Run cargo run --locked --example diagram_analysis to analyze supplied intervals
without constructing a complex.
Run cargo run --locked --example complex_construction to construct a lower-star
filtration, inspect its simplices and compute persistence using existing APIs.
Read the published API reference, or build it locally
with cargo doc --no-deps --open. From a repository
checkout, run the example with
cargo run --locked --example square. Dimension-generic prime-field persistence and
explicit complex queries are demonstrated by cargo run --example rips_sphere.
Prime fields and representative bases are
demonstrated by cargo run --example rips_representatives.
Sparse Rips approximation, including metric hypotheses
and sampling provenance, is demonstrated by cargo run --example sparse_rips.
To compare two complete diagrams, run
cargo run --locked --example diagram_distances. The distance example
demonstrates all three metrics; see the matching contract
for ground costs, essential intervals and error semantics.
Work and memory depend on the input and reduction fill-in. Rips comparisons use native GUDHI and upstream Ripser C++; see the maintained Rips comparison for tested scope, correctness and performance observations. Generated measurements and logs stay outside source Git.
Issue tracker · Code and original artwork are MIT licensed.