cocycle 0.1.1

Topological data analysis in pure Rust
Documentation
  • Coverage
  • 100%
    227 out of 227 items documented8 out of 24 items with examples
  • Size
  • Source code size: 1.1 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 6.4 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 4s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Aequiludium/cocycle-rs
    2 2 17
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • huangbogeng

Cocycle — topology, computed in Rust

CI Rust 1.91+ License: MIT

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.

A square's Rips filtration: points, a loop at edge length 1, and filled triangles at sqrt(2).

Quick start

Rust 1.91+ · MIT. Add Cocycle to your application's Cargo.toml:

[dependencies]
cocycle = "0.1.1"
use cocycle::descriptors::betti_curve;
use cocycle::geometry::PointCloudView;
use cocycle::filtration::RipsBuilder;
use cocycle::persistence::PersistenceExt;

fn main() -> cocycle::Result<()> {
    let square = [0., 0., 1., 0., 1., 1., 0., 1.];
    let points = PointCloudView::new(&square, 4, 2)?;
    let result = RipsBuilder::from_points(points).persistence().compute()?;
    let diagram = result.diagram();
    assert_eq!(betti_curve(diagram, 1, &[0., 1., 2.])?, [0, 1, 0]);
    Ok(())
}

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.