From 3d864670aac88a2b943ad118a0d47e29d2733f1b Mon Sep 17 00:00:00 2001 From: vrouvrea Date: Tue, 7 Jun 2016 14:48:47 +0000 Subject: Cython documentation. Sphinx style. git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/ST_cythonize@1254 636b058d-ea47-450e-bf9e-a15bfbe3eedb Former-commit-id: ed09c0f54fda05d4147f5680db6f626e9a5d1a92 --- src/cython/src/cython/alpha_complex.pyx | 184 +++++++++++++++++++-- src/cython/src/cython/mini_simplex_tree.pyx | 149 ++++++++++++++++- .../src/cython/persistence_graphical_tools.py | 11 ++ src/cython/src/cython/rips_complex.pyx | 158 +++++++++++++++++- src/cython/src/cython/simplex_tree.pyx | 149 ++++++++++++++++- 5 files changed, 622 insertions(+), 29 deletions(-) (limited to 'src') diff --git a/src/cython/src/cython/alpha_complex.pyx b/src/cython/src/cython/alpha_complex.pyx index 0d44cbce..6f8f5eca 100644 --- a/src/cython/src/cython/alpha_complex.pyx +++ b/src/cython/src/cython/alpha_complex.pyx @@ -59,11 +59,35 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi": # AlphaComplex python interface cdef class AlphaComplex: + """AlphaComplex is a simplicial complex constructed from the finite cells + of a Delaunay Triangulation. + + The filtration value of each simplex is computed as the square of the + circumradius of the simplex if the circumsphere is empty (the simplex is + then said to be Gabriel), and as the minimum of the filtration values of + the codimension 1 cofaces that make it not Gabriel otherwise. + + All simplices that have a filtration value strictly greater than a given + alpha squared value are not inserted into the complex. + + .. note:: + + When Alpha_complex is constructed with an infinite value of alpha, the + complex is a Delaunay complex. + + """ + cdef Alpha_complex_interface * thisptr cdef Alpha_complex_persistence_interface * pcohptr def __cinit__(self, points=None, max_alpha_square=float('inf')): + """AlphaComplex constructor. + + Args: + points (list): A list of points in d-Dimension. + max_alpha_square (float): Maximum Alpha square value. + """ if points is not None: self.thisptr = new Alpha_complex_interface(points, max_alpha_square) @@ -75,36 +99,97 @@ cdef class AlphaComplex: del self.pcohptr def get_filtration(self): + """This function returns the main simplicial complex filtration value. + + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.filtration() def filtration(self, simplex): + """This function returns the simplicial complex filtration value for a + given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.simplex_filtration(simplex) def set_filtration(self, filtration): + """This function sets the main simplicial complex filtration value. + + :param filtration: The filtration value. + :type filtration: float. + """ self.thisptr.set_filtration( filtration) def initialize_filtration(self): + """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_filtered_tree after inserting or + removing simplices. + """ self.thisptr.initialize_filtration() def num_vertices(self): + """This function returns the number of vertices of the simplicial + complex. + + :returns: int -- the simplicial complex number of vertices. + """ return self.thisptr.num_vertices() def num_simplices(self): + """This function returns the number of simplices of the simplicial + complex. + + :returns: int -- the simplicial complex number of simplices. + """ return self.thisptr.num_simplices() def dimension(self): + """This function returns the dimension of the simplicial complex. + + :returns: int -- the simplicial complex dimension. + """ return self.thisptr.dimension() - def set_dimension(self, dim): - self.thisptr.set_dimension(dim) + def set_dimension(self, dimension): + """This function sets the dimension of the simplicial complex. + + :param dimension: The new dimension value. + :type dimension: int. + """ + self.thisptr.set_dimension(dimension) def find(self, simplex): + """This function returns if the N-simplex was found in the simplicial + complex or not. + + :param simplex: The N-simplex to find, represented by a list of vertex. + :type simplex: list of int. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) return self.thisptr.find_simplex(complex) def insert(self, simplex, filtration=0.0): + """This function inserts the given N-simplex with the given filtration + value (default value is '0.0'). + + :param simplex: The N-simplex to insert, represented by a list of + vertex. + :type simplex: list of int. + :param filtration: The filtration value of the simplex. + :type filtration: float. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -112,6 +197,12 @@ cdef class AlphaComplex: filtration) def get_filtered_tree(self): + """This function returns the tree sorted by increasing filtration + values. + + :returns: list of tuples(simplex, filtration) -- the tree sorted by + increasing filtration values. + """ cdef vector[pair[vector[int], double]] coface_tree \ = self.thisptr.get_filtered_tree() ct = [] @@ -122,9 +213,17 @@ cdef class AlphaComplex: ct.append((v, filtered_complex.second)) return ct - def get_skeleton_tree(self, dim): + def get_skeleton_tree(self, dimension): + """This function returns the tree skeleton of a maximum given + dimension. + + :param dimension: The skeleton dimension value. + :type dimension: int. + :returns: list of tuples(simplex, filtration) -- the skeleton tree + of a maximum dimension. + """ cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_skeleton_tree(dim) + = self.thisptr.get_skeleton_tree(dimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -134,6 +233,13 @@ cdef class AlphaComplex: return ct def get_star_tree(self, simplex): + """This function returns the star tree of a given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: list of tuples(simplex, filtration) -- the star tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -147,12 +253,23 @@ cdef class AlphaComplex: ct.append((v, filtered_complex.second)) return ct - def get_coface_tree(self, simplex, dim): + def get_coface_tree(self, simplex, codimension): + """This function returns the coface tree of a given N-simplex with a + given codimension. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :param codimension: The codimension. If codimension = 0, all cofaces + are returned (equivalent of get_star_tree function) + :type codimension: int. + :returns: list of tuples(simplex, filtration) -- the coface tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_coface_tree(complex, dim) + = self.thisptr.get_coface_tree(complex, codimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -162,22 +279,52 @@ cdef class AlphaComplex: return ct def remove_maximal_simplex(self, simplex): + """This function removes a given maximal N-simplex from the simplicial + complex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + """ self.thisptr.remove_maximal_simplex(simplex) def get_point(self, vertex): + """This function returns the point corresponding to a given vertex. + + :param vertex: The vertex. + :type vertex: int. + :returns: list of float -- the point. + """ cdef vector[double] point = self.thisptr.get_point(vertex) return point - def persistence(self, homology_coeff_field=11, min_persistence=0): + def persistence(self, homology_coeff_field=11, min_persistence=0.0): + """This function returns the persistence of the simplicial complex. + + :param homology_coeff_field: The homology coefficient field. Must be a + prime number + :type homology_coeff_field: int. + :param min_persistence: 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. + :type min_persistence: float. + :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a + simplex. + """ if self.pcohptr != NULL: del self.pcohptr self.pcohptr = new Alpha_complex_persistence_interface(self.thisptr) cdef vector[pair[int, pair[double, double]]] persistence_result if self.pcohptr != NULL: - persistence_result = self.pcohptr.get_persistence(homology_coeff_field, min_persistence) + persistence_result \ + = self.pcohptr.get_persistence(homology_coeff_field, + min_persistence) return persistence_result def betti_numbers(self): + """This function returns the Betti numbers of the simplicial complex. + + :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]). + """ cdef vector[int] bn_result if self.pcohptr != NULL: bn_result = self.pcohptr.betti_numbers() @@ -187,10 +334,25 @@ cdef class AlphaComplex: return bn_result def persistent_betti_numbers(self, from_value, to_value): + """This function returns the persistent Betti numbers of the + simplicial complex. + + :param from_value: The persistence birth limit to be added in the + numbers (persistent birth <= from_value). + :type from_value: float. + :param to_value: The persistence death limit to be added in the + numbers (persistent death > to_value). + :type to_value: float. + + :returns: list of int -- The persistent Betti numbers ([B0, B1, ..., + Bn]). + """ cdef vector[int] pbn_result if self.pcohptr != NULL: - pbn_result = self.pcohptr.persistent_betti_numbers(from_value, to_value) + pbn_result \ + = self.pcohptr.persistent_betti_numbers(from_value, + to_value) else: - print("persistent_betti_numbers function requires persistence function" - " to be launched first.") + print("persistent_betti_numbers function requires persistence " + "function to be launched first.") return pbn_result diff --git a/src/cython/src/cython/mini_simplex_tree.pyx b/src/cython/src/cython/mini_simplex_tree.pyx index 3d216fe2..c6725226 100644 --- a/src/cython/src/cython/mini_simplex_tree.pyx +++ b/src/cython/src/cython/mini_simplex_tree.pyx @@ -61,6 +61,15 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi": # MiniSimplexTree python interface cdef class MiniSimplexTree: + """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 non-filtered, with keys, and non contiguous vertices + version of the simplex tree. + """ cdef Simplex_tree_interface_mini * thisptr cdef Mini_simplex_tree_persistence_interface * pcohptr @@ -75,36 +84,97 @@ cdef class MiniSimplexTree: del self.pcohptr def get_filtration(self): + """This function returns the main simplicial complex filtration value. + + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.filtration() def filtration(self, simplex): + """This function returns the simplicial complex filtration value for a + given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.simplex_filtration(simplex) def set_filtration(self, filtration): + """This function sets the main simplicial complex filtration value. + + :param filtration: The filtration value. + :type filtration: float. + """ self.thisptr.set_filtration( filtration) def initialize_filtration(self): + """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_filtered_tree after inserting or + removing simplices. + """ self.thisptr.initialize_filtration() def num_vertices(self): + """This function returns the number of vertices of the simplicial + complex. + + :returns: int -- the simplicial complex number of vertices. + """ return self.thisptr.num_vertices() def num_simplices(self): + """This function returns the number of simplices of the simplicial + complex. + + :returns: int -- the simplicial complex number of simplices. + """ return self.thisptr.num_simplices() def dimension(self): + """This function returns the dimension of the simplicial complex. + + :returns: int -- the simplicial complex dimension. + """ return self.thisptr.dimension() - def set_dimension(self, dim): - self.thisptr.set_dimension(dim) + def set_dimension(self, dimension): + """This function sets the dimension of the simplicial complex. + + :param dimension: The new dimension value. + :type dimension: int. + """ + self.thisptr.set_dimension(dimension) def find(self, simplex): + """This function returns if the N-simplex was found in the simplicial + complex or not. + + :param simplex: The N-simplex to find, represented by a list of vertex. + :type simplex: list of int. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) return self.thisptr.find_simplex(complex) def insert(self, simplex, filtration=0.0): + """This function inserts the given N-simplex with the given filtration + value (default value is '0.0'). + + :param simplex: The N-simplex to insert, represented by a list of + vertex. + :type simplex: list of int. + :param filtration: The filtration value of the simplex. + :type filtration: float. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -112,6 +182,12 @@ cdef class MiniSimplexTree: filtration) def get_filtered_tree(self): + """This function returns the tree sorted by increasing filtration + values. + + :returns: list of tuples(simplex, filtration) -- the tree sorted by + increasing filtration values. + """ cdef vector[pair[vector[int], double]] coface_tree \ = self.thisptr.get_filtered_tree() ct = [] @@ -122,9 +198,17 @@ cdef class MiniSimplexTree: ct.append((v, filtered_complex.second)) return ct - def get_skeleton_tree(self, dim): + def get_skeleton_tree(self, dimension): + """This function returns the tree skeleton of a maximum given + dimension. + + :param dimension: The skeleton dimension value. + :type dimension: int. + :returns: list of tuples(simplex, filtration) -- the skeleton tree + of a maximum dimension. + """ cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_skeleton_tree(dim) + = self.thisptr.get_skeleton_tree(dimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -134,6 +218,13 @@ cdef class MiniSimplexTree: return ct def get_star_tree(self, simplex): + """This function returns the star tree of a given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: list of tuples(simplex, filtration) -- the star tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -147,12 +238,23 @@ cdef class MiniSimplexTree: ct.append((v, filtered_complex.second)) return ct - def get_coface_tree(self, simplex, dim): + def get_coface_tree(self, simplex, codimension): + """This function returns the coface tree of a given N-simplex with a + given codimension. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :param codimension: The codimension. If codimension = 0, all cofaces + are returned (equivalent of get_star_tree function) + :type codimension: int. + :returns: list of tuples(simplex, filtration) -- the coface tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_coface_tree(complex, dim) + = self.thisptr.get_coface_tree(complex, codimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -162,9 +264,27 @@ cdef class MiniSimplexTree: return ct def remove_maximal_simplex(self, simplex): + """This function removes a given maximal N-simplex from the simplicial + complex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + """ self.thisptr.remove_maximal_simplex(simplex) def persistence(self, homology_coeff_field=11): + """This function returns the persistence of the simplicial complex. + + :param homology_coeff_field: The homology coefficient field. Must be a + prime number + :type homology_coeff_field: int. + :param min_persistence: 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. + :type min_persistence: float. + :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a + simplex. + """ if self.pcohptr != NULL: del self.pcohptr self.pcohptr = new Mini_simplex_tree_persistence_interface(self.thisptr) @@ -174,6 +294,10 @@ cdef class MiniSimplexTree: return persistence_result def betti_numbers(self): + """This function returns the Betti numbers of the simplicial complex. + + :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]). + """ cdef vector[int] bn_result if self.pcohptr != NULL: bn_result = self.pcohptr.betti_numbers() @@ -183,6 +307,19 @@ cdef class MiniSimplexTree: return bn_result def persistent_betti_numbers(self, from_value, to_value): + """This function returns the persistent Betti numbers of the + simplicial complex. + + :param from_value: The persistence birth limit to be added in the + numbers (persistent birth <= from_value). + :type from_value: float. + :param to_value: The persistence death limit to be added in the + numbers (persistent death > to_value). + :type to_value: float. + + :returns: list of int -- The persistent Betti numbers ([B0, B1, ..., + Bn]). + """ cdef vector[int] pbn_result if self.pcohptr != NULL: pbn_result = self.pcohptr.persistent_betti_numbers(from_value, to_value) diff --git a/src/cython/src/cython/persistence_graphical_tools.py b/src/cython/src/cython/persistence_graphical_tools.py index b845e405..6cacf4a5 100755 --- a/src/cython/src/cython/persistence_graphical_tools.py +++ b/src/cython/src/cython/persistence_graphical_tools.py @@ -35,12 +35,17 @@ palette = ['#ff0000', '#00ff00', '#0000ff', '#00ffff', '#ff00ff', '#ffff00', '#008888'] def show_palette_values(): + """This function shows palette color values in function of the dimension. + + :returns: plot -- An horizontal bar plot of dimensions color. + """ colors = [] for color in palette: colors.append(color) y_pos = np.arange(len(palette)) + # alpha=0.4 is realy usefull for ugly colors plt.barh(y_pos, y_pos + 1, align='center', alpha=0.4, color=colors) plt.ylabel('Dimension') plt.title('Dimension palette values') @@ -48,6 +53,12 @@ def show_palette_values(): plt.show() def bar_code_persistence(persistence): + """This function plots the persistence bar code. + + :param persistence: The persistence to plot. + :type persistence: list of tuples(dimension, tuple(birth, death)). + :returns: plot -- An horizontal bar plot of persistence. + """ # Look for minimum birth date and maximum death date for plot optimisation max_death = 0 min_birth = persistence[0][1][0] diff --git a/src/cython/src/cython/rips_complex.pyx b/src/cython/src/cython/rips_complex.pyx index 52a3cfd8..13e82230 100644 --- a/src/cython/src/cython/rips_complex.pyx +++ b/src/cython/src/cython/rips_complex.pyx @@ -63,12 +63,30 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi": # RipsComplex python interface cdef class RipsComplex: + """RipsComplex is a simplicial complex constructed from a list of points. + + Each point Pn is inserted as a vertex in the simplicial complex with a + null filtration value. + + A N-simplex represented by the list of vertices Vi, ..., Vj is inserted in + the simplicial complex if all the points Pi, ..., Pj corresponding to the + vertices are within a distance less or equal to a given maximum edge length + value, and if N (dimension of the N-simplex) is less or equal to a given + maximum dimension. + """ cdef Rips_complex_interface * thisptr cdef Rips_complex_persistence_interface * pcohptr def __cinit__(self, points=None, max_dimension=3, max_edge_length=float('inf')): + """RipsComplex constructor. + + Args: + points (list): A list of points in d-Dimension. + max_dimension (int): Maximum dimension of the N-simplex to insert. + max_edge_length (float): Maximum edge length, or distance. + """ self.thisptr = new Rips_complex_interface() # Constructor from graph expansion if points is not None: @@ -82,36 +100,97 @@ cdef class RipsComplex: del self.pcohptr def get_filtration(self): + """This function returns the main simplicial complex filtration value. + + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.filtration() def filtration(self, simplex): + """This function returns the simplicial complex filtration value for a + given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.simplex_filtration(simplex) def set_filtration(self, filtration): + """This function sets the main simplicial complex filtration value. + + :param filtration: The filtration value. + :type filtration: float. + """ self.thisptr.set_filtration( filtration) def initialize_filtration(self): + """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_filtered_tree after inserting or + removing simplices. + """ self.thisptr.initialize_filtration() def num_vertices(self): + """This function returns the number of vertices of the simplicial + complex. + + :returns: int -- the simplicial complex number of vertices. + """ return self.thisptr.num_vertices() def num_simplices(self): + """This function returns the number of simplices of the simplicial + complex. + + :returns: int -- the simplicial complex number of simplices. + """ return self.thisptr.num_simplices() def dimension(self): + """This function returns the dimension of the simplicial complex. + + :returns: int -- the simplicial complex dimension. + """ return self.thisptr.dimension() - def set_dimension(self, dim): - self.thisptr.set_dimension(dim) + def set_dimension(self, dimension): + """This function sets the dimension of the simplicial complex. + + :param dimension: The new dimension value. + :type dimension: int. + """ + self.thisptr.set_dimension(dimension) def find(self, simplex): + """This function returns if the N-simplex was found in the simplicial + complex or not. + + :param simplex: The N-simplex to find, represented by a list of vertex. + :type simplex: list of int. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) return self.thisptr.find_simplex(complex) def insert(self, simplex, filtration=0.0): + """This function inserts the given N-simplex with the given filtration + value (default value is '0.0'). + + :param simplex: The N-simplex to insert, represented by a list of + vertex. + :type simplex: list of int. + :param filtration: The filtration value of the simplex. + :type filtration: float. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -119,6 +198,12 @@ cdef class RipsComplex: filtration) def get_filtered_tree(self): + """This function returns the tree sorted by increasing filtration + values. + + :returns: list of tuples(simplex, filtration) -- the tree sorted by + increasing filtration values. + """ cdef vector[pair[vector[int], double]] coface_tree \ = self.thisptr.get_filtered_tree() ct = [] @@ -129,9 +214,17 @@ cdef class RipsComplex: ct.append((v, filtered_complex.second)) return ct - def get_skeleton_tree(self, dim): + def get_skeleton_tree(self, dimension): + """This function returns the tree skeleton of a maximum given + dimension. + + :param dimension: The skeleton dimension value. + :type dimension: int. + :returns: list of tuples(simplex, filtration) -- the skeleton tree + of a maximum dimension. + """ cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_skeleton_tree(dim) + = self.thisptr.get_skeleton_tree(dimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -141,6 +234,13 @@ cdef class RipsComplex: return ct def get_star_tree(self, simplex): + """This function returns the star tree of a given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: list of tuples(simplex, filtration) -- the star tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -154,12 +254,23 @@ cdef class RipsComplex: ct.append((v, filtered_complex.second)) return ct - def get_coface_tree(self, simplex, dim): + def get_coface_tree(self, simplex, codimension): + """This function returns the coface tree of a given N-simplex with a + given codimension. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :param codimension: The codimension. If codimension = 0, all cofaces + are returned (equivalent of get_star_tree function) + :type codimension: int. + :returns: list of tuples(simplex, filtration) -- the coface tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_coface_tree(complex, dim) + = self.thisptr.get_coface_tree(complex, codimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -169,9 +280,27 @@ cdef class RipsComplex: return ct def remove_maximal_simplex(self, simplex): + """This function removes a given maximal N-simplex from the simplicial + complex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + """ self.thisptr.remove_maximal_simplex(simplex) def persistence(self, homology_coeff_field=11, min_persistence=0): + """This function returns the persistence of the simplicial complex. + + :param homology_coeff_field: The homology coefficient field. Must be a + prime number + :type homology_coeff_field: int. + :param min_persistence: 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. + :type min_persistence: float. + :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a + simplex. + """ if self.pcohptr != NULL: del self.pcohptr self.pcohptr = new Rips_complex_persistence_interface(self.thisptr) @@ -181,6 +310,10 @@ cdef class RipsComplex: return persistence_result def betti_numbers(self): + """This function returns the Betti numbers of the simplicial complex. + + :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]). + """ cdef vector[int] bn_result if self.pcohptr != NULL: bn_result = self.pcohptr.betti_numbers() @@ -190,6 +323,19 @@ cdef class RipsComplex: return bn_result def persistent_betti_numbers(self, from_value, to_value): + """This function returns the persistent Betti numbers of the + simplicial complex. + + :param from_value: The persistence birth limit to be added in the + numbers (persistent birth <= from_value). + :type from_value: float. + :param to_value: The persistence death limit to be added in the + numbers (persistent death > to_value). + :type to_value: float. + + :returns: list of int -- The persistent Betti numbers ([B0, B1, ..., + Bn]). + """ cdef vector[int] pbn_result if self.pcohptr != NULL: pbn_result = self.pcohptr.persistent_betti_numbers(from_value, to_value) diff --git a/src/cython/src/cython/simplex_tree.pyx b/src/cython/src/cython/simplex_tree.pyx index b84b7758..c5cb7595 100644 --- a/src/cython/src/cython/simplex_tree.pyx +++ b/src/cython/src/cython/simplex_tree.pyx @@ -61,6 +61,15 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi": # SimplexTree python interface cdef class SimplexTree: + """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. + """ cdef Simplex_tree_interface_full_featured * thisptr cdef Simplex_tree_persistence_interface * pcohptr @@ -75,36 +84,97 @@ cdef class SimplexTree: del self.pcohptr def get_filtration(self): + """This function returns the main simplicial complex filtration value. + + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.filtration() def filtration(self, simplex): + """This function returns the simplicial complex filtration value for a + given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: float -- the simplicial complex filtration value. + """ return self.thisptr.simplex_filtration(simplex) def set_filtration(self, filtration): + """This function sets the main simplicial complex filtration value. + + :param filtration: The filtration value. + :type filtration: float. + """ self.thisptr.set_filtration( filtration) def initialize_filtration(self): + """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_filtered_tree after inserting or + removing simplices. + """ self.thisptr.initialize_filtration() def num_vertices(self): + """This function returns the number of vertices of the simplicial + complex. + + :returns: int -- the simplicial complex number of vertices. + """ return self.thisptr.num_vertices() def num_simplices(self): + """This function returns the number of simplices of the simplicial + complex. + + :returns: int -- the simplicial complex number of simplices. + """ return self.thisptr.num_simplices() def dimension(self): + """This function returns the dimension of the simplicial complex. + + :returns: int -- the simplicial complex dimension. + """ return self.thisptr.dimension() - def set_dimension(self, dim): - self.thisptr.set_dimension(dim) + def set_dimension(self, dimension): + """This function sets the dimension of the simplicial complex. + + :param dimension: The new dimension value. + :type dimension: int. + """ + self.thisptr.set_dimension(dimension) def find(self, simplex): + """This function returns if the N-simplex was found in the simplicial + complex or not. + + :param simplex: The N-simplex to find, represented by a list of vertex. + :type simplex: list of int. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) return self.thisptr.find_simplex(complex) def insert(self, simplex, filtration=0.0): + """This function inserts the given N-simplex with the given filtration + value (default value is '0.0'). + + :param simplex: The N-simplex to insert, represented by a list of + vertex. + :type simplex: list of int. + :param filtration: The filtration value of the simplex. + :type filtration: float. + :returns: bool -- true if the simplex was found, false otherwise. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -112,6 +182,12 @@ cdef class SimplexTree: filtration) def get_filtered_tree(self): + """This function returns the tree sorted by increasing filtration + values. + + :returns: list of tuples(simplex, filtration) -- the tree sorted by + increasing filtration values. + """ cdef vector[pair[vector[int], double]] coface_tree \ = self.thisptr.get_filtered_tree() ct = [] @@ -122,9 +198,17 @@ cdef class SimplexTree: ct.append((v, filtered_complex.second)) return ct - def get_skeleton_tree(self, dim): + def get_skeleton_tree(self, dimension): + """This function returns the tree skeleton of a maximum given + dimension. + + :param dimension: The skeleton dimension value. + :type dimension: int. + :returns: list of tuples(simplex, filtration) -- the skeleton tree + of a maximum dimension. + """ cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_skeleton_tree(dim) + = self.thisptr.get_skeleton_tree(dimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -134,6 +218,13 @@ cdef class SimplexTree: return ct def get_star_tree(self, simplex): + """This function returns the star tree of a given N-simplex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :returns: list of tuples(simplex, filtration) -- the star tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) @@ -147,12 +238,23 @@ cdef class SimplexTree: ct.append((v, filtered_complex.second)) return ct - def get_coface_tree(self, simplex, dim): + def get_coface_tree(self, simplex, codimension): + """This function returns the coface tree of a given N-simplex with a + given codimension. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + :param codimension: The codimension. If codimension = 0, all cofaces + are returned (equivalent of get_star_tree function) + :type codimension: int. + :returns: list of tuples(simplex, filtration) -- the coface tree of a + simplex. + """ cdef vector[int] complex for i in simplex: complex.push_back(i) cdef vector[pair[vector[int], double]] coface_tree \ - = self.thisptr.get_coface_tree(complex, dim) + = self.thisptr.get_coface_tree(complex, codimension) ct = [] for filtered_complex in coface_tree: v = [] @@ -162,9 +264,27 @@ cdef class SimplexTree: return ct def remove_maximal_simplex(self, simplex): + """This function removes a given maximal N-simplex from the simplicial + complex. + + :param simplex: The N-simplex, represented by a list of vertex. + :type simplex: list of int. + """ self.thisptr.remove_maximal_simplex(simplex) def persistence(self, homology_coeff_field=11, min_persistence=0): + """This function returns the persistence of the simplicial complex. + + :param homology_coeff_field: The homology coefficient field. Must be a + prime number + :type homology_coeff_field: int. + :param min_persistence: 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. + :type min_persistence: float. + :returns: list of tuples(dimension, tuple(birth, death)) -- the star tree of a + simplex. + """ if self.pcohptr != NULL: del self.pcohptr self.pcohptr = new Simplex_tree_persistence_interface(self.thisptr) @@ -174,6 +294,10 @@ cdef class SimplexTree: return persistence_result def betti_numbers(self): + """This function returns the Betti numbers of the simplicial complex. + + :returns: list of int -- The Betti numbers ([B0, B1, ..., Bn]). + """ cdef vector[int] bn_result if self.pcohptr != NULL: bn_result = self.pcohptr.betti_numbers() @@ -183,6 +307,19 @@ cdef class SimplexTree: return bn_result def persistent_betti_numbers(self, from_value, to_value): + """This function returns the persistent Betti numbers of the + simplicial complex. + + :param from_value: The persistence birth limit to be added in the + numbers (persistent birth <= from_value). + :type from_value: float. + :param to_value: The persistence death limit to be added in the + numbers (persistent death > to_value). + :type to_value: float. + + :returns: list of int -- The persistent Betti numbers ([B0, B1, ..., + Bn]). + """ cdef vector[int] pbn_result if self.pcohptr != NULL: pbn_result = self.pcohptr.persistent_betti_numbers(from_value, to_value) -- cgit v1.2.3