TopoFlow

A Toolkit for Persistent Homology Computation and 3D Visualization

Overview

TopoFlow is a Python toolkit for computing Vietoris-Rips persistent homology from point cloud data and rendering the results as animated 3D visualizations. It provides implementations of core TDA (Topological Data Analysis) operations alongside interactive graphics capabilities for exploring topological features across filtration scales.

Installation

pip install -e .

Dependencies: NumPy, SciPy, Matplotlib, scikit-learn (optional), Ripser (optional), GUDHI (optional)

Scientific Background

Persistent Homology

Persistent homology is a method in topological data analysis that studies the multi-scale topological structure of data. Given a point cloud sampled from a topological space, we construct a nested sequence of simplicial complexes (a filtration) and track how topological features—connected components (H₀), loops (H₁), voids (H₂)—appear and disappear across scales.

Vietoris-Rips Complex

Given a point cloud $P \subset \mathbb{R}^d$ and a scale parameter $\varepsilon > 0$, the Vietoris-Rips complex $VR_\varepsilon(P)$ is the abstract simplicial complex where a subset ${p_0, \ldots, p_k} \subseteq P$ forms a $k$-simplex if and only if $\text{dist}(p_i, p_j) \leq \varepsilon$ for all $i, j$.

As $\varepsilon$ increases from 0 to $\infty$:

• H₀ features (connected components): merge at the distances connecting points
• H₁ features (loops/cycles): form when edges create triangular cycles
• H₂ features (voids): form when tetrahedra enclose empty regions

Persistence Diagram and Barcode

Each topological feature has a birth scale (when it appears) and a death scale (when it is filled in). The persistence of a feature is $\text{death} - \text{birth}$—long-lived features are more robust, while short-lived features are often noise.

• Persistence barcode: each feature as an interval [birth, death)
• Persistence diagram: points (birth, death) in the plane; features on the diagonal have zero persistence

Betti Numbers

The Betti numbers $\beta_k$ count the number of independent $k$-dimensional topological features:

• $\beta_0$: number of connected components
• $\beta_1$: number of independent loops/cycles
• $\beta_2$: number of enclosed voids

Persistence Landscape

The persistence landscape, introduced by Bubenik (2015), is a piecewise-linear function representation of persistence that enables statistical analysis. The $k$-th landscape function $\lambda_k(t)$ captures the $k$-th most persistent feature at each filtration value.

Algorithm

TopoFlow computes persistent homology via:

1. Distance matrix computation: $O(n^2)$ pairwise distances
2. Filtration construction: Sort all edge pairs by distance
3. Homology computation: Uses Ripser (default), GUDHI, or a union-find fallback
4. Visualization rendering: 3D bar charts, surface plots, and animated GIFs

Usage

Command-Line Interface

# Compute persistent homology and render barcode as 3D chart
topoflow render --input points.csv --output barcode.png --type barcode

# Run demo with torus point cloud
topoflow demo --output demo.gif

# Generate random point cloud and visualize VR complex
topoflow random --n-points 100 --distribution torus --type complex --output vr_complex.png

# Compute and display topological summary
topoflow summary --input points.csv

# Generate persistence landscape animation
topoflow landscape --input points.csv --output landscape.gif

Supported Distributions

Distribution	Description
sphere	Uniform random points on unit sphere surface
torus	Random points on torus (R=2.0, r=0.8)
cube	Uniform random points in [-1,1]³
circle	Uniform random points on unit circle

Visualization Types

• barcode: 3D bar chart of persistence intervals by homology dimension
• surface: 3D surface rendering of persistence landscape
• complex: 3D VR complex mesh with edges colored by filtration value
• betti: 2D Betti curves (count vs. filtration value)
• diagram: Standard persistence diagram (birth vs. death)
• collapse: Animated GIF showing VR complex building across filtration
• landscape: Animated GIF of persistence landscape construction

Python API

from topoflow.topology import (
    generate_random_point_cloud,
    read_point_cloud,
    compute_persistent_homology,
    compute_betti_curves,
    compute_persistence_landscape,
    get_topological_summary,
)
from topoflow.render import create_persistence_diagram, create_3d_barcode_chart

# Load or generate point cloud
points = read_point_cloud("data.csv")
# or: points = generate_random_point_cloud(n_points=100, distribution="torus")

# Compute persistent homology
result = compute_persistent_homology(points, max_dim=1, max_edge_length=2.0)

# Access results
dgms = result["dgms"]           # List of persistence diagrams per dimension
betti_nums = result["betti_numbers"]  # [β₀, β₁, ...] at max filtration

# Compute derived quantities
betti_curves = compute_betti_curves(result)
landscape = compute_persistence_landscape(result)

# Get complete topological summary
summary = get_topological_summary(points)
# Contains: n_points, betti_numbers, barcodes, betti_curves, 
#           persistence_landscape, total_persistence

# Visualize
fig = create_persistence_diagram(summary["barcodes"])
fig.savefig("diagram.png")

Output Formats

Format	Description
PNG	Static visualizations (barcode chart, diagram, curves)
GIF	Animated visualizations (collapse, landscape, demo)

Implementation Notes

• Primary TDA backend: Ripser (via ripser Python package)—fast C++ implementation
• Fallback: Custom union-find algorithm for H₀ and triangle-based H₁ approximation
• Optional backend: GUDHI library support via library="gudhi" argument
• Visualization: Matplotlib with mpl_toolkits.mplot3d for 3D rendering

References

• Bubenik, P. (2015). Statistical topological data analysis using persistence landscapes. JMLR, 16(1), 77–102.
• Edelsbrunner, H., & Harer, J. (2008). Persistent homology—a survey. Surveys on Discrete and Computational Geometry, 453, 257–282.
• Edelsbrunner, H., Letscher, D., & Zomorodian, A. (2002). Topological persistence and simplification. Discrete & Computational Geometry, 28(4), 511–533.

License

MIT License - Copyright (c) 2026 Teerth Sharma