tda 0.4.0

TDA does one computational job: Vietoris–Rips persistent homology, quickly. It accepts point clouds, distance matrices, and sparse distance graphs and runs a packed, Ripser-style¹ reduction in Rust. Use the result directly as a persistence diagram, or bring a selected class back to the data through topological coordinates.

Limits: up to 16,777,215 points and homology dimension 7. Internally the engine selects a packed 128-bit or 256-bit simplex layout. Deep dimensions and large point counts are most practical with quotient, which trades exactness for a log(3)-interleaved approximation at a fraction of the cost.²

Installation

TDA requires Python 3.11 or newer. Pre-built wheels for common macOS, Windows, and Linux platforms are published on PyPI:

pip install tda

git clone https://github.com/antonio-leitao/topological-data-analysis.git
cd topological-data-analysis

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install maturin numpy

cd crates/python
maturin develop --release

Quick start

import numpy as np
import tda

points = np.random.rand(200, 3)
barcode = tda.persistent_homology(points, max_dim=2)

# barcode[d] contains the [birth, death] intervals in dimension d.
print(barcode[1])

For a guided introduction, see the runnable notebooks:

• persistent_homology.ipynb covers circles, spheres, distance matrices, and quotient preprocessing.
• coordinates.ipynb shows circular, toroidal, and fitted coordinates.

Inputs

Set distance_matrix=True for a dense precomputed distance matrix:

barcode = tda.persistent_homology(
    distances,
    max_dim=1,
    distance_matrix=True,
)

Sparse matrices are treated as distance graphs. Entries are edges and missing pairs have infinite distance:

import scipy.sparse as sp

graph = sp.coo_matrix(
    ([1.0, 1.0, 1.0, 1.0], ([0, 1, 2, 3], [1, 2, 3, 0])),
    shape=(4, 4),
)
barcode = tda.persistent_homology(graph, max_dim=1)

Arrays are read in place. C-contiguous float32 or float64 input and the int32/int64 index and float32/float64 value arrays of CSR, CSC, and COO matrices reach Rust without a copy; other layouts and sparse formats are copied once. The GIL is released while persistence runs. Coordinates must be finite and distances non-negative, otherwise a ValueError names the offending entry.

Parameters

persistent_homology and filtration_size share these options:

With collapse="auto", collapse is skipped for max_dim=0, runs in full from max_dim=2 up unless the longest edges show there is nothing to remove, and at max_dim=1 stops once it costs more than it saves. The barcode is the same either way.

The result is a list of length max_dim + 1. barcode[d] is an array of [birth, death] intervals; inf marks an essential feature.

Scaling persistent homology

The filtration is normally the expensive object. TDA provides three composable ways to reduce it before persistence:

For the strongest exact reduction, combine peel and collapse. Peel is based on the established dominated-vertex/strong-collapse idea; to our knowledge, this filtration-peeling implementation is currently specific to TDA. For much larger problems, quotient produces a near-linear skeleton and can still be combined with the exact steps. The canonical order is peel → quotient → collapse.

Every exact step reads the whole graph below the truncation radius, which for a point cloud is most of its pairs, so exact persistence needs memory quadratic in the number of points. The quotient does not. With quotient=True and peel=False, a point cloud above about 26,700 points never stores its pairs: they are generated in distance bands and consumed in order, and the result is identical to building them. Memory then follows the skeleton, which is close to linear in the number of points. Peel needs the whole graph, so with peel=True the pairs are stored as before.

Benchmark

Left: time to compute persistence up to H_2 on samples of the Stanford dragon, up to the full 435,545-point scan. Right: time to compute persistence up to H_d on 500 points sampled from the d-sphere. Both run on one thread. The setup and raw results are in bench/.

One run of the summary example with max_dim=2 and parallel=false:

cargo run --release -p tda_core --example summary

Timings depend on hardware; filtration size more directly shows the work that reaches reduction:

On dragon_2000, quotient reduces 546.8 million simplices to about 30.4 thousand and cuts this run from 22.43 seconds to 149.59 milliseconds. That is the intended quotient use case: a controlled approximation when the full filtration is the bottleneck.

Using persistence

Persistence diagrams

For many applications, the barcode returned by persistent_homology is the final summary: long-lived intervals identify features that persist across scales.

Coordinates

Coordinates bring selected persistent cohomology classes back to the original observations. One H¹ class assigns every point an angle on S¹:⁴

result = tda.coords.circular(points)
angles = result.coordinates  # (n, 1), values in [0, 2π)

Asking for several classes gives one column each. Classes that are alive at a common scale are jointly decorrelated by lattice reduction into a single map to a torus; result.groups reports which columns were decorrelated together:⁵

two_circles = np.concatenate([points, points + [4.0, 0.0]])

result = tda.coords.circular(two_circles, n_classes=2)
result.coordinates  # (n, 2)
result.groups       # [[0, 1]] — both columns in one toroidal block

Classes that are not co-alive stay independent and come back as singleton groups ([[0], [1]]), which are plain circular coordinates.

These constructions are adapted from DREiMAC, the reference implementation.⁶ See the coordinates notebook for the geometric intuition, class selection, quotient coordinates, and fitted maps for new data.

The integer lift of the selected cocycle is checked for closedness. DREiMAC can repair a failed lift with mixed-integer optimization; TDA instead returns an error and leaves the choice of another class, scale, or prime to the user.⁷

Additional APIs

Use filtration_size to inspect the truncated filtration under the same preprocessing options without computing persistence:

size = tda.filtration_size(points, max_dim=2, quotient=True)

A fitted circular_map transforms new point-cloud observations without recomputing persistence. See the coordinates notebook for examples.

Rust

The Rust crate is published as tda_core:

[dependencies]
tda_core = "0.4"

use tda_core::{persistent_homology, Error};

fn main() -> Result<(), Error> {
    let points = vec![
        0.0, 0.0,
        1.0, 0.0,
        0.0, 1.0,
        1.0, 1.0,
    ];

    let barcode = persistent_homology(&points, 4, 1)?;
    println!("{:?}", barcode.intervals);
    Ok(())
}

Distance matrices, sparse COO and CSR/CSC distance graphs, thresholds, and preprocessing options are available through Config and the corresponding _with, _sparse, and _csr functions. Every entry point reads f32 or f64 values and u32, u64, i32, or i64 indices in place. Invalid input returns tda_core::Error.

References

License

TDA is distributed under the MIT License.