# 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 Jean-Daniel 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 N-simplex.

Parameters: simplex (list of int.) – The N-simplex, 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]). list of int 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. int

Note

This function is not constant time because it can recompute dimension if required (can be triggered by remove_maximal_simplex() or prune_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 N-simplex in this simplicial complex, or +infinity if it is not in the complex.

Parameters: simplex (list of int.) – The N-simplex, represented by a list of vertex. The simplicial complex filtration value. float
find()

This function returns if the N-simplex was found in the simplicial complex or not.

Parameters: simplex (list of int.) – The N-simplex to find, represented by a list of vertex. true if the simplex was found, false otherwise. bool
get_cofaces()

This function returns the cofaces of a given N-simplex with a given codimension.

Parameters: simplex (list of int.) – The N-simplex, represented by a list of vertex. codimension (int.) – The codimension. If codimension = 0, all cofaces are returned (equivalent of get_star function) The (simplices of the) cofaces of a simplex 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. 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. The (simplices of the) skeleton of a maximum dimension. list of tuples(simplex, filtration)
get_star()

This function returns the star of a given N-simplex.

Parameters: simplex (list of int.) – The N-simplex, represented by a list of vertex. The (simplices of the) star of a simplex. list of tuples(simplex, filtration)
initialize_filtration()

This function initializes and sorts the simplicial complex filtration vector.

insert()

This function inserts the given N-simplex 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 N-simplex to insert, represented by a list of vertex. filtration (float.) – The filtration value of the simplex. true if the simplex was not yet in the complex, false otherwise (whatever its original filtration value). bool
num_simplices()

This function returns the number of simplices of the simplicial complex.

Returns: the simplicial complex number of simplices. int
num_vertices()

This function returns the number of vertices of the simplicial complex.

Returns: The simplicial complex number of vertices. 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. The persistence of the simplicial complex. 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. The persistence intervals. list of pair of float 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). The persistent Betti numbers ([B0, B1, ..., Bn]). list of int 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. The filtration modification information. 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 call initialize_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 call dimension() method to recompute the exact dimension.

remove_maximal_simplex()

This function removes a given maximal N-simplex from the simplicial complex.

Parameters: simplex (list of int.) – The N-simplex, 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 call dimension() 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() or prune_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. 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. intervals_in_dim function requires persistence() function to be launched first.