0
# Complex Construction
1
2
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.
3
4
## Capabilities
5
6
### SimplexTree
7
8
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.
9
10
```python { .api }
11
class SimplexTree:
12
def __init__(self):
13
"""Initialize an empty simplex tree."""
14
15
def insert(self, simplex: list, filtration: float = 0.0):
16
"""
17
Insert a simplex with given filtration value.
18
19
Parameters:
20
- simplex: List of vertex indices forming the simplex
21
- filtration: Filtration value for the simplex
22
23
Returns:
24
bool: True if simplex was inserted
25
"""
26
27
def find(self, simplex: list):
28
"""
29
Find a simplex in the tree.
30
31
Parameters:
32
- simplex: List of vertex indices
33
34
Returns:
35
tuple: (found, filtration) where found is bool and filtration is float
36
"""
37
38
def remove_maximal_simplex(self, simplex: list):
39
"""
40
Remove a maximal simplex and all its cofaces.
41
42
Parameters:
43
- simplex: List of vertex indices
44
45
Returns:
46
bool: True if simplex was removed
47
"""
48
49
def expansion(self, max_dim: int):
50
"""
51
Expand the complex to maximal dimension.
52
53
Parameters:
54
- max_dim: Maximum dimension for expansion
55
"""
56
57
def persistence(self, homology_coeff_field: int = 11, min_persistence: float = 0.0):
58
"""
59
Compute persistent homology.
60
61
Parameters:
62
- homology_coeff_field: Coefficient field for homology computation
63
- min_persistence: Minimum persistence value to return
64
65
Returns:
66
list: Persistence pairs as (dimension, (birth, death)) tuples
67
"""
68
69
def persistence_pairs(self):
70
"""
71
Get persistence pairs with simplex representatives.
72
73
Returns:
74
list: Persistence pairs with birth/death simplex representatives
75
"""
76
77
def betti_numbers(self):
78
"""
79
Compute Betti numbers.
80
81
Returns:
82
list: Betti numbers for each dimension
83
"""
84
85
def num_vertices(self):
86
"""Get number of vertices."""
87
88
def num_simplices(self):
89
"""Get total number of simplices."""
90
91
def dimension(self):
92
"""Get dimension of the complex."""
93
94
def filtration(self, simplex: list):
95
"""Get filtration value of a simplex."""
96
97
def assign_filtration(self, simplex: list, filtration: float):
98
"""Assign filtration value to a simplex."""
99
100
def make_filtration_non_decreasing(self):
101
"""Ensure filtration values are non-decreasing."""
102
103
def reset_filtration(self, filtration: float, dimension: int):
104
"""Reset filtration values for simplices of given dimension."""
105
```
106
107
### RipsComplex
108
109
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.
110
111
```python { .api }
112
class RipsComplex:
113
def __init__(self, points=None, distance_matrix=None, max_edge_length=float('inf'), sparse=None):
114
"""
115
Initialize Rips complex constructor.
116
117
Parameters:
118
- points: List of points in d-dimensional space
119
- distance_matrix: Symmetric distance matrix (alternative to points)
120
- max_edge_length: Maximum edge length threshold
121
- sparse: Sparsification parameter (0 < sparse <= 1)
122
"""
123
124
def create_simplex_tree(self, max_dimension: int = 1):
125
"""
126
Create simplex tree from the Rips complex.
127
128
Parameters:
129
- max_dimension: Maximum dimension of simplices to include
130
131
Returns:
132
SimplexTree: Filtered simplex tree
133
"""
134
135
class WeightedRipsComplex:
136
def __init__(self, distance_matrix, weights=None, max_filtration=float('inf')):
137
"""
138
Initialize weighted Rips complex constructor.
139
140
Parameters:
141
- distance_matrix: Distance matrix between points
142
- weights: Weight for each vertex (optional)
143
- max_filtration: Maximum filtration value
144
"""
145
146
def create_simplex_tree(self, max_dimension: int):
147
"""
148
Create simplex tree from the weighted Rips complex.
149
150
Parameters:
151
- max_dimension: Maximum dimension of the complex
152
153
Returns:
154
SimplexTree: The constructed simplex tree
155
"""
156
157
class DTMRipsComplex:
158
def __init__(self, points=None, distance_matrix=None, k=1, q=2, max_filtration=float('inf')):
159
"""
160
Initialize DTM Rips complex constructor using Distance-to-Measure.
161
162
Parameters:
163
- points: Array of points in d-dimensional space
164
- distance_matrix: Full distance matrix (alternative to points)
165
- k: Number of neighbors for DTM computation
166
- q: Order used to compute distance to measure
167
- max_filtration: Maximum filtration value
168
"""
169
170
def create_simplex_tree(self, max_dimension: int):
171
"""
172
Create simplex tree from the DTM Rips complex.
173
174
Parameters:
175
- max_dimension: Maximum dimension of the complex
176
177
Returns:
178
SimplexTree: The constructed simplex tree
179
"""
180
```
181
182
### AlphaComplex
183
184
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.
185
186
```python { .api }
187
class AlphaComplex:
188
def __init__(self, points, precision: str = 'safe'):
189
"""
190
Initialize Alpha complex constructor.
191
192
Parameters:
193
- points: List of points in d-dimensional space
194
- precision: Precision mode ('safe', 'exact', 'fast')
195
"""
196
197
def create_simplex_tree(self):
198
"""
199
Create simplex tree from the Alpha complex.
200
201
Returns:
202
SimplexTree: Filtered simplex tree with alpha filtration
203
"""
204
```
205
206
### DelaunayComplex
207
208
Constructs Delaunay triangulations, providing the foundational geometric structure for Alpha complexes.
209
210
```python { .api }
211
class DelaunayComplex:
212
def __init__(self, points):
213
"""
214
Initialize Delaunay complex constructor.
215
216
Parameters:
217
- points: List of points in d-dimensional space
218
"""
219
220
def create_simplex_tree(self):
221
"""
222
Create simplex tree from the Delaunay triangulation.
223
224
Returns:
225
SimplexTree: Unfiltered simplex tree
226
"""
227
```
228
229
### TangentialComplex
230
231
Constructs tangential complexes for reconstructing manifolds from point clouds. Useful for manifold learning and surface reconstruction.
232
233
```python { .api }
234
class TangentialComplex:
235
def __init__(self, points, intrinsic_dim: int):
236
"""
237
Initialize tangential complex constructor.
238
239
Parameters:
240
- points: List of points sampled from a manifold
241
- intrinsic_dim: Intrinsic dimension of the manifold
242
"""
243
244
def compute_tangential_complex(self):
245
"""Compute the tangential complex."""
246
247
def create_simplex_tree(self):
248
"""
249
Create simplex tree from the tangential complex.
250
251
Returns:
252
SimplexTree: Filtered simplex tree
253
"""
254
```
255
256
### NerveGIC
257
258
Constructs nerve complexes and graph-induced complexes, implementing mapper-like algorithms for topological data analysis.
259
260
```python { .api }
261
class NerveGIC:
262
def __init__(self):
263
"""Initialize nerve of graph-induced complex constructor."""
264
265
def set_function(self, function):
266
"""
267
Set the filter function for the complex.
268
269
Parameters:
270
- function: Function values for each point
271
"""
272
273
def set_cover(self, cover):
274
"""
275
Set the cover parameters.
276
277
Parameters:
278
- cover: Cover specification (intervals, overlap, etc.)
279
"""
280
281
def compute_nerve(self):
282
"""Compute the nerve of the cover."""
283
284
def create_simplex_tree(self):
285
"""
286
Create simplex tree from the nerve complex.
287
288
Returns:
289
SimplexTree: Nerve complex as simplex tree
290
"""
291
```
292
293
## Usage Examples
294
295
### Basic SimplexTree Construction
296
297
```python
298
import gudhi
299
300
# Create empty simplex tree
301
st = gudhi.SimplexTree()
302
303
# Insert simplices manually
304
st.insert([0, 1], filtration=0.5)
305
st.insert([1, 2], filtration=0.6)
306
st.insert([0, 2], filtration=0.7)
307
st.insert([0, 1, 2], filtration=0.8)
308
309
# Compute persistence
310
persistence = st.persistence()
311
print(f"Persistence pairs: {persistence}")
312
```
313
314
### Rips Complex from Point Cloud
315
316
```python
317
import gudhi
318
import numpy as np
319
320
# Generate random point cloud
321
points = np.random.random((50, 3))
322
323
# Build Rips complex
324
rips = gudhi.RipsComplex(points=points, max_edge_length=0.5)
325
simplex_tree = rips.create_simplex_tree(max_dimension=2)
326
327
# Compute persistent homology
328
persistence = simplex_tree.persistence()
329
```
330
331
### Alpha Complex Construction
332
333
```python
334
import gudhi
335
import numpy as np
336
337
# Generate point cloud
338
points = np.random.random((30, 2))
339
340
# Build Alpha complex
341
alpha = gudhi.AlphaComplex(points=points)
342
simplex_tree = alpha.create_simplex_tree()
343
344
# Compute persistence
345
persistence = simplex_tree.persistence()
346
```