or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

complex-construction.mdcubical-complexes.mdindex.mdpersistent-homology.mdpoint-cloud.mdrepresentations.mdwitness-complexes.md
tile.json

tessl/pypi-gudhi

Computational topology and topological data analysis library providing state-of-the-art algorithms for constructing simplicial complexes and computing persistent homology

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gudhi@3.11.x

To install, run

npx @tessl/cli install tessl/pypi-gudhi@3.11.0

index.mddocs/

GUDHI

GUDHI (Geometry Understanding in Higher Dimensions) is a comprehensive computational topology and topological data analysis library that provides state-of-the-art algorithms for constructing simplicial complexes and computing persistent homology. Built primarily in C++ with Python bindings, it offers a complete toolkit for analyzing topological features in high-dimensional data.

Package Information

  • Package Name: gudhi
  • Package Type: pypi
  • Language: Python (with C++ backends)
  • Installation: pip install gudhi

Core Imports

import gudhi

Common imports for specific functionality:

from gudhi import SimplexTree, RipsComplex, CubicalComplex
from gudhi import AlphaComplex, WeightedRipsComplex, DTMRipsComplex
from gudhi import persistence_graphical_tools

Basic Usage

import gudhi
import numpy as np

# Create a point cloud
points = np.random.random((100, 3))

# Build a Rips complex
rips_complex = gudhi.RipsComplex(points=points, max_edge_length=0.5)
simplex_tree = rips_complex.create_simplex_tree(max_dimension=2)

# Compute persistent homology
persistence = simplex_tree.persistence()

# Visualize persistence diagram
gudhi.plot_persistence_diagram(persistence)

Architecture

GUDHI's architecture centers around the SimplexTree data structure, which efficiently represents filtered simplicial complexes. The library provides multiple pathways for complex construction:

  • Complex Constructors: Classes that build complexes from data (RipsComplex, AlphaComplex, CubicalComplex, etc.)
  • SimplexTree: Central data structure for storing and manipulating complexes
  • Persistence Engine: Algorithms for computing persistent homology
  • Analysis Tools: Utilities for processing and visualizing results
  • ML Integration: Interfaces to scikit-learn and TensorFlow for topological machine learning

This design enables seamless workflows from raw data through complex construction to topological analysis and machine learning applications.

Capabilities

Complex Construction

Core classes for building simplicial and cubical complexes from various data types including point clouds, distance matrices, images, and geometric structures.

class SimplexTree:
    def __init__(self): ...
    def insert(self, simplex: list, filtration: float = 0.0): ...
    def persistence(self): ...

class RipsComplex:
    def __init__(self, points=None, distance_matrix=None, max_edge_length=float('inf'), sparse=None): ...
    def create_simplex_tree(self, max_dimension=1): ...

class CubicalComplex:
    def __init__(self, dimensions, top_dimensional_cells, periodic_dimensions=None): ...
    def persistence(self): ...

Complex Construction

Persistent Homology

Comprehensive tools for computing, analyzing, and visualizing persistent homology including persistence diagrams, barcodes, and topological summaries.

def plot_persistence_diagram(persistence, **kwargs): ...
def plot_persistence_barcode(persistence, **kwargs): ...

Persistent Homology

Point Cloud Processing

Specialized tools for analyzing point clouds including distance-to-measure computations, subsampling algorithms, and nearest neighbor queries.

class DistanceToMeasure:
    def __init__(self, k: int, q: float = 2.0): ...
    def compute_distance_to_measure(self, points): ...

def choose_n_farthest_points(points, nb_points): ...
def pick_n_random_points(points, nb_points): ...

Point Cloud Processing

Topological Representations

Machine learning interfaces for converting persistence diagrams into vector representations suitable for statistical analysis and neural networks.

class PersistenceImage:
    def __init__(self, bandwidth=1.0, weight=lambda x: 1, im_range=None, resolution=None): ...
    def fit_transform(self, X): ...

class Landscape:
    def __init__(self, num_landscapes=5, resolution=100, sample_range=[np.nan, np.nan], keep_endpoints=False): ...
    def fit_transform(self, X): ...

Topological Representations

Cubical Complexes

Specialized functionality for working with cubical complexes, particularly useful for image analysis and structured grid data.

class CubicalComplex:
    def __init__(self, dimensions, top_dimensional_cells, periodic_dimensions=None): ...
    def persistence(self): ...
    def cofaces_of_persistence_pairs(self): ...

class PeriodicCubicalComplex:
    def __init__(self, dimensions, top_dimensional_cells): ...
    def persistence(self): ...

Cubical Complexes

Witness Complexes

Classes for constructing witness complexes, which provide memory-efficient approximations of complex topological structures using landmark points.

class WitnessComplex:
    def __init__(self, landmarks, witnesses): ...
    def create_simplex_tree(self, max_alpha_square, limit_dimension): ...

class EuclideanWitnessComplex:
    def __init__(self, landmarks, witnesses): ...
    def create_simplex_tree(self, max_alpha_square, limit_dimension): ...

Witness Complexes

Wasserstein Distances and Barycenters

Computing Wasserstein distances between persistence diagrams and optimal transport-based algorithms for topological data analysis.

def wasserstein_distance(diagram1, diagram2, order=1, internal_p=2): ...
def bottleneck_distance(diagram1, diagram2, e=0): ...

class WassersteinBarycenter:
    def __init__(self, diagrams, weights=None): ...
    def compute_barycenter(self): ...

Machine Learning Integration

Scikit-learn compatible transformers and TensorFlow layers for topological machine learning workflows.

# From gudhi.sklearn module
class CubicalPersistence:
    def __init__(self, dimensions=None, persistence_dim_max=True): ...
    def fit_transform(self, X): ...

class RipsPersistence:
    def __init__(self, max_edge_length=float('inf'), max_dimension=1): ...
    def fit_transform(self, X): ...

# From gudhi.tensorflow module 
class RipsLayer:
    def __init__(self, maximum_edge_length=float('inf'), homology_dimensions=[0, 1]): ...

class CubicalLayer:
    def __init__(self, dimensions, homology_dimensions=[0, 1]): ...

Clustering and Density-based Analysis

Advanced clustering algorithms including TOMATO (Topological Mode Analysis Tool) for topological data analysis.

# From gudhi.clustering module
class Tomato:
    def __init__(self, density_type="manual", k=10): ...
    def fit(self, X): ...
    def n_clusters_: int
    def cluster_centers_: list

Data Generation and Utilities

Utilities for generating synthetic point clouds and datasets for topological data analysis experiments.

# From gudhi.datasets module
def sphere(n_samples=100, ambient_dim=3, radius=1, sample="random"): ...
def torus(n_samples=100, dim=2): ...
def two_spheres(n_samples=100, ambient_dim=3, radius=1): ...

# From gudhi.datasets.remote module
def fetch_bunny(): ...
def fetch_spiral_2d(): ...

Types

# Persistence pairs format
PersistencePair = tuple[int, tuple[float, float]]  # (dimension, (birth, death))

# Simplex representation
Simplex = list[int]  # List of vertex indices

# Filtration value type
Filtration = float

# Point cloud data
Points = list[list[float]]  # List of points in d-dimensional space
DistanceMatrix = list[list[float]]  # Symmetric distance matrix