dire_rapids.atlas_cpu module

CPU implementation of atlas topology computation.

Uses sklearn for kNN, numpy for arrays, and scipy sparse matrices.

dire_rapids.atlas_cpu.compute_h0_h1_atlas_cpu(data, k_neighbors=20, density_threshold=0.8, overlap_factor=1.5, return_distances=False)[source]

CPU implementation of atlas-based H0/H1 computation.

Build dense local triangulations around each point, then merge consistently.

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

  • return_distances (bool) – If True, also return edge-to-distance mapping

Returns:

tuple

Return type:

(h0_diagram, h1_diagram) or (h0_diagram, h1_diagram, edge_distances)

Overview

CPU implementation of local kNN atlas topology computation using Hodge Laplacian.

Status: ⚠️ Under active development - API may change

Key Functions

  • compute_h0_h1_atlas_cpu: Main entry point for computing H0/H1 Betti curves

  • compute_betti_curve_from_dgm: Convert persistence diagram to Betti curve

  • compute_h0_h1_hodge: Hodge Laplacian-based H0/H1 computation

Algorithm

  1. Construct kNN graph for each point’s local neighborhood

  2. Use combinatorial Nystroem approximation via Hodge Laplacian

  3. Extract H0/H1 persistence diagrams from eigenvalue spectrum

  4. Aggregate into global Betti curves

Examples

from dire_rapids.atlas_cpu import compute_h0_h1_atlas_cpu
import numpy as np

# Generate sample data
X = np.random.randn(1000, 50).astype(np.float32)

# Compute H0/H1 Betti curves
betti_curves, stats = compute_h0_h1_atlas_cpu(
    X,
    n_neighbors=30,
    n_radii=50
)

print(f"Betti curves shape: {betti_curves.shape}")  # (n_radii, 2)
print(f"H0 at first radius: {betti_curves[0, 0]}")
print(f"H1 at first radius: {betti_curves[0, 1]}")
print(f"Radii: {stats['radii'][:5]}")

See Also

  • dire_rapids.atlas_gpu: GPU-accelerated version using cuVS

  • tests/test_atlas_approach.py: Comprehensive usage examples

  • tests/test_atlas_scaling.py: Scaling benchmarks