0
# GUDHI
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: gudhi
7
- **Package Type**: pypi
8
- **Language**: Python (with C++ backends)
9
- **Installation**: `pip install gudhi`
10

11
## Core Imports
12

13
```python
14
import gudhi
15
```
16

17
Common imports for specific functionality:
18

19
```python
20
from gudhi import SimplexTree, RipsComplex, CubicalComplex
21
from gudhi import AlphaComplex, WeightedRipsComplex, DTMRipsComplex
22
from gudhi import persistence_graphical_tools
23
```
24

25
## Basic Usage
26

27
```python
28
import gudhi
29
import numpy as np
30

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

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

38
# Compute persistent homology
39
persistence = simplex_tree.persistence()
40

41
# Visualize persistence diagram
42
gudhi.plot_persistence_diagram(persistence)
43
```
44

45
## Architecture
46

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

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

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

57
## Capabilities
58

59
### Complex Construction
60

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

63
```python { .api }
64
class SimplexTree:
65
    def __init__(self): ...
66
    def insert(self, simplex: list, filtration: float = 0.0): ...
67
    def persistence(self): ...
68

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

73
class CubicalComplex:
74
    def __init__(self, dimensions, top_dimensional_cells, periodic_dimensions=None): ...
75
    def persistence(self): ...
76
```
77

78
[Complex Construction](./complex-construction.md)
79

80
### Persistent Homology
81

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

84
```python { .api }
85
def plot_persistence_diagram(persistence, **kwargs): ...
86
def plot_persistence_barcode(persistence, **kwargs): ...
87
```
88

89
[Persistent Homology](./persistent-homology.md)
90

91
### Point Cloud Processing
92

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

95
```python { .api }
96
class DistanceToMeasure:
97
    def __init__(self, k: int, q: float = 2.0): ...
98
    def compute_distance_to_measure(self, points): ...
99

100
def choose_n_farthest_points(points, nb_points): ...
101
def pick_n_random_points(points, nb_points): ...
102
```
103

104
[Point Cloud Processing](./point-cloud.md)
105

106
### Topological Representations
107

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

110
```python { .api }
111
class PersistenceImage:
112
    def __init__(self, bandwidth=1.0, weight=lambda x: 1, im_range=None, resolution=None): ...
113
    def fit_transform(self, X): ...
114

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

120
[Topological Representations](./representations.md)
121

122
### Cubical Complexes
123

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

126
```python { .api }
127
class CubicalComplex:
128
    def __init__(self, dimensions, top_dimensional_cells, periodic_dimensions=None): ...
129
    def persistence(self): ...
130
    def cofaces_of_persistence_pairs(self): ...
131

132
class PeriodicCubicalComplex:
133
    def __init__(self, dimensions, top_dimensional_cells): ...
134
    def persistence(self): ...
135
```
136

137
[Cubical Complexes](./cubical-complexes.md)
138

139
### Witness Complexes
140

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

143
```python { .api }
144
class WitnessComplex:
145
    def __init__(self, landmarks, witnesses): ...
146
    def create_simplex_tree(self, max_alpha_square, limit_dimension): ...
147

148
class EuclideanWitnessComplex:
149
    def __init__(self, landmarks, witnesses): ...
150
    def create_simplex_tree(self, max_alpha_square, limit_dimension): ...
151
```
152

153
[Witness Complexes](./witness-complexes.md)
154

155
### Wasserstein Distances and Barycenters
156

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

159
```python { .api }
160
def wasserstein_distance(diagram1, diagram2, order=1, internal_p=2): ...
161
def bottleneck_distance(diagram1, diagram2, e=0): ...
162

163
class WassersteinBarycenter:
164
    def __init__(self, diagrams, weights=None): ...
165
    def compute_barycenter(self): ...
166
```
167

168
### Machine Learning Integration
169

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

172
```python { .api }
173
# From gudhi.sklearn module
174
class CubicalPersistence:
175
    def __init__(self, dimensions=None, persistence_dim_max=True): ...
176
    def fit_transform(self, X): ...
177

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

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

186
class CubicalLayer:
187
    def __init__(self, dimensions, homology_dimensions=[0, 1]): ...
188
```
189

190
### Clustering and Density-based Analysis
191

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

194
```python { .api }
195
# From gudhi.clustering module
196
class Tomato:
197
    def __init__(self, density_type="manual", k=10): ...
198
    def fit(self, X): ...
199
    def n_clusters_: int
200
    def cluster_centers_: list
201
```
202

203
### Data Generation and Utilities
204

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

207
```python { .api }
208
# From gudhi.datasets module
209
def sphere(n_samples=100, ambient_dim=3, radius=1, sample="random"): ...
210
def torus(n_samples=100, dim=2): ...
211
def two_spheres(n_samples=100, ambient_dim=3, radius=1): ...
212

213
# From gudhi.datasets.remote module
214
def fetch_bunny(): ...
215
def fetch_spiral_2d(): ...
216
```
217

218
## Types
219

220
```python { .api }
221
# Persistence pairs format
222
PersistencePair = tuple[int, tuple[float, float]]  # (dimension, (birth, death))
223

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

227
# Filtration value type
228
Filtration = float
229

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