tessl/pypi-gudhi
Computational topology and topological data analysis library providing state-of-the-art algorithms for constructing simplicial complexes and computing persistent homology
—
Pending
complex-construction.mddocs/
Complex Construction
Core classes for building simplicial and cubical complexes from various data types. These classes form the foundation of GUDHI's topological analysis capabilities, providing efficient construction of filtered complexes from point clouds, distance matrices, images, and geometric structures.
Capabilities
SimplexTree
The fundamental data structure for representing filtered simplicial complexes. SimplexTree efficiently stores simplices with their filtration values and provides methods for complex manipulation and persistence computation.
class SimplexTree:
def __init__(self):
"""Initialize an empty simplex tree."""
def insert(self, simplex: list, filtration: float = 0.0):
"""
Insert a simplex with given filtration value.
Parameters:
- simplex: List of vertex indices forming the simplex
- filtration: Filtration value for the simplex
Returns:
bool: True if simplex was inserted
"""
def find(self, simplex: list):
"""
Find a simplex in the tree.
Parameters:
- simplex: List of vertex indices
Returns:
tuple: (found, filtration) where found is bool and filtration is float
"""
def remove_maximal_simplex(self, simplex: list):
"""
Remove a maximal simplex and all its cofaces.
Parameters:
- simplex: List of vertex indices
Returns:
bool: True if simplex was removed
"""
def expansion(self, max_dim: int):
"""
Expand the complex to maximal dimension.
Parameters:
- max_dim: Maximum dimension for expansion
"""
def persistence(self, homology_coeff_field: int = 11, min_persistence: float = 0.0):
"""
Compute persistent homology.
Parameters:
- homology_coeff_field: Coefficient field for homology computation
- min_persistence: Minimum persistence value to return
Returns:
list: Persistence pairs as (dimension, (birth, death)) tuples
"""
def persistence_pairs(self):
"""
Get persistence pairs with simplex representatives.
Returns:
list: Persistence pairs with birth/death simplex representatives
"""
def betti_numbers(self):
"""
Compute Betti numbers.
Returns:
list: Betti numbers for each dimension
"""
def num_vertices(self):
"""Get number of vertices."""
def num_simplices(self):
"""Get total number of simplices."""
def dimension(self):
"""Get dimension of the complex."""
def filtration(self, simplex: list):
"""Get filtration value of a simplex."""
def assign_filtration(self, simplex: list, filtration: float):
"""Assign filtration value to a simplex."""
def make_filtration_non_decreasing(self):
"""Ensure filtration values are non-decreasing."""
def reset_filtration(self, filtration: float, dimension: int):
"""Reset filtration values for simplices of given dimension."""RipsComplex
Constructs Rips complexes (also known as Vietoris-Rips complexes) from point clouds or distance matrices. The Rips complex includes all simplices whose pairwise distances are within a threshold.
class RipsComplex:
def __init__(self, points=None, distance_matrix=None, max_edge_length=float('inf'), sparse=None):
"""
Initialize Rips complex constructor.
Parameters:
- points: List of points in d-dimensional space
- distance_matrix: Symmetric distance matrix (alternative to points)
- max_edge_length: Maximum edge length threshold
- sparse: Sparsification parameter (0 < sparse <= 1)
"""
def create_simplex_tree(self, max_dimension: int = 1):
"""
Create simplex tree from the Rips complex.
Parameters:
- max_dimension: Maximum dimension of simplices to include
Returns:
SimplexTree: Filtered simplex tree
"""
class WeightedRipsComplex:
def __init__(self, distance_matrix, weights=None, max_filtration=float('inf')):
"""
Initialize weighted Rips complex constructor.
Parameters:
- distance_matrix: Distance matrix between points
- weights: Weight for each vertex (optional)
- max_filtration: Maximum filtration value
"""
def create_simplex_tree(self, max_dimension: int):
"""
Create simplex tree from the weighted Rips complex.
Parameters:
- max_dimension: Maximum dimension of the complex
Returns:
SimplexTree: The constructed simplex tree
"""
class DTMRipsComplex:
def __init__(self, points=None, distance_matrix=None, k=1, q=2, max_filtration=float('inf')):
"""
Initialize DTM Rips complex constructor using Distance-to-Measure.
Parameters:
- points: Array of points in d-dimensional space
- distance_matrix: Full distance matrix (alternative to points)
- k: Number of neighbors for DTM computation
- q: Order used to compute distance to measure
- max_filtration: Maximum filtration value
"""
def create_simplex_tree(self, max_dimension: int):
"""
Create simplex tree from the DTM Rips complex.
Parameters:
- max_dimension: Maximum dimension of the complex
Returns:
SimplexTree: The constructed simplex tree
"""AlphaComplex
Constructs Alpha complexes, which are subcomplexes of the Delaunay triangulation. Alpha complexes provide a more geometrically natural filtration than Rips complexes for point clouds in Euclidean space.
class AlphaComplex:
def __init__(self, points, precision: str = 'safe'):
"""
Initialize Alpha complex constructor.
Parameters:
- points: List of points in d-dimensional space
- precision: Precision mode ('safe', 'exact', 'fast')
"""
def create_simplex_tree(self):
"""
Create simplex tree from the Alpha complex.
Returns:
SimplexTree: Filtered simplex tree with alpha filtration
"""DelaunayComplex
Constructs Delaunay triangulations, providing the foundational geometric structure for Alpha complexes.
class DelaunayComplex:
def __init__(self, points):
"""
Initialize Delaunay complex constructor.
Parameters:
- points: List of points in d-dimensional space
"""
def create_simplex_tree(self):
"""
Create simplex tree from the Delaunay triangulation.
Returns:
SimplexTree: Unfiltered simplex tree
"""TangentialComplex
Constructs tangential complexes for reconstructing manifolds from point clouds. Useful for manifold learning and surface reconstruction.
class TangentialComplex:
def __init__(self, points, intrinsic_dim: int):
"""
Initialize tangential complex constructor.
Parameters:
- points: List of points sampled from a manifold
- intrinsic_dim: Intrinsic dimension of the manifold
"""
def compute_tangential_complex(self):
"""Compute the tangential complex."""
def create_simplex_tree(self):
"""
Create simplex tree from the tangential complex.
Returns:
SimplexTree: Filtered simplex tree
"""NerveGIC
Constructs nerve complexes and graph-induced complexes, implementing mapper-like algorithms for topological data analysis.
class NerveGIC:
def __init__(self):
"""Initialize nerve of graph-induced complex constructor."""
def set_function(self, function):
"""
Set the filter function for the complex.
Parameters:
- function: Function values for each point
"""
def set_cover(self, cover):
"""
Set the cover parameters.
Parameters:
- cover: Cover specification (intervals, overlap, etc.)
"""
def compute_nerve(self):
"""Compute the nerve of the cover."""
def create_simplex_tree(self):
"""
Create simplex tree from the nerve complex.
Returns:
SimplexTree: Nerve complex as simplex tree
"""Usage Examples
Basic SimplexTree Construction
import gudhi
# Create empty simplex tree
st = gudhi.SimplexTree()
# Insert simplices manually
st.insert([0, 1], filtration=0.5)
st.insert([1, 2], filtration=0.6)
st.insert([0, 2], filtration=0.7)
st.insert([0, 1, 2], filtration=0.8)
# Compute persistence
persistence = st.persistence()
print(f"Persistence pairs: {persistence}")Rips Complex from Point Cloud
import gudhi
import numpy as np
# Generate random point cloud
points = np.random.random((50, 3))
# Build Rips complex
rips = gudhi.RipsComplex(points=points, max_edge_length=0.5)
simplex_tree = rips.create_simplex_tree(max_dimension=2)
# Compute persistent homology
persistence = simplex_tree.persistence()Alpha Complex Construction
import gudhi
import numpy as np
# Generate point cloud
points = np.random.random((30, 2))
# Build Alpha complex
alpha = gudhi.AlphaComplex(points=points)
simplex_tree = alpha.create_simplex_tree()
# Compute persistence
persistence = simplex_tree.persistence()Install with Tessl CLI
npx tessl i tessl/pypi-gudhi