From 4721085696a8def22da522c32b78748765cbe006 Mon Sep 17 00:00:00 2001 From: vrouvrea Date: Tue, 9 Aug 2016 16:02:23 +0000 Subject: Modifications for sphinx documentation latex support (still pseudo code issue) doctest support for linux Cmake launches make html && make doctest to test the doc git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/ST_cythonize@1427 636b058d-ea47-450e-bf9e-a15bfbe3eedb Former-commit-id: 58de6ec78d4368b99c9a81c9c229c4e7b075835a --- biblio/bibliography.bib | 2 +- src/cython/CMakeLists.txt | 8 +- src/cython/doc/source/alpha_complex_user.rst | 192 ++++++++++++++++++++- src/cython/doc/source/biblio.rst | 10 ++ src/cython/doc/source/conf.py | 1 + src/cython/doc/source/cubical_complex_user.rst | 4 +- src/cython/doc/source/index.rst | 24 +-- .../doc/source/persistent_cohomology_sum.rst | 28 +++ .../doc/source/persistent_cohomology_user.rst | 7 + src/cython/doc/source/simplex_tree_sum.rst | 3 +- src/cython/doc/source/simplex_tree_user.rst | 1 - src/cython/doc/source/witness_complex_ref.rst | 4 +- src/cython/doc/source/witness_complex_user.rst | 4 +- 13 files changed, 256 insertions(+), 32 deletions(-) create mode 100644 src/cython/doc/source/biblio.rst create mode 100644 src/cython/doc/source/persistent_cohomology_sum.rst create mode 100644 src/cython/doc/source/persistent_cohomology_user.rst diff --git a/biblio/bibliography.bib b/biblio/bibliography.bib index 9fc01a5d..bd34f087 100644 --- a/biblio/bibliography.bib +++ b/biblio/bibliography.bib @@ -176,7 +176,7 @@ language={English}, @article{RS62, author={J. B. Rosser and L. Schoenfeld}, title={Approximate Formulas for some Functions of Prime Numbers}, - journal= ijm, + journal= {ijm}, volume= 6, year= 1962, pages={64-94}, diff --git a/src/cython/CMakeLists.txt b/src/cython/CMakeLists.txt index 19289977..9feca6ed 100644 --- a/src/cython/CMakeLists.txt +++ b/src/cython/CMakeLists.txt @@ -95,10 +95,16 @@ if(PYTHON_PATH AND CYTHON_PATH) # User version file(GLOB GUDHI_USER_DOC_IMAGES "${CMAKE_SOURCE_DIR}/doc/*/*.png") file(COPY ${GUDHI_USER_DOC_IMAGES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/img") + # Biblio + file(GLOB GUDHI_BIB_FILES "${CMAKE_SOURCE_DIR}/biblio/*.bib") + file(COPY ${GUDHI_BIB_FILES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/") + # Examples + file(GLOB GUDHI_EXAMPLES_FILES "${CMAKE_SOURCE_DIR}/src/cython/example/*.py") + file(COPY ${GUDHI_EXAMPLES_FILES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/doc/source/") if (UNIX) add_custom_target(html WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc - COMMAND make html) + COMMAND make html && make doctest) else (UNIX) add_custom_target(html WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc diff --git a/src/cython/doc/source/alpha_complex_user.rst b/src/cython/doc/source/alpha_complex_user.rst index ba920fe3..82b99be9 100644 --- a/src/cython/doc/source/alpha_complex_user.rst +++ b/src/cython/doc/source/alpha_complex_user.rst @@ -6,10 +6,192 @@ Definition .. include:: alpha_complex_sum.rst -Alpha_complex is constructing a Simplex_tree using Delaunay Triangulation from -CGAL (the Computational Geometry Algorithms Library). - -The complex is a template class requiring an Epick_d dD Geometry Kernel [16] from CGAL as template parameter. +Alpha_complex is constructing a :doc:`Simplex_tree ` using +`Delaunay Triangulation `_ +:cite:`cgal:hdj-t-15b` from `CGAL `_ (the Computational Geometry Algorithms Library +:cite:`cgal:eb-15b`). Remarks - When Alpha_complex is constructed with an infinite value of alpha, the complex is a Delaunay complex. \ No newline at end of file +^^^^^^^ +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. math:: + \begin{algorithm} + \caption{Filtration value computation algorithm}\label{alpha} + \begin{algorithmic} + \For{i : dimension $\rightarrow$ 0} + \ForAll{$\sigma$ of dimension i} + \If {filtration($\sigma$) is NaN} + \State filtration($\sigma$) = $\alpha^2(\sigma)$ + \EndIf + \ForAll{$\tau$ face of $\sigma$} \Comment{propagate alpha filtration value} + \If {filtration($\tau$) is not NaN} + \State filtration($\tau$) = min (filtration($\tau$), filtration($\sigma$)) + \Else + \If {$\tau$ is not Gabriel for $\sigma$} + \State filtration($\tau$) = filtration($\sigma$) + \EndIf + \EndIf + \EndFor + \EndFor + \EndFor + \State make\_filtration\_non\_decreasing() + \State prune\_above\_filtration() + \end{algorithmic} + \end{algorithm} + +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 `_). + +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 `_). +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(points=[[1, 1], [7, 0], [4, 6], [9, 6], [0, 14], [2, 19], [9, 17]], + 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 new file mode 100644 index 00000000..66709265 --- /dev/null +++ b/src/cython/doc/source/biblio.rst @@ -0,0 +1,10 @@ + + + +.. bibliography:: bibliography.bib + :filter: docnames + :style: alpha + +.. bibliography:: how_to_cite_cgal.bib + :filter: docnames + :style: unsrt diff --git a/src/cython/doc/source/conf.py b/src/cython/doc/source/conf.py index 094020f7..25e77e6d 100755 --- a/src/cython/doc/source/conf.py +++ b/src/cython/doc/source/conf.py @@ -39,6 +39,7 @@ extensions = [ 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', + 'sphinxcontrib.bibtex', ] # Add any paths that contain templates here, relative to this directory. diff --git a/src/cython/doc/source/cubical_complex_user.rst b/src/cython/doc/source/cubical_complex_user.rst index 6ae67940..2efff680 100644 --- a/src/cython/doc/source/cubical_complex_user.rst +++ b/src/cython/doc/source/cubical_complex_user.rst @@ -1,6 +1,6 @@ -========================= +=========================== Cubical complex user manual -========================= +=========================== Definition ---------- diff --git a/src/cython/doc/source/index.rst b/src/cython/doc/source/index.rst index 2b17464a..5245d69d 100644 --- a/src/cython/doc/source/index.rst +++ b/src/cython/doc/source/index.rst @@ -3,9 +3,6 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. toctree:: - :maxdepth: 2 - GUDHI's documentation ##################### @@ -17,10 +14,11 @@ Introduction The Gudhi library (Geometry Understanding in Higher Dimensions) is a generic open source C++ library for Computational Topology and Topological Data -Analysis (TDA). The GUDHI library intends to help the development of new -algorithmic solutions in TDA and their transfer to applications. It provides -robust, efficient, flexible and easy to use implementations of -state-of-the-art algorithms and data structures. +Analysis (`TDA `_). +The GUDHI library intends to help the development of new algorithmic solutions +in TDA and their transfer to applications. It provides robust, efficient, +flexible and easy to use implementations of state-of-the-art algorithms and +data structures. The current release of the GUDHI library includes: @@ -29,8 +27,8 @@ The current release of the GUDHI library includes: * Simplication of simplicial complexes by edge contraction. All data-structures are generic and several of their aspects can be -parameterized via template classes. We refer to [14] for a detailed -description of the design of the library. +parameterized via template classes. We refer to :cite:`gudhilibrary_ICMS14` +for a detailed description of the design of the library. Data structures *************** @@ -62,10 +60,4 @@ Toolbox Persistence cohomology ====================== -===================================== ===================================== ===================================== -:Author: Clément Maria :Introduced in: GUDHI PYTHON 1.4.0 :Copyright: GPL v3 -===================================== ===================================== ===================================== - - - - +.. include:: persistent_cohomology_sum.rst diff --git a/src/cython/doc/source/persistent_cohomology_sum.rst b/src/cython/doc/source/persistent_cohomology_sum.rst new file mode 100644 index 00000000..081399a5 --- /dev/null +++ b/src/cython/doc/source/persistent_cohomology_sum.rst @@ -0,0 +1,28 @@ +===================================== ===================================== ===================================== +: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 new file mode 100644 index 00000000..41b6a3e3 --- /dev/null +++ b/src/cython/doc/source/persistent_cohomology_user.rst @@ -0,0 +1,7 @@ +================================= +Persistent cohomology user manual +================================= +Definition +---------- + +.. include:: persistent_cohomology_sum.rst diff --git a/src/cython/doc/source/simplex_tree_sum.rst b/src/cython/doc/source/simplex_tree_sum.rst index cc02ccc2..ffdb2cf4 100644 --- a/src/cython/doc/source/simplex_tree_sum.rst +++ b/src/cython/doc/source/simplex_tree_sum.rst @@ -7,8 +7,7 @@ | img/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | | | | | | The data structure is described in | -| | `this document `_ | +| | :cite:`boissonnatmariasimplextreealgorithmica` | +-------------------------------------------+----------------------------------------------------------------------+ | :doc:`simplex_tree_user` | :doc:`simplex_tree_ref` | +-------------------------------------------+----------------------------------------------------------------------+ - \ No newline at end of file diff --git a/src/cython/doc/source/simplex_tree_user.rst b/src/cython/doc/source/simplex_tree_user.rst index e1f6e93d..b07bd449 100644 --- a/src/cython/doc/source/simplex_tree_user.rst +++ b/src/cython/doc/source/simplex_tree_user.rst @@ -5,4 +5,3 @@ Definition ---------- .. include:: simplex_tree_sum.rst - diff --git a/src/cython/doc/source/witness_complex_ref.rst b/src/cython/doc/source/witness_complex_ref.rst index 79e39739..c78760cb 100644 --- a/src/cython/doc/source/witness_complex_ref.rst +++ b/src/cython/doc/source/witness_complex_ref.rst @@ -1,6 +1,6 @@ -=============================== +================================ Witness complex reference manual -=============================== +================================ .. autoclass:: gudhi.WitnessComplex :members: diff --git a/src/cython/doc/source/witness_complex_user.rst b/src/cython/doc/source/witness_complex_user.rst index 3b4c3891..698e5441 100644 --- a/src/cython/doc/source/witness_complex_user.rst +++ b/src/cython/doc/source/witness_complex_user.rst @@ -1,6 +1,6 @@ -========================== +=========================== Witness complex user manual -========================== +=========================== Definition ---------- -- cgit v1.2.3