diff options
author | vrouvrea <vrouvrea@636b058d-ea47-450e-bf9e-a15bfbe3eedb> | 2016-08-12 15:03:09 +0000 |
---|---|---|
committer | vrouvrea <vrouvrea@636b058d-ea47-450e-bf9e-a15bfbe3eedb> | 2016-08-12 15:03:09 +0000 |
commit | 7de929fe3cc4dda0fd565bc7ce9bf92c521053ed (patch) | |
tree | e7f7674c7e45168bbf3cdbfd1f7b0568ff562be3 /src/cython/doc | |
parent | 359411b63f1d4698cca3413c0f00822f80243786 (diff) |
move cython/doc/source in cython/src/doc
git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/ST_cythonize@1433 636b058d-ea47-450e-bf9e-a15bfbe3eedb
Former-commit-id: 9e9d17b611d04df874ab31a844c9549821bc16ee
Diffstat (limited to 'src/cython/doc')
-rw-r--r-- | src/cython/doc/source/alpha_complex_ref.rst | 10 | ||||
-rw-r--r-- | src/cython/doc/source/alpha_complex_sum.rst | 21 | ||||
-rw-r--r-- | src/cython/doc/source/alpha_complex_user.rst | 192 | ||||
-rw-r--r-- | src/cython/doc/source/biblio.rst | 7 | ||||
-rw-r--r-- | src/cython/doc/source/cgal_citation.rst | 8 | ||||
-rw-r--r-- | src/cython/doc/source/cubical_complex_ref.rst | 9 | ||||
-rw-r--r-- | src/cython/doc/source/cubical_complex_sum.rst | 12 | ||||
-rw-r--r-- | src/cython/doc/source/cubical_complex_user.rst | 150 | ||||
-rw-r--r-- | src/cython/doc/source/periodic_cubical_complex_ref.rst | 9 | ||||
-rw-r--r-- | src/cython/doc/source/persistent_cohomology_sum.rst | 28 | ||||
-rw-r--r-- | src/cython/doc/source/persistent_cohomology_user.rst | 104 | ||||
-rw-r--r-- | src/cython/doc/source/simplex_tree_ref.rst | 10 | ||||
-rw-r--r-- | src/cython/doc/source/simplex_tree_sum.rst | 13 | ||||
-rw-r--r-- | src/cython/doc/source/simplex_tree_user.rst | 67 | ||||
-rw-r--r-- | src/cython/doc/source/witness_complex_ref.rst | 10 | ||||
-rw-r--r-- | src/cython/doc/source/witness_complex_sum.rst | 25 | ||||
-rw-r--r-- | src/cython/doc/source/witness_complex_user.rst | 31 |
17 files changed, 0 insertions, 706 deletions
diff --git a/src/cython/doc/source/alpha_complex_ref.rst b/src/cython/doc/source/alpha_complex_ref.rst deleted file mode 100644 index 6a122b09..00000000 --- a/src/cython/doc/source/alpha_complex_ref.rst +++ /dev/null @@ -1,10 +0,0 @@ -============================== -Alpha complex reference manual -============================== - -.. autoclass:: gudhi.AlphaComplex - :members: - :undoc-members: - :show-inheritance: - - .. automethod:: gudhi.AlphaComplex.__init__ diff --git a/src/cython/doc/source/alpha_complex_sum.rst b/src/cython/doc/source/alpha_complex_sum.rst deleted file mode 100644 index b608050e..00000000 --- a/src/cython/doc/source/alpha_complex_sum.rst +++ /dev/null @@ -1,21 +0,0 @@ -===================================== ===================================== ===================================== -:Author: Vincent Rouvreau :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+-------------------------------------------+----------------------------------------------------------------------+ -| .. image:: | Alpha_complex is a simplicial complex constructed from the finite | -| img/alpha_complex_representation.png | 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. | -| | | -| | This package requires having CGAL version 4.7 or higher (4.8.1 is | -| | advised for better perfomances). | -+-------------------------------------------+----------------------------------------------------------------------+ -| :doc:`alpha_complex_user` | :doc:`alpha_complex_ref` | -+-------------------------------------------+----------------------------------------------------------------------+ diff --git a/src/cython/doc/source/alpha_complex_user.rst b/src/cython/doc/source/alpha_complex_user.rst deleted file mode 100644 index 07bfcabf..00000000 --- a/src/cython/doc/source/alpha_complex_user.rst +++ /dev/null @@ -1,192 +0,0 @@ -========================= -Alpha complex user manual -========================= -Definition ----------- - -.. include:: alpha_complex_sum.rst - -Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_sum>` using -`Delaunay Triangulation <http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations>`_ -:cite:`cgal:hdj-t-15b` from `CGAL <http://www.cgal.org/>`_ (the Computational Geometry Algorithms Library -:cite:`cgal:eb-15b`). - -Remarks -^^^^^^^ -When Alpha_complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex. - -Example from points -------------------- - -This example builds the Delaunay triangulation from the given points, and initializes the alpha complex with it: - -.. testcode:: - - import gudhi - alpha_complex = gudhi.AlphaComplex(points=[[1, 1], [7, 0], [4, 6], [9, 6], [0, 14], [2, 19], [9, 17]], - max_alpha_square=60.0) - result_str = 'Alpha complex is of dimension ' + repr(alpha_complex.dimension()) + ' - ' + \ - repr(alpha_complex.num_simplices()) + ' simplices - ' + \ - repr(alpha_complex.num_vertices()) + ' vertices.' - print(result_str) - for fitered_value in alpha_complex.get_filtered_tree(): - print(fitered_value) - -The output is: - -.. testoutput:: - - Alpha complex is of dimension 2 - 25 simplices - 7 vertices. - ([0], 0.0) - ([1], 0.0) - ([2], 0.0) - ([3], 0.0) - ([4], 0.0) - ([5], 0.0) - ([6], 0.0) - ([2, 3], 6.25) - ([4, 5], 7.25) - ([0, 2], 8.5) - ([0, 1], 9.25) - ([1, 3], 10.0) - ([1, 2], 11.25) - ([1, 2, 3], 12.5) - ([0, 1, 2], 12.995867768595042) - ([5, 6], 13.25) - ([2, 4], 20.0) - ([4, 6], 22.736686390532547) - ([4, 5, 6], 22.736686390532547) - ([3, 6], 30.25) - ([2, 6], 36.5) - ([2, 3, 6], 36.5) - ([2, 4, 6], 37.24489795918368) - ([0, 4], 59.710743801652896) - ([0, 2, 4], 59.710743801652896) - - -Algorithm ---------- - -Data structure -^^^^^^^^^^^^^^ - -In order to build the alpha complex, first, a Simplex tree is built from the cells of a Delaunay Triangulation. -(The filtration value is set to NaN, which stands for unknown value): - -.. image:: - img/alpha_complex_doc.png - :align: center - :alt: Simplex tree structure construction example - -Filtration value computation algorithm -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - **for** i : dimension :math:`\rightarrow` 0 **do** - **for all** :math:`\sigma` of dimension i - **if** filtration(:math:`\sigma`) is NaN **then** - filtration(:math:`\sigma`) = :math:`\alpha^2(\sigma)` - **end if** - - *//propagate alpha filtration value* - - **for all** :math:`\tau` face of :math:`\sigma` - **if** filtration(:math:`\tau`) is not NaN **then** - filtration(:math:`\tau`) = filtration(:math:`\sigma`) - **end if** - **end for** - **end for** - **end for** - - make_filtration_non_decreasing() - - prune_above_filtration() - -Dimension 2 -^^^^^^^^^^^ - -From the example above, it means the algorithm looks into each triangle ([0,1,2], [0,2,4], [1,2,3], ...), -computes the filtration value of the triangle, and then propagates the filtration value as described -here: - -.. image:: - img/alpha_complex_doc_420.png - :align: center - :alt: Filtration value propagation example - -Dimension 1 -^^^^^^^^^^^ - -Then, the algorithm looks into each edge ([0,1], [0,2], [1,2], ...), -computes the filtration value of the edge (in this case, propagation will have no effect). - -Dimension 0 -^^^^^^^^^^^ - -Finally, the algorithm looks into each vertex ([0], [1], [2], [3], [4], [5] and [6]) and -sets the filtration value (0 in case of a vertex - propagation will have no effect). - -Non decreasing filtration values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not -quite define a proper filtration (i.e. non-decreasing with respect to inclusion). -We fix that up by calling `Simplex_tree::make_filtration_non_decreasing()` (cf. -`C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_). - -Prune above given filtration value -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The simplex tree is pruned from the given maximum alpha squared value (cf. `Simplex_tree::prune_above_filtration()` -int he `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_). -In the following example, the value is given by the user as argument of the program. - - -Example from OFF file -^^^^^^^^^^^^^^^^^^^^^ - -This example builds the Delaunay triangulation from the points given by an OFF file, and initializes the alpha complex -with it. - - -Then, it is asked to display information about the alpha complex: - -.. testcode:: - - import gudhi - alpha_complex = gudhi.AlphaComplex(off_file='source/alphacomplexdoc.off', - max_alpha_square=59.0) - result_str = 'Alpha complex is of dimension ' + repr(alpha_complex.dimension()) + ' - ' + \ - repr(alpha_complex.num_simplices()) + ' simplices - ' + \ - repr(alpha_complex.num_vertices()) + ' vertices.' - print(result_str) - for fitered_value in alpha_complex.get_filtered_tree(): - print(fitered_value) - -the program output is: - -.. testoutput:: - - Alpha complex is of dimension 2 - 23 simplices - 7 vertices. - ([0], 0.0) - ([1], 0.0) - ([2], 0.0) - ([3], 0.0) - ([4], 0.0) - ([5], 0.0) - ([6], 0.0) - ([2, 3], 6.25) - ([4, 5], 7.25) - ([0, 2], 8.5) - ([0, 1], 9.25) - ([1, 3], 10.0) - ([1, 2], 11.25) - ([1, 2, 3], 12.5) - ([0, 1, 2], 12.995867768595042) - ([5, 6], 13.25) - ([2, 4], 20.0) - ([4, 6], 22.736686390532547) - ([4, 5, 6], 22.736686390532547) - ([3, 6], 30.25) - ([2, 6], 36.5) - ([2, 3, 6], 36.5) - ([2, 4, 6], 37.24489795918368) diff --git a/src/cython/doc/source/biblio.rst b/src/cython/doc/source/biblio.rst deleted file mode 100644 index b8e733ed..00000000 --- a/src/cython/doc/source/biblio.rst +++ /dev/null @@ -1,7 +0,0 @@ -============ -Bibliography -============ - -.. bibliography:: bibliography.bib - :filter: docnames - :style: unsrt diff --git a/src/cython/doc/source/cgal_citation.rst b/src/cython/doc/source/cgal_citation.rst deleted file mode 100644 index bbc4ef9e..00000000 --- a/src/cython/doc/source/cgal_citation.rst +++ /dev/null @@ -1,8 +0,0 @@ -============== -CGAL citations -============== - -.. - bibliography:: how_to_cite_cgal.bib - :filter: docnames - :style: unsrt diff --git a/src/cython/doc/source/cubical_complex_ref.rst b/src/cython/doc/source/cubical_complex_ref.rst deleted file mode 100644 index 84aa4223..00000000 --- a/src/cython/doc/source/cubical_complex_ref.rst +++ /dev/null @@ -1,9 +0,0 @@ -Cubical complex reference manual -################################ - -.. autoclass:: gudhi.CubicalComplex - :members: - :undoc-members: - :show-inheritance: - - .. automethod:: gudhi.CubicalComplex.__init__ diff --git a/src/cython/doc/source/cubical_complex_sum.rst b/src/cython/doc/source/cubical_complex_sum.rst deleted file mode 100644 index 4008a1fd..00000000 --- a/src/cython/doc/source/cubical_complex_sum.rst +++ /dev/null @@ -1,12 +0,0 @@ -===================================== ===================================== ===================================== -:Author: Pawel Dlotko :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+---------------------------------------------+----------------------------------------------------------------------+ -| .. image:: | The cubical complex is an example of a structured complex useful in | -| img/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image | -| | analysis. | -+---------------------------------------------+----------------------------------------------------------------------+ -| :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | -| | * :doc:`periodic_cubical_complex_ref` | -+---------------------------------------------+----------------------------------------------------------------------+ diff --git a/src/cython/doc/source/cubical_complex_user.rst b/src/cython/doc/source/cubical_complex_user.rst deleted file mode 100644 index 38ff978c..00000000 --- a/src/cython/doc/source/cubical_complex_user.rst +++ /dev/null @@ -1,150 +0,0 @@ -=========================== -Cubical complex user manual -=========================== -Definition ----------- - -===================================== ===================================== ===================================== -:Author: Pawel Dlotko :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+---------------------------------------------+----------------------------------------------------------------------+ -| :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | -| | * :doc:`periodic_cubical_complex_ref` | -+---------------------------------------------+----------------------------------------------------------------------+ - -The cubical complex is an example of a structured complex useful in computational mathematics (specially rigorous -numerics) and image analysis. - -An *elementary interval* is an interval of a form :math:`[n,n+1]`, or :math:`[n,n]`, for :math:`n \in \mathcal{Z}`. -The first one is called *non-degenerate*, while the second one is a *degenerate* interval. A -*boundary of a elementary interval* is a chain :math:`\partial [n,n+1] = [n+1,n+1]-[n,n]` in case of -non-degenerated elementary interval and :math:`\partial [n,n] = 0` in case of degenerate elementary interval. An -*elementary cube* :math:`C` is a product of elementary intervals, :math:`C=I_1 \times \ldots \times I_n`. -*Embedding dimension* of a cube is n, the number of elementary intervals (degenerate or not) in the product. -A *dimension of a cube* :math:`C=I_1 \times ... \times I_n` is the number of non degenerate elementary -intervals in the product. A *boundary of a cube* :math:`C=I_1 \times \ldots \times I_n` is a chain obtained -in the following way: - -.. math:: - - \partial C = (\partial I_1 \times \ldots \times I_n) + (I_1 \times \partial I_2 \times \ldots \times I_n) + - \ldots + (I_1 \times I_2 \times \ldots \times \partial I_n). - -A *cubical complex* :math:`\mathcal{K}` is a collection of cubes closed under operation of taking boundary -(i.e. boundary of every cube from the collection is in the collection). A cube :math:`C` in cubical complex -:math:`\mathcal{K}` is *maximal* if it is not in a boundary of any other cube in :math:`\mathcal{K}`. A -*support* of a cube :math:`C` is the set in :math:`\mathbb{R}^n` occupied by :math:`C` (:math:`n` is the embedding -dimension of :math:`C`). - -Cubes may be equipped with a filtration values in which case we have filtered cubical complex. All the cubical -complexes considered in this implementation are filtered cubical complexes (although, the range of a filtration may -be a set of two elements). - -For further details and theory of cubical complexes, please consult :cite:`kaczynski2004computational` as well as the -following paper :cite:`peikert2012topological`. - -Data structure. ---------------- - -The implementation of Cubical complex provides a representation of complexes that occupy a rectangular region in -:math:`\mathbb{R}^n`. This extra assumption allows for a memory efficient way of storing cubical complexes in a form -of so called bitmaps. Let -:math:`R = [b_1,e_1] \times \ldots \times [b_n,e_n]`, for :math:`b_1,...b_n,e_1,...,e_n \in \mathbb{Z}`, -:math:`b_i \leq d_i` be the considered rectangular region and let :math:`\mathcal{K}` be a filtered -cubical complex having the rectangle :math:`R` as its support. Note that the structure of the coordinate system gives -a way a lexicographical ordering of cells of :math:`\mathcal{K}`. This ordering is a base of the presented -bitmap-based implementation. In this implementation, the whole cubical complex is stored as a vector of the values -of filtration. This, together with dimension of :math:`\mathcal{K}` and the sizes of :math:`\mathcal{K}` in all -directions, allows to determine, dimension, neighborhood, boundary and coboundary of every cube -:math:`C \in \mathcal{K}`. - -.. image:: - img/Cubical_complex_representation.png - :align: center - :alt: Cubical complex. - -Note that the cubical complex in the figure above is, in a natural way, a product of one dimensional cubical -complexes in :math:`\mathbb{R}`. The number of all cubes in each direction is equal :math:`2n+1`, where :math:`n` is -the number of maximal cubes in the considered direction. Let us consider a cube at the position :math:`k` in the -bitmap. -Knowing the sizes of the bitmap, by a series of modulo operation, we can determine which elementary intervals are -present in the product that gives the cube :math:`C`. In a similar way, we can compute boundary and the coboundary of -each cube. Further details can be found in the literature. - -Input Format. -------------- - -In the current implantation, filtration is given at the maximal cubes, and it is then extended by the lower star -filtration to all cubes. There are a number of constructors that can be used to construct cubical complex by users -who want to use the code directly. They can be found in the :doc:`cubical_complex_ref`. -Currently one input from a text file is used. It uses a format used already in -`Perseus software <http://www.sas.upenn.edu/~vnanda/perseus/>`_ by Vidit Nanda. -Below we are providing a description of the format. The first line contains a number d begin the dimension of the -bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3 -in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8 -20 4 7 6 5 in the example below). - -.. image:: - img/exampleBitmap.png - :align: center - :alt: Example of a input data. - -The input file for the following complex is: - -.. literalinclude:: cubicalcomplexdoc.txt - -.. centered:: cubicalcomplexdoc.txt - -.. testcode:: - - import gudhi - cubical_complex = gudhi.CubicalComplex(perseus_file='source/cubicalcomplexdoc.txt') - result_str = 'Cubical complex is of dimension ' + repr(cubical_complex.dimension()) + ' - ' + \ - repr(cubical_complex.num_simplices()) + ' simplices.' - print(result_str) - -the program output is: - -.. testoutput:: - - Cubical complex is of dimension 2 - 49 simplices. - -Periodic boundary conditions. ------------------------------ - -Often one would like to impose periodic boundary conditions to the cubical complex (cf. -:doc:`periodic_cubical_complex_ref`). -Let :math:`I_1\times ... \times I_n` be a box that is decomposed with a cubical complex :math:`\mathcal{K}`. -Imposing periodic boundary conditions in the direction i, means that the left and the right side of a complex -:math:`\mathcal{K}` are considered the same. In particular, if for a bitmap :math:`\mathcal{K}` periodic boundary -conditions are imposed in all directions, then complex :math:`\mathcal{K}` became n-dimensional torus. One can use -various constructors from the file Bitmap_cubical_complex_periodic_boundary_conditions_base.h to construct cubical -complex with periodic boundary conditions. One can also use Perseus style input files. To indicate periodic boundary -conditions in a given direction, then number of top dimensional cells in this direction have to be multiplied by -1. -For instance: - -.. literalinclude:: periodiccubicalcomplexdoc.txt - -.. centered:: periodiccubicalcomplexdoc.txt - -Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y. - -.. testcode:: - - import gudhi - periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='source/periodiccubicalcomplexdoc.txt') - result_str = 'Periodic cubical complex is of dimension ' + repr(periodic_cc.dimension()) + ' - ' + \ - repr(periodic_cc.num_simplices()) + ' simplices.' - print(result_str) - -the program output is: - -.. testoutput:: - - Periodic cubical complex is of dimension 2 - 42 simplices. - -Examples. ---------- - -End user programs are available in cython/example/ folder. diff --git a/src/cython/doc/source/periodic_cubical_complex_ref.rst b/src/cython/doc/source/periodic_cubical_complex_ref.rst deleted file mode 100644 index c6190a1b..00000000 --- a/src/cython/doc/source/periodic_cubical_complex_ref.rst +++ /dev/null @@ -1,9 +0,0 @@ -Periodic cubical complex reference manual -######################################### - -.. autoclass:: gudhi.PeriodicCubicalComplex - :members: - :undoc-members: - :show-inheritance: - - .. automethod:: gudhi.PeriodicCubicalComplex.__init__ diff --git a/src/cython/doc/source/persistent_cohomology_sum.rst b/src/cython/doc/source/persistent_cohomology_sum.rst deleted file mode 100644 index 081399a5..00000000 --- a/src/cython/doc/source/persistent_cohomology_sum.rst +++ /dev/null @@ -1,28 +0,0 @@ -===================================== ===================================== ===================================== -:Author: Clément Maria :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+---------------------------------------------+----------------------------------------------------------------------+ -| .. image:: | The theory of homology consists in attaching to a topological space | -| img/3DTorus_poch.png | a sequence of (homology) groups, capturing global topological | -| | features like connected components, holes, cavities, etc. Persistent | -| | homology studies the evolution -- birth, life and death -- of these | -| | features when the topological space is changing. Consequently, the | -| | theory is essentially composed of three elements: topological spaces,| -| | their homology groups and an evolution scheme. | -| | | -| | Computation of persistent cohomology using the algorithm of | -| | :cite:`DBLP:journals/dcg/SilvaMV11` and | -| | :cite:`DBLP:journals/corr/abs-1208-5018` and the Compressed | -| | Annotation Matrix implementation of | -| | :cite:`DBLP:conf/esa/BoissonnatDM13`. | -| | | -+---------------------------------------------+----------------------------------------------------------------------+ -| :doc:`persistent_cohomology_user` | Please refer to each data structure that contains persistence | -| | feature for reference: | -| | | -| | * :doc:`alpha_complex_ref` | -| | * :doc:`cubical_complex_ref` | -| | * :doc:`simplex_tree_ref` | -| | * :doc:`witness_complex_ref` | -+---------------------------------------------+----------------------------------------------------------------------+ diff --git a/src/cython/doc/source/persistent_cohomology_user.rst b/src/cython/doc/source/persistent_cohomology_user.rst deleted file mode 100644 index 33b19ce2..00000000 --- a/src/cython/doc/source/persistent_cohomology_user.rst +++ /dev/null @@ -1,104 +0,0 @@ -================================= -Persistent cohomology user manual -================================= -Definition ----------- -===================================== ===================================== ===================================== -:Author: Clément Maria :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+---------------------------------------------+----------------------------------------------------------------------+ -| :doc:`persistent_cohomology_user` | Please refer to each data structure that contains persistence | -| | feature for reference: | -| | | -| | * :doc:`alpha_complex_ref` | -| | * :doc:`cubical_complex_ref` | -| | * :doc:`simplex_tree_ref` | -| | * :doc:`witness_complex_ref` | -+---------------------------------------------+----------------------------------------------------------------------+ - - -Computation of persistent cohomology using the algorithm of :cite:`DBLP:journals/dcg/SilvaMV11` and -:cite:`DBLP:journals/corr/abs-1208-5018` and the Compressed Annotation Matrix implementation of -:cite:`DBLP:conf/esa/BoissonnatDM13`. - -The theory of homology consists in attaching to a topological space a sequence of (homology) groups, capturing global -topological features like connected components, holes, cavities, etc. Persistent homology studies the evolution -- -birth, life and death -- of these features when the topological space is changing. Consequently, the theory is -essentially composed of three elements: - -* topological spaces -* their homology groups -* an evolution scheme. - -Topological Spaces ------------------- - -Topological spaces are represented by simplicial complexes. -Let :math:`V = \{1, \cdots ,|V|\}` be a set of *vertices*. -A *simplex* :math:`\sigma` is a subset of vertices :math:`\sigma \subseteq V`. -A *simplicial complex* :math:`\mathbf{K}` on :math:`V` is a collection of simplices :math:`\{\sigma\}`, -:math:`\sigma \subseteq V`, such that :math:`\tau \subseteq \sigma \in \mathbf{K} \Rightarrow \tau \in \mathbf{K}`. -The dimension :math:`n=|\sigma|-1` of :math:`\sigma` is its number of elements minus 1. -A *filtration* of a simplicial complex is a function :math:`f:\mathbf{K} \rightarrow \mathbb{R}` satisfying -:math:`f(\tau)\leq f(\sigma)` whenever :math:`\tau \subseteq \sigma`. - -Homology --------- - -For a ring :math:`\mathcal{R}`, the group of *n-chains*, denoted :math:`\mathbf{C}_n(\mathbf{K},\mathcal{R})`, of -:math:`\mathbf{K}` is the group of formal sums of n-simplices with :math:`\mathcal{R}` coefficients. The -*boundary operator* is a linear operator -:math:`\partial_n: \mathbf{C}_n(\mathbf{K},\mathcal{R}) \rightarrow \mathbf{C}_{n-1}(\mathbf{K},\mathcal{R})` -such that :math:`\partial_n \sigma = \partial_n [v_0, \cdots , v_n] = \sum_{i=0}^n (-1)^{i}[v_0,\cdots ,\widehat{v_i}, \cdots,v_n]`, -where :math:`\widehat{v_i}` means :math:`v_i` is omitted from the list. The chain groups form a sequence: - -.. math:: - - \cdots \ \ \mathbf{C}_n(\mathbf{K},\mathcal{R}) \xrightarrow{\ \partial_n\ } - \mathbf{C}_{n-1}(\mathbf{K},\mathcal{R}) \xrightarrow{\partial_{n-1}} \cdots \xrightarrow{\ \partial_2 \ } - \mathbf{C}_1(\mathbf{K},\mathcal{R}) \xrightarrow{\ \partial_1 \ } \mathbf{C}_0(\mathbf{K},\mathcal{R}) - -of finitely many groups :math:`\mathbf{C}_n(\mathbf{K},\mathcal{R})` and homomorphisms :math:`\partial_n`, indexed by -the dimension :math:`n \geq 0`. The boundary operators satisfy the property :math:`\partial_n \circ \partial_{n+1}=0` -for every :math:`n > 0` and we define the homology groups: - -.. math:: - - \mathbf{H}_n(\mathbf{K},\mathcal{R}) = \ker \partial_n / \mathrm{im} \ \partial_{n+1} - -We refer to :cite:`Munkres-elementsalgtop1984` for an introduction to homology -theory and to :cite:`DBLP:books/daglib/0025666` for an introduction to persistent homology. - -Indexing Scheme ---------------- - -"Changing" a simplicial complex consists in applying a simplicial map. An *indexing scheme* is a directed graph -together with a traversal order, such that two consecutive nodes in the graph are connected by an arrow (either forward -or backward). -The nodes represent simplicial complexes and the directed edges simplicial maps. - -From the computational point of view, there are two types of indexing schemes of interest in persistent homology: - -* linear ones - :math:`\bullet \longrightarrow \bullet \longrightarrow \cdots \longrightarrow \bullet \longrightarrow \bullet` - in persistent homology :cite:`DBLP:journals/dcg/ZomorodianC05`, -* zigzag ones - :math:`\bullet \longrightarrow \bullet \longleftarrow \cdots \longrightarrow \bullet \longleftarrow \bullet` - in zigzag persistent homology :cite:`DBLP:journals/focm/CarlssonS10`. - -These indexing schemes have a natural left-to-right traversal order, and we describe them with ranges and iterators. -In the current release of the Gudhi library, only the linear case is implemented. - -In the following, we consider the case where the indexing scheme is induced by a filtration. - -Ordering the simplices by increasing filtration values (breaking ties so as a simplex appears after its subsimplices of -same filtration value) provides an indexing scheme. - -Examples --------- - -We provide several example files: run these examples with -h for details on their use. - -.. todo:: - examples for persistence diff --git a/src/cython/doc/source/simplex_tree_ref.rst b/src/cython/doc/source/simplex_tree_ref.rst deleted file mode 100644 index 6d196843..00000000 --- a/src/cython/doc/source/simplex_tree_ref.rst +++ /dev/null @@ -1,10 +0,0 @@ -============================= -Simplex tree reference manual -============================= - -.. autoclass:: gudhi.SimplexTree - :members: - :undoc-members: - :show-inheritance: - - .. automethod:: gudhi.SimplexTree.__init__ diff --git a/src/cython/doc/source/simplex_tree_sum.rst b/src/cython/doc/source/simplex_tree_sum.rst deleted file mode 100644 index ffdb2cf4..00000000 --- a/src/cython/doc/source/simplex_tree_sum.rst +++ /dev/null @@ -1,13 +0,0 @@ -===================================== ===================================== ===================================== -:Author: Clément Maria :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+-------------------------------------------+----------------------------------------------------------------------+ -| .. image:: | The simplex tree is an efficient and flexible data structure for | -| img/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | -| | | -| | The data structure is described in | -| | :cite:`boissonnatmariasimplextreealgorithmica` | -+-------------------------------------------+----------------------------------------------------------------------+ -| :doc:`simplex_tree_user` | :doc:`simplex_tree_ref` | -+-------------------------------------------+----------------------------------------------------------------------+ diff --git a/src/cython/doc/source/simplex_tree_user.rst b/src/cython/doc/source/simplex_tree_user.rst deleted file mode 100644 index 3a00f1ac..00000000 --- a/src/cython/doc/source/simplex_tree_user.rst +++ /dev/null @@ -1,67 +0,0 @@ -======================== -Simplex tree user manual -======================== -Definition ----------- - -.. include:: simplex_tree_sum.rst - -A simplicial complex :math:`\mathbf{K}` on a set of vertices :math:`V = \{1, \cdots ,|V|\}` is a collection of -simplices :math:`\{\sigma\}`, :math:`\sigma \subseteq V` such that -:math:`\tau \subseteq \sigma \in \mathbf{K} \rightarrow \tau \in \mathbf{K}`. The dimension :math:`n=|\sigma|-1` of -:math:`\sigma` is its number of elements minus `1`. - -A filtration of a simplicial complex is a function :math:`f:\mathbf{K} \rightarrow \mathbb{R}` satisfying -:math:`f(\tau)\leq f(\sigma)` whenever :math:`\tau \subseteq \sigma`. Ordering the simplices by increasing filtration -values (breaking ties so as a simplex appears after its subsimplices of same filtration value) provides an indexing -scheme. - - -Implementation --------------- - -There are two implementation of complexes. The first on is the Simplex_tree data structure. -The simplex tree is an efficient and flexible data structure for representing general (filtered) simplicial complexes. -The data structure is described in :cite`boissonnatmariasimplextreealgorithmica`. - -The second one is the Hasse_complex. The Hasse complex is a data structure representing explicitly all co-dimension 1 -incidence relations in a complex. It is consequently faster when accessing the boundary of a simplex, but is less -compact and harder to construct from scratch. - -Example -------- - -.. testcode:: - - import gudhi - st = gudhi.SimplexTree() - if st.insert([0, 1]): - print("[0, 1] inserted") - if st.insert([0, 1, 2], filtration=4.0): - print("[0, 1, 2] inserted") - if st.find([0, 1]): - print("[0, 1] found") - print("num_vertices=", st.num_vertices()) - print("num_simplices=", st.num_simplices()) - print("skeleton_tree(2) =") - for sk_value in st.get_skeleton_tree(2): - print(sk_value) - - -The output is: - -.. testoutput:: - - [0, 1] inserted - [0, 1, 2] inserted - [0, 1] found - ('num_vertices=', 3) - ('num_simplices=', 7) - skeleton_tree(2) = - ([0, 1, 2], 4.0) - ([0, 1], 0.0) - ([0, 2], 4.0) - ([0], 0.0) - ([1, 2], 4.0) - ([1], 0.0) - ([2], 4.0) diff --git a/src/cython/doc/source/witness_complex_ref.rst b/src/cython/doc/source/witness_complex_ref.rst deleted file mode 100644 index c78760cb..00000000 --- a/src/cython/doc/source/witness_complex_ref.rst +++ /dev/null @@ -1,10 +0,0 @@ -================================ -Witness complex reference manual -================================ - -.. autoclass:: gudhi.WitnessComplex - :members: - :undoc-members: - :show-inheritance: - - .. automethod:: gudhi.WitnessComplex.__init__ diff --git a/src/cython/doc/source/witness_complex_sum.rst b/src/cython/doc/source/witness_complex_sum.rst deleted file mode 100644 index 0d65d420..00000000 --- a/src/cython/doc/source/witness_complex_sum.rst +++ /dev/null @@ -1,25 +0,0 @@ -===================================== ===================================== ===================================== -:Author: Siargey Kachanovich :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - -+---------------------------------------------+----------------------------------------------------------------------+ -| .. image:: | Witness complex :math:`Wit(W,L)` is a simplicial complex defined on | -| img/Witness_complex_representation.png | two sets of points in :math:`\mathbb{R}^D`:Wit(W,L)` is a simplicial | -| | complex defined on two sets of points in :math:`\mathbb{R}^D`: | -| | | -| | * :math:`W` set of **witnesses** and | -| | * :math:`L \subseteq W` set of **landmarks**. | -| | | -| | The simplices are based on landmarks and a simplex belongs to the | -| | witness complex if and only if it is witnessed, that is: | -| | | -| | :math:`\sigma \subset L` is witnessed if there exists a point | -| | :math:`w \in W` such that w is closer to the vertices of | -| | :math:`\sigma` than other points in :math:`L` and all of its faces | -| | are witnessed as well. | -| | | -| | The data structure is described in | -| | :cite:`boissonnatmariasimplextreealgorithmica`. | -+---------------------------------------------+----------------------------------------------------------------------+ -| :doc:`witness_complex_user` | :doc:`witness_complex_ref` | -+---------------------------------------------+----------------------------------------------------------------------+ diff --git a/src/cython/doc/source/witness_complex_user.rst b/src/cython/doc/source/witness_complex_user.rst deleted file mode 100644 index 604c7357..00000000 --- a/src/cython/doc/source/witness_complex_user.rst +++ /dev/null @@ -1,31 +0,0 @@ -=========================== -Witness complex user manual -=========================== -Definition ----------- - -.. include:: witness_complex_sum.rst - -Implementation --------------- - -The principal class of this module is Gudhi::Witness_complex. - -In both cases, the constructor for this class takes a {witness}x{closest_landmarks} table, where each row represents a -witness and consists of landmarks sorted by distance to this witness. - -.. todo:: - This table can be constructed by two additional classes Landmark_choice_by_furthest_point and - Landmark_choice_by_random_point also included in the module. - -.. figure:: - img/bench_Cy8.png - :align: center - - Running time as function on number of landmarks. - -.. figure:: - img/bench_sphere.png - :align: center - - Running time as function on number of witnesses for |L|=300. |