dire_rapids.betti_curve module

Betti curve computation using filtered edge addition.

Computes Betti numbers (β₀, β₁) at multiple filtration thresholds by: 1. Building full atlas complex once with kNN graph 2. Recording all edge distances 3. Progressively adding edges by distance threshold 4. Recomputing Laplacians and Betti numbers at each step

Contains both CPU and GPU implementations with automatic backend selection.

class dire_rapids.betti_curve.UnionFind(n)

Bases: object

Disjoint-set with path compression and union by rank.

__init__(n)

find(x)

union(x, y)

dire_rapids.betti_curve.compute_betti_curve_cpu(data, k_neighbors=20, density_threshold=0.8, overlap_factor=1.5, n_steps=50)

CPU implementation of filtered Betti curve computation.

Parameters:

• data (array-like) – Point cloud data (n_samples, n_features)

• k_neighbors (int) – Size of local neighborhood

• density_threshold (float) – Percentile threshold for edge inclusion (0-1)

• overlap_factor (float) – Factor for expanding local neighborhoods

• n_steps (int) – Number of filtration steps

Returns:

• dict ({) – ‘filtration_values’: array of filtration thresholds, ‘beta_0’: array of H0 Betti numbers, ‘beta_1’: array of H1 Betti numbers, ‘n_edges_active’: array of active edge counts, ‘n_triangles_active’: array of active triangle counts

• }

dire_rapids.betti_curve.compute_betti_curve_fast(data, k_neighbors=20, density_threshold=0.8, overlap_factor=1.5, n_steps=50)

Fast Betti curve computation using union-find (β₀) and matrix rank (β₁).

Instead of computing eigenvalues of Hodge Laplacians via eigsh (the bottleneck in compute_betti_curve_cpu), this uses algebraic topology identities:

β₀ = connected components via union-find, O(E·α(E)) β₁ = E - rank(B1) - rank(B2) via Hodge decomposition rank(B1) = V - β₀ (graph theory, free) rank(B2) via GPU-accelerated SVD (torch.linalg.matrix_rank)

Parameters:

• data (array-like) – Point cloud data (n_samples, n_features)

• k_neighbors (int) – Size of local neighborhood

• density_threshold (float) – Percentile threshold for edge inclusion (0-1)

• overlap_factor (float) – Factor for expanding local neighborhoods

• n_steps (int) – Number of filtration steps

Returns:

dict

Return type:

Same structure as compute_betti_curve_cpu

dire_rapids.betti_curve.compute_betti_curve_gpu(data, k_neighbors=20, density_threshold=0.8, overlap_factor=1.5, n_steps=50)

GPU implementation of filtered Betti curve computation.

Uses GPU kNN (cuVS/cuML) for graph construction and rank-based Betti computation (union-find for β₀, GPU SVD for β₁). Atlas building runs on CPU (set operations are faster there).

Parameters:

• data (array-like) – Point cloud data (n_samples, n_features)

• k_neighbors (int) – Size of local neighborhood

• density_threshold (float) – Percentile threshold for edge inclusion (0-1)

• overlap_factor (float) – Factor for expanding local neighborhoods

• n_steps (int) – Number of filtration steps

Returns:

dict

Return type:

Same structure as compute_betti_curve_cpu

dire_rapids.betti_curve.compute_betti_curve(data, k_neighbors=20, density_threshold=0.8, overlap_factor=1.5, n_steps=50, use_gpu=True)

Compute filtered Betti curve (backend selector).

Automatically selects GPU or CPU implementation based on availability and use_gpu parameter.

Parameters:

• data (array-like) – Point cloud data (n_samples, n_features)

• k_neighbors (int) – Size of local neighborhood

• density_threshold (float) – Percentile threshold for edge inclusion (0-1)

• overlap_factor (float) – Factor for expanding local neighborhoods

• n_steps (int) – Number of filtration steps

• use_gpu (bool) – Whether to use GPU acceleration (if available)

Returns:

• dict ({) – ‘filtration_values’: array of filtration thresholds, ‘beta_0’: array of H0 Betti numbers, ‘beta_1’: array of H1 Betti numbers, ‘n_edges_active’: array of active edge counts, ‘n_triangles_active’: array of active triangle counts

• }