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]).
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() 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.
Returns:The simplicial complex filtration value.
Return type: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.
Returns:true if the simplex was found, false otherwise.
Return type: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)
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 N-simplex.

Parameters:simplex (list of int.) – The N-simplex, 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(), or get_filtration() after inserting or removing simplices.

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.
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 call initialize_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 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.
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.