Simplex tree reference manual¶

class
gudhi.
SimplexTree
¶ Bases:
object
The simplex tree is an efficient and flexible data structure for representing general (filtered) simplicial complexes. The data structure is described in JeanDaniel Boissonnat and Clément Maria. The Simplex Tree: An Efficient Data Structure for General Simplicial Complexes. Algorithmica, pages 1–22, 2014.
This class is a filtered, with keys, and non contiguous vertices version of the simplex tree.

__init__
()¶ SimplexTree constructor.

assign_filtration
()¶ This function assigns the simplicial complex filtration value for a given Nsimplex.
Parameters:  simplex (list of int.) – The Nsimplex, represented by a list of vertex.
 filtration (float) – The simplicial complex filtration value.

betti_numbers
()¶ This function returns the Betti numbers of the simplicial complex.
Returns: The Betti numbers ([B0, B1, …, Bn]). Return type: list of int Note: betti_numbers function requires persistence()
function to be launched first.

dimension
()¶ This function returns the dimension of the simplicial complex.
Returns: the simplicial complex dimension. Return type: int Note
This function is not constant time because it can recompute dimension if required (can be triggered by
remove_maximal_simplex()
orprune_above_filtration()
methods).

expansion
()¶ Expands the Simplex_tree containing only its one skeleton until dimension max_dim.
The expanded simplicial complex until dimension \(d\) attached to a graph \(G\) is the maximal simplicial complex of dimension at most \(d\) admitting the graph \(G\) as \(1\)skeleton. The filtration value assigned to a simplex is the maximal filtration value of one of its edges.
The Simplex_tree must contain no simplex of dimension bigger than 1 when calling the method.
Parameters: max_dim (int.) – The maximal dimension.

filtration
()¶ This function returns the filtration value for a given Nsimplex in this simplicial complex, or +infinity if it is not in the complex.
Parameters: simplex (list of int.) – The Nsimplex, represented by a list of vertex. Returns: The simplicial complex filtration value. Return type: float

find
()¶ This function returns if the Nsimplex was found in the simplicial complex or not.
Parameters: simplex (list of int.) – The Nsimplex to find, represented by a list of vertex. Returns: true if the simplex was found, false otherwise. Return type: bool

get_cofaces
()¶ This function returns the cofaces of a given Nsimplex with a given codimension.
Parameters:  simplex (list of int.) – The Nsimplex, represented by a list of vertex.
 codimension (int.) – The codimension. If codimension = 0, all cofaces are returned (equivalent of get_star function)
Returns: The (simplices of the) cofaces of a simplex
Return type: list of tuples(simplex, filtration)

get_filtration
()¶ This function returns a list of all simplices with their given filtration values.
Returns: The simplices sorted by increasing filtration values. Return type: list of tuples(simplex, filtration)

get_skeleton
()¶ This function returns the (simplices of the) skeleton of a maximum given dimension.
Parameters: dimension (int.) – The skeleton dimension value. Returns: The (simplices of the) skeleton of a maximum dimension. Return type: list of tuples(simplex, filtration)

get_star
()¶ This function returns the star of a given Nsimplex.
Parameters: simplex (list of int.) – The Nsimplex, represented by a list of vertex. Returns: The (simplices of the) star of a simplex. Return type: list of tuples(simplex, filtration)

initialize_filtration
()¶ This function initializes and sorts the simplicial complex filtration vector.
Note
This function must be launched before
persistence()
,betti_numbers()
,persistent_betti_numbers()
, orget_filtration()
afterinserting
orremoving
simplices.

insert
()¶ This function inserts the given Nsimplex and its subfaces with the given filtration value (default value is ‘0.0’). If some of those simplices are already present with a higher filtration value, their filtration value is lowered.
Parameters:  simplex (list of int.) – The Nsimplex to insert, represented by a list of vertex.
 filtration (float.) – The filtration value of the simplex.
Returns: true if the simplex was not yet in the complex, false otherwise (whatever its original filtration value).
Return type: bool

make_filtration_non_decreasing
()¶ This function ensures that each simplex has a higher filtration value than its faces by increasing the filtration values.
Returns: The filtration modification information. Return type: bint Note
Some simplex tree functions require the filtration to be valid. make_filtration_non_decreasing function is not launching
initialize_filtration()
but returns the filtration modification information. If the complex has changed , please callinitialize_filtration()
to recompute it.

num_simplices
()¶ This function returns the number of simplices of the simplicial complex.
Returns: the simplicial complex number of simplices. Return type: int

num_vertices
()¶ This function returns the number of vertices of the simplicial complex.
Returns: The simplicial complex number of vertices. Return type: int

persistence
()¶ This function returns the persistence of the simplicial complex.
Parameters:  homology_coeff_field (int.) – The homology coefficient field. Must be a prime number. Default value is 11.
 min_persistence (float.) – The minimum persistence value to take into account (strictly greater than min_persistence). Default value is 0.0. Sets min_persistence to 1.0 to see all values.
Returns: The persistence of the simplicial complex.
Return type: list of pairs(dimension, pair(birth, death))

persistence_intervals_in_dimension
()¶ This function returns the persistence intervals of the simplicial complex in a specific dimension.
Parameters: dimension (int.) – The specific dimension. Returns: The persistence intervals. Return type: list of pair of float Note: intervals_in_dim function requires persistence()
function to be launched first.

persistence_pairs
()¶ This function returns the persistence pairs of the simplicial complex.
Returns: The persistence intervals. Return type: list of pair of list of int Note: intervals_in_dim function requires persistence()
function to be launched first.

persistent_betti_numbers
()¶ This function returns the persistent Betti numbers of the simplicial complex.
Parameters:  from_value (float.) – The persistence birth limit to be added in the numbers (persistent birth <= from_value).
 to_value (float.) – The persistence death limit to be added in the numbers (persistent death > to_value).
Returns: The persistent Betti numbers ([B0, B1, …, Bn]).
Return type: list of int
Note: persistent_betti_numbers function requires
persistence()
function to be launched first.

prune_above_filtration
()¶ Prune above filtration value given as parameter.
Parameters: filtration (float.) – Maximum threshold value. Returns: The filtration modification information. Return type: bint Note
Some simplex tree functions require the filtration to be valid. prune_above_filtration function is not launching
initialize_filtration()
but returns the filtration modification information. If the complex has changed , please callinitialize_filtration()
to recompute it.Note
Note that the dimension of the simplicial complex may be lower after calling
prune_above_filtration()
than it was before. However,upper_bound_dimension()
will return the old value, which remains a valid upper bound. If you care, you can calldimension()
method to recompute the exact dimension.

remove_maximal_simplex
()¶ This function removes a given maximal Nsimplex from the simplicial complex.
Parameters: simplex (list of int.) – The Nsimplex, represented by a list of vertex. Note
Be aware that removing is shifting data in a flat_map (
initialize_filtration()
to be done).Note
The dimension of the simplicial complex may be lower after calling remove_maximal_simplex than it was before. However,
upper_bound_dimension()
method will return the old value, which remains a valid upper bound. If you care, you can calldimension()
to recompute the exact dimension.

set_dimension
()¶ This function sets the dimension of the simplicial complex.
Parameters: dimension (int.) – The new dimension value. Note
This function must be used with caution because it disables dimension recomputation when required (this recomputation can be triggered by
remove_maximal_simplex()
orprune_above_filtration()
).

upper_bound_dimension
()¶ This function returns a valid dimension upper bound of the simplicial complex.
Returns: an upper bound on the dimension of the simplicial complex. Return type: int

write_persistence_diagram
()¶ This function writes the persistence intervals of the simplicial complex in a user given file name.
Parameters: persistence_file (string.) – The specific dimension. Note: intervals_in_dim function requires persistence()
function to be launched first.
