diff options
Diffstat (limited to 'cython/doc')
31 files changed, 199 insertions, 340 deletions
diff --git a/cython/doc/Makefile.in b/cython/doc/Makefile.in deleted file mode 100644 index 526350b3..00000000 --- a/cython/doc/Makefile.in +++ /dev/null @@ -1,44 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = @SPHINX_PATH@ -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -f examples.inc - rm -rf $(BUILDDIR)/* - -# GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean) - -html: - ./generate_examples.py - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/cython/doc/_templates/layout.html b/cython/doc/_templates/layout.html index b11c1236..243f33c6 100644 --- a/cython/doc/_templates/layout.html +++ b/cython/doc/_templates/layout.html @@ -65,6 +65,7 @@ {#- old style sidebars: using blocks -- should be deprecated #} {%- block sidebartoc %} <h2><a href="index.html">GUDHI</a></h2> +<h2><a href="fileformats.html">File formats</a></h2> <h2><a href="installation.html">GUDHI installation</a></h2> <h2><a href="citation.html">Acknowledging the GUDHI library</a></h2> <h2><a href="genindex.html">Index</a></h2> diff --git a/cython/doc/alpha_complex_sum.rst b/cython/doc/alpha_complex_sum.rst index 8437e901..1680a712 100644 --- a/cython/doc/alpha_complex_sum.rst +++ b/cython/doc/alpha_complex_sum.rst @@ -5,7 +5,7 @@ +----------------------------------------------------------------+------------------------------------------------------------------------+ | .. figure:: | Alpha_complex is a simplicial complex constructed from the finite | -| img/alpha_complex_representation.png | cells of a Delaunay Triangulation. | +| ../../doc/Alpha_complex/alpha_complex_representation.png | cells of a Delaunay Triangulation. | | :alt: Alpha complex representation | | | :figclass: align-center | The filtration value of each simplex is computed as the square of the | | | circumradius of the simplex if the circumsphere is empty (the simplex | @@ -16,7 +16,7 @@ | | complex. | | | | | | This package requires having CGAL version 4.7 or higher (4.8.1 is | -| | advised for better perfomances). | +| | advised for better performance). | +----------------------------------------------------------------+------------------------------------------------------------------------+ | :doc:`alpha_complex_user` | :doc:`alpha_complex_ref` | +----------------------------------------------------------------+------------------------------------------------------------------------+ diff --git a/cython/doc/alpha_complex_user.rst b/cython/doc/alpha_complex_user.rst index e8268ef1..db7edd6f 100644 --- a/cython/doc/alpha_complex_user.rst +++ b/cython/doc/alpha_complex_user.rst @@ -75,7 +75,7 @@ In order to build the alpha complex, first, a Simplex tree is built from the cel (The filtration value is set to NaN, which stands for unknown value): .. figure:: - img/alpha_complex_doc.png + ../../doc/Alpha_complex/alpha_complex_doc.png :figclass: align-center :alt: Simplex tree structure construction example @@ -112,7 +112,7 @@ computes the filtration value of the triangle, and then propagates the filtratio here: .. figure:: - img/alpha_complex_doc_420.png + ../../doc/Alpha_complex/alpha_complex_doc_420.png :figclass: align-center :alt: Filtration value propagation example @@ -142,7 +142,7 @@ 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 `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. @@ -158,7 +158,8 @@ Then, it is asked to display information about the alpha complex: .. testcode:: import gudhi - alpha_complex = gudhi.AlphaComplex(off_file='alphacomplexdoc.off') + alpha_complex = gudhi.AlphaComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/alphacomplexdoc.off') simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=59.0) result_str = 'Alpha complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ @@ -200,6 +201,6 @@ the program output is: CGAL citations ============== -.. bibliography:: how_to_cite_cgal.bib +.. bibliography:: ../../biblio/how_to_cite_cgal.bib :filter: docnames :style: unsrt diff --git a/cython/doc/bottleneck_distance_sum.rst b/cython/doc/bottleneck_distance_sum.rst index 5c475d0d..030fad9e 100644 --- a/cython/doc/bottleneck_distance_sum.rst +++ b/cython/doc/bottleneck_distance_sum.rst @@ -5,7 +5,7 @@ +-----------------------------------------------------------------+----------------------------------------------------------------------+ | .. figure:: | Bottleneck distance measures the similarity between two persistence | -| img/perturb_pd.png | diagrams. It's the shortest distance b for which there exists a | +| ../../doc/Bottleneck_distance/perturb_pd.png | diagrams. It's the shortest distance b for which there exists a | | :figclass: align-center | perfect matching between the points of the two diagrams (+ all the | | | diagonal points) such that any couple of matched points are at | | Bottleneck distance is the length of | distance at most b. | diff --git a/cython/doc/bottleneck_distance_user.rst b/cython/doc/bottleneck_distance_user.rst index 0066992f..7692dce2 100644 --- a/cython/doc/bottleneck_distance_user.rst +++ b/cython/doc/bottleneck_distance_user.rst @@ -25,7 +25,7 @@ This example computes the bottleneck distance from 2 persistence diagrams: message = "Bottleneck distance approximation=" + '%.2f' % gudhi.bottleneck_distance(diag1, diag2, 0.1) print(message) - message = "Bottleneck distance exact value=" + '%.2f' % gudhi.bottleneck_distance(diag1, diag2, 0) + message = "Bottleneck distance value=" + '%.2f' % gudhi.bottleneck_distance(diag1, diag2) print(message) The output is: @@ -33,4 +33,4 @@ The output is: .. testoutput:: Bottleneck distance approximation=0.81 - Bottleneck distance exact value=0.75 + Bottleneck distance value=0.75 diff --git a/cython/doc/citation.rst b/cython/doc/citation.rst index 6cdfb7cc..f4fdf83b 100644 --- a/cython/doc/citation.rst +++ b/cython/doc/citation.rst @@ -12,4 +12,4 @@ Manual, as well as for publications directly related to the GUDHI library. GUDHI bibtex ************ -.. literalinclude:: how_to_cite_gudhi.bib +.. literalinclude:: ../../biblio/how_to_cite_gudhi.bib diff --git a/cython/doc/conf.py b/cython/doc/conf.py index 42bfd59c..19a880d4 100755 --- a/cython/doc/conf.py +++ b/cython/doc/conf.py @@ -21,7 +21,7 @@ import os #sys.path.insert(0, os.path.abspath('.')) # Path to Gudhi.so from source path -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ @@ -58,18 +58,20 @@ source_suffix = '.rst' # The master toctree document. master_doc = 'index' +import gudhi + # General information about the project. -project = u'GUDHI' -copyright = u'2016, GUDHI Editorial Board' +project = gudhi.__name__ +copyright = gudhi.__copyright__ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2.0' +version = gudhi.__version__ # The full version, including alpha/beta/rc tags. -release = '2.0.0' +#release = '2.0.1-rc1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -198,81 +200,3 @@ html_static_path = ['_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'GUDHIdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ('index', 'GUDHI.tex', u'GUDHI Documentation', - u'Vincent Rouvreau', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'gudhi', u'GUDHI Documentation', - [u'Vincent Rouvreau'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'GUDHI', u'GUDHI Documentation', - u'Vincent Rouvreau', 'GUDHI', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False diff --git a/cython/doc/cubical_complex_sum.rst b/cython/doc/cubical_complex_sum.rst index 3ddf6375..280ad0e0 100644 --- a/cython/doc/cubical_complex_sum.rst +++ b/cython/doc/cubical_complex_sum.rst @@ -2,14 +2,14 @@ :Author: Pawel Dlotko :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 ================================================================= =================================== =================================== -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| .. figure:: | The cubical complex is an example of a structured complex useful in | -| img/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image | -| :alt: Cubical complex representation | analysis. | -| :figclass: align-center | | -| | | -| Cubical complex representation | | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | -| | * :doc:`periodic_cubical_complex_ref` | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ ++--------------------------------------------------------------------------+----------------------------------------------------------------------+ +| .. figure:: | The cubical complex is an example of a structured complex useful in | +| ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image | +| :alt: Cubical complex representation | analysis. | +| :figclass: align-center | | +| | | +| Cubical complex representation | | ++--------------------------------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | +| | * :doc:`periodic_cubical_complex_ref` | ++--------------------------------------------------------------------------+----------------------------------------------------------------------+ diff --git a/cython/doc/cubical_complex_user.rst b/cython/doc/cubical_complex_user.rst index 344b9554..2bfac62a 100644 --- a/cython/doc/cubical_complex_user.rst +++ b/cython/doc/cubical_complex_user.rst @@ -59,7 +59,7 @@ directions, allows to determine, dimension, neighborhood, boundary and coboundar :math:`C \in \mathcal{K}`. .. figure:: - img/Cubical_complex_representation.png + ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png :alt: Cubical complex. :figclass: align-center @@ -87,7 +87,7 @@ in the example below). Next, in lexicographical order, the filtration of top dim 20 4 7 6 5 in the example below). .. figure:: - img/exampleBitmap.png + ../../doc/Bitmap_cubical_complex/exampleBitmap.png :alt: Example of a input data. :figclass: align-center @@ -95,14 +95,15 @@ in the example below). Next, in lexicographical order, the filtration of top dim The input file for the following complex is: -.. literalinclude:: cubicalcomplexdoc.txt +.. literalinclude:: ../../data/bitmap/cubicalcomplexdoc.txt -.. centered:: cubicalcomplexdoc.txt +.. centered:: ../../data/bitmap/cubicalcomplexdoc.txt .. testcode:: import gudhi - cubical_complex = gudhi.CubicalComplex(perseus_file='cubicalcomplexdoc.txt') + cubical_complex = gudhi.CubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ + '/data/bitmap/cubicalcomplexdoc.txt') result_str = 'Cubical complex is of dimension ' + repr(cubical_complex.dimension()) + ' - ' + \ repr(cubical_complex.num_simplices()) + ' simplices.' print(result_str) @@ -127,16 +128,17 @@ complex with periodic boundary conditions. One can also use Perseus style input 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 +.. literalinclude:: ../../data/bitmap/periodiccubicalcomplexdoc.txt -.. centered:: periodiccubicalcomplexdoc.txt +.. centered:: ../../data/bitmap/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='periodiccubicalcomplexdoc.txt') + periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ + '/data/bitmap/periodiccubicalcomplexdoc.txt') result_str = 'Periodic cubical complex is of dimension ' + repr(periodic_cc.dimension()) + ' - ' + \ repr(periodic_cc.num_simplices()) + ' simplices.' print(result_str) @@ -155,6 +157,6 @@ End user programs are available in cython/example/ folder. Bibliography ============ -.. bibliography:: bibliography.bib +.. bibliography:: ../../bibliography.bib :filter: docnames :style: unsrt diff --git a/cython/doc/examples.rst b/cython/doc/examples.rst index a89e0596..1e596e18 100644 --- a/cython/doc/examples.rst +++ b/cython/doc/examples.rst @@ -1,4 +1,21 @@ Examples ######## -.. include:: examples.inc +.. only:: builder_html + + * :download:`rips_complex_from_points_example.py <../example/rips_complex_from_points_example.py>` + * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>` + * :download:`simplex_tree_example.py <../example/simplex_tree_example.py>` + * :download:`alpha_rips_persistence_bottleneck_distance.py <../example/alpha_rips_persistence_bottleneck_distance.py>` + * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>` + * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>` + * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>` + * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>` + * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>` + * :download:`witness_complex_from_nearest_landmark_table.py <../example/witness_complex_from_nearest_landmark_table.py>` + * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` + * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` + * :download:`rips_complex_diagram_persistence_from_off_file_example.py <../example/rips_complex_diagram_persistence_from_off_file_example.py>` + * :download:`rips_complex_diagram_persistence_from_distance_matrix_file_example.py <../example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py>` + * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>` + * :download:`random_cubical_complex_persistence_example.py <../example/random_cubical_complex_persistence_example.py>` diff --git a/cython/doc/fileformats.rst b/cython/doc/fileformats.rst new file mode 100644 index 00000000..156ef4e4 --- /dev/null +++ b/cython/doc/fileformats.rst @@ -0,0 +1,33 @@ +File formats +############ + +Persistence Diagram +******************* + +Such a file, whose extension is usually ``.pers``, contains a list of +persistence intervals. + +Lines starting with ``#`` are ignored (comments). + +Other lines might contain 2, 3 or 4 values (the number of values on each line +must be the same for all lines):: + + [[field] dimension] birth death + +Here is a simple sample file:: + + # Persistence diagram example + 2 2.7 3.7 + 2 9.6 14. + # Some comments + 3 34.2 34.974 + 4 3. inf + +Other sample files can be found in the data/persistence_diagram folder. + +Such files can be generated with +:meth:`gudhi.SimplexTree.write_persistence_diagram`, read with +:meth:`gudhi.read_persistence_intervals_grouped_by_dimension`, or +:meth:`gudhi.read_persistence_intervals_in_dimension` and displayed with +:meth:`gudhi.plot_persistence_barcode` or +:meth:`gudhi.plot_persistence_diagram`. diff --git a/cython/doc/generate_examples.py b/cython/doc/generate_examples.py deleted file mode 100755 index d64d506c..00000000 --- a/cython/doc/generate_examples.py +++ /dev/null @@ -1,43 +0,0 @@ -#!/usr/bin/env python - -from os import listdir - -"""This file is part of the Gudhi Library. The Gudhi library - (Geometric Understanding in Higher Dimensions) is a generic C++ - library for computational topology. - - Author(s): Vincent Rouvreau - - Copyright (C) 2017 INRIA - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see <http://www.gnu.org/licenses/>. -""" - -__author__ = "Vincent Rouvreau" -__copyright__ = "Copyright (C) 2017 INRIA" -__license__ = "GPL v3" - -""" -generate_examples.py generates examples.inc to be included in examples.rst. -Refer to Makefile and make.bat to see if it is correctly launched. -""" - -output_file = open('examples.inc','w') - -output_file.write('.. only:: builder_html\n\n') - -for file in listdir('../example/'): - output_file.write(" * :download:`" + file + " <../example/" + file + ">`\n") - -output_file.close() diff --git a/cython/doc/index.rst b/cython/doc/index.rst index 94dbc65a..3945d72a 100644 --- a/cython/doc/index.rst +++ b/cython/doc/index.rst @@ -1,15 +1,17 @@ -GUDHI documentation -################### +GUDHI Python module documentation +################################# -.. image:: img/Gudhi_banner.png - :align: center +.. figure:: + ../../doc/common/Gudhi_banner.png + :alt: Gudhi banner + :figclass: align-center Introduction ************ -The Gudhi library (Geometry Understanding in Higher Dimensions) is a generic -open source `C++ library <http://gudhi.gforge.inria.fr/doc/latest/>`_, with a -`Python interface <http://gudhi.gforge.inria.fr/python/latest/>`_, for +The Python interface for the Gudhi library (Geometry Understanding in Higher +Dimensions) is a generic open source +`Python module <http://gudhi.gforge.inria.fr/python/latest/>`_, for Computational Topology and Topological Data Analysis (`TDA <https://en.wikipedia.org/wiki/Topological_data_analysis>`_). The GUDHI library intends to help the development of new algorithmic solutions @@ -20,12 +22,11 @@ data structures. The current release of the GUDHI library includes: * Data structures to represent, construct and manipulate simplicial complexes. -* Algorithms to compute persistent homology and multi-field persistent homology. -* Simplication of simplicial complexes by edge contraction. +* Simplification of simplicial complexes by edge contraction. +* Algorithms to compute persistent homology and bottleneck distance. -All data-structures are generic and several of their aspects can be -parameterized via template classes. We refer to :cite:`gudhilibrary_ICMS14` -for a detailed description of the design of the library. +We refer to :cite:`gudhilibrary_ICMS14` for a detailed description of the +design of the library. Data structures *************** @@ -82,6 +83,6 @@ Persistence graphical tools Bibliography ************ -.. bibliography:: bibliography.bib +.. bibliography:: ../../biblio/bibliography.bib :filter: docnames :style: unsrt diff --git a/cython/doc/installation.rst b/cython/doc/installation.rst index f98a5039..c182f176 100644 --- a/cython/doc/installation.rst +++ b/cython/doc/installation.rst @@ -68,31 +68,32 @@ The :doc:`Alpha complex </alpha_complex_user>`, C++ library which provides easy access to efficient and reliable geometric algorithms. -Having CGAL version 4.6.0 or higher installed is recommended. The procedure to -install this library according to your operating system is detailed +Having CGAL, the Computational Geometry Algorithms Library, version 4.7.0 or +higher installed is recommended. The procedure to install this library +according to your operating system is detailed `here <http://doc.cgal.org/latest/Manual/installation.html>`_. -The following examples require the Computational Geometry Algorithms Library: - -.. only:: builder_html - - * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` - * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` - -The following example requires CGAL version ≥ 4.7.0: +The following examples requires CGAL version ≥ 4.7.0: .. only:: builder_html * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>` * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>` -The following example requires CGAL version ≥ 4.8.0: +The following examples requires CGAL version ≥ 4.8.0: .. only:: builder_html * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>` * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>` +The following examples requires CGAL version ≥ 4.8.1: + +.. only:: builder_html + + * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` + * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` + Eigen3 ====== diff --git a/cython/doc/make.bat.in b/cython/doc/make.bat.in deleted file mode 100644 index ff1a6d56..00000000 --- a/cython/doc/make.bat.in +++ /dev/null @@ -1,67 +0,0 @@ -@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=@SPHINX_PATH@
-)
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
- set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
- set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
- :help
- echo.Please use `make ^<target^>` where ^<target^> is one of
- echo. html to make standalone HTML files
- echo. doctest to run all doctests embedded in the documentation if enabled
- goto end
-)
-
-if "%1" == "clean" (
- del examples.inc
- for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
- del /q /s %BUILDDIR%\*
- goto end
-)
-
-
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
- exit /b 1
-)
-
-:: GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean)
-
-if "%1" == "html" (
- generate_examples.py
- %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
- if errorlevel 1 exit /b 1
- echo.
- echo.Build finished. The HTML pages are in %BUILDDIR%/html.
- goto end
-)
-
-if "%1" == "doctest" (
- %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
- if errorlevel 1 exit /b 1
- echo.
- echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
- goto end
-)
-
-:end
diff --git a/cython/doc/persistence_graphical_tools_user.rst b/cython/doc/persistence_graphical_tools_user.rst index cae18323..9033331f 100644 --- a/cython/doc/persistence_graphical_tools_user.rst +++ b/cython/doc/persistence_graphical_tools_user.rst @@ -14,12 +14,14 @@ This function is useful to show the color palette values of dimension: .. testcode:: import gudhi - gudhi.show_palette_values(alpha=1.0) + plt = gudhi.show_palette_values(alpha=1.0) + plt.show() .. plot:: import gudhi - gudhi.show_palette_values(alpha=1.0) + plt = gudhi.show_palette_values(alpha=1.0) + plt.show() Show persistence as a barcode ----------------------------- @@ -30,17 +32,22 @@ This function can display the persistence result as a barcode: import gudhi - periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='3d_torus.txt') + periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ + '/data/bitmap/3d_torus.txt') diag = periodic_cc.persistence() - gudhi.plot_persistence_barcode(diag) + plt = gudhi.plot_persistence_barcode(diag) + plt.show() .. plot:: import gudhi - periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='3d_torus.txt') + periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ + '/data/bitmap/3d_torus.txt') diag = periodic_cc.persistence() - gudhi.plot_persistence_barcode(diag) + print("diag = ", diag) + plt = gudhi.plot_persistence_barcode(diag) + plt.show() Show persistence as a diagram ----------------------------- @@ -51,16 +58,20 @@ This function can display the persistence result as a diagram: import gudhi - rips_complex = gudhi.RipsComplex(off_file='tore3D_300.off', max_edge_length=2.0) + rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/tore3D_1307.off', max_edge_length=0.2) simplex_tree = rips_complex.create_simplex_tree(max_dimension=3) diag = simplex_tree.persistence() - gudhi.plot_persistence_diagram(diag) + plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13) + plt.show() .. plot:: import gudhi - rips_complex = gudhi.RipsComplex(off_file='tore3D_300.off', max_edge_length=2.0) + rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/tore3D_1307.off', max_edge_length=0.2) simplex_tree = rips_complex.create_simplex_tree(max_dimension=3) diag = simplex_tree.persistence() - gudhi.plot_persistence_diagram(diag) + plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13) + plt.show() diff --git a/cython/doc/persistent_cohomology_sum.rst b/cython/doc/persistent_cohomology_sum.rst index d1f79cb4..a26df1dc 100644 --- a/cython/doc/persistent_cohomology_sum.rst +++ b/cython/doc/persistent_cohomology_sum.rst @@ -4,7 +4,7 @@ +-----------------------------------------------------------------+-----------------------------------------------------------------------+ | .. figure:: | The theory of homology consists in attaching to a topological space | -| img/3DTorus_poch.png | a sequence of (homology) groups, capturing global topological | +| ../../doc/Persistent_cohomology/3DTorus_poch.png | a sequence of (homology) groups, capturing global topological | | :figclass: align-center | features like connected components, holes, cavities, etc. Persistent | | | homology studies the evolution -- birth, life and death -- of these | | Rips Persistent Cohomology on a 3D | features when the topological space is changing. Consequently, the | diff --git a/cython/doc/persistent_cohomology_user.rst b/cython/doc/persistent_cohomology_user.rst index 72f1a7f7..bf90c163 100644 --- a/cython/doc/persistent_cohomology_user.rst +++ b/cython/doc/persistent_cohomology_user.rst @@ -109,6 +109,6 @@ We provide several example files: run these examples with -h for details on thei Bibliography ============ -.. bibliography:: bibliography.bib +.. bibliography:: ../../biblio/bibliography.bib :filter: docnames :style: unsrt diff --git a/cython/doc/pyplots/barcode_persistence.py b/cython/doc/pyplots/barcode_persistence.py index c06ac5a7..de33d506 100755 --- a/cython/doc/pyplots/barcode_persistence.py +++ b/cython/doc/pyplots/barcode_persistence.py @@ -1,5 +1,7 @@ import gudhi -periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='../3d_torus.txt') +periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ + '/data/bitmap/3d_torus.txt') diag = periodic_cc.persistence() -gudhi.plot_persistence_barcode(diag) +plt = gudhi.plot_persistence_barcode(diag) +plt.show() diff --git a/cython/doc/pyplots/diagram_persistence.py b/cython/doc/pyplots/diagram_persistence.py index b4714fe3..c2fbf801 100755 --- a/cython/doc/pyplots/diagram_persistence.py +++ b/cython/doc/pyplots/diagram_persistence.py @@ -1,5 +1,8 @@ import gudhi -alpha_complex = gudhi.AlphaComplex(off_file='../tore3D_300.off') -diag = alpha_complex.persistence() -gudhi.plot_persistence_diagram(diag) +rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/tore3D_1307.off', max_edge_length=0.2) +simplex_tree = rips_complex.create_simplex_tree(max_dimension=3) +diag = simplex_tree.persistence() +plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13) +plt.show() diff --git a/cython/doc/pyplots/show_palette_values.py b/cython/doc/pyplots/show_palette_values.py index e72a55fd..fdf9645f 100755 --- a/cython/doc/pyplots/show_palette_values.py +++ b/cython/doc/pyplots/show_palette_values.py @@ -1,2 +1,3 @@ import gudhi -gudhi.show_palette_values(alpha=1.0) +plt = gudhi.show_palette_values(alpha=1.0) +plt.show() diff --git a/cython/doc/python3-sphinx-build b/cython/doc/python3-sphinx-build.py index 44b94169..44b94169 100755 --- a/cython/doc/python3-sphinx-build +++ b/cython/doc/python3-sphinx-build.py diff --git a/cython/doc/reader_utils_ref.rst b/cython/doc/reader_utils_ref.rst new file mode 100644 index 00000000..9c1ea6fc --- /dev/null +++ b/cython/doc/reader_utils_ref.rst @@ -0,0 +1,11 @@ +============================= +Reader utils reference manual +============================= + +.. autofunction:: gudhi.read_off + +.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file + +.. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension + +.. autofunction:: gudhi.read_persistence_intervals_in_dimension diff --git a/cython/doc/rips_complex_sum.rst b/cython/doc/rips_complex_sum.rst index 2b65fc19..5616bfa9 100644 --- a/cython/doc/rips_complex_sum.rst +++ b/cython/doc/rips_complex_sum.rst @@ -4,7 +4,7 @@ +----------------------------------------------------------------+------------------------------------------------------------------------+ | .. figure:: | Rips complex is a simplicial complex constructed from a one skeleton | -| img/rips_complex_representation.png | graph. | +| ../../doc/Rips_complex/rips_complex_representation.png | graph. | | :figclass: align-center | | | | The filtration value of each edge is computed from a user-given | | Rips complex representation | distance function and is inserted until a user-given threshold | diff --git a/cython/doc/rips_complex_user.rst b/cython/doc/rips_complex_user.rst index f9760976..96ba9944 100644 --- a/cython/doc/rips_complex_user.rst +++ b/cython/doc/rips_complex_user.rst @@ -26,7 +26,7 @@ structure, and then expands the simplicial complex when required. Vertex name correspond to the index of the point in the given range (aka. the point cloud). .. figure:: - img/rips_complex_representation.png + ../../doc/Rips_complex/rips_complex_representation.png :align: center Rips-complex one skeleton graph representation @@ -101,7 +101,8 @@ Finally, it is asked to display information about the Rips complex. .. testcode:: import gudhi - rips_complex = gudhi.RipsComplex(off_file='alphacomplexdoc.off', max_edge_length=12.0) + rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/alphacomplexdoc.off', max_edge_length=12.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ @@ -205,7 +206,8 @@ Finally, it is asked to display information about the Rips complex. .. testcode:: import gudhi - rips_complex = gudhi.RipsComplex(csv_file='full_square_distance_matrix.csv', max_edge_length=12.0) + rips_complex = gudhi.RipsComplex(csv_file=gudhi.__root_source_dir__ + \ + '/data/distance_matrix/full_square_distance_matrix.csv', max_edge_length=12.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ diff --git a/cython/doc/simplex_tree_sum.rst b/cython/doc/simplex_tree_sum.rst index 3174fb62..fb0e54c1 100644 --- a/cython/doc/simplex_tree_sum.rst +++ b/cython/doc/simplex_tree_sum.rst @@ -4,7 +4,7 @@ +----------------------------------------------------------------+------------------------------------------------------------------------+ | .. figure:: | The simplex tree is an efficient and flexible data structure for | -| img/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | +| ../../doc/Simplex_tree/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | | :alt: Simplex tree representation | | | :figclass: align-center | The data structure is described in | | | :cite:`boissonnatmariasimplextreealgorithmica` | diff --git a/cython/doc/tangential_complex_sum.rst b/cython/doc/tangential_complex_sum.rst index 2b05bc10..72b4d7ba 100644 --- a/cython/doc/tangential_complex_sum.rst +++ b/cython/doc/tangential_complex_sum.rst @@ -5,10 +5,10 @@ +----------------------------------------------------------------+------------------------------------------------------------------------+ | .. figure:: | A Tangential Delaunay complex is a simplicial complex designed to | -| img/tc_examples.png | reconstruct a :math:`k`-dimensional manifold embedded in :math:`d`- | +| ../../doc/Tangential_complex/tc_examples.png | reconstruct a :math:`k`-dimensional manifold embedded in :math:`d`- | | :figclass: align-center | dimensional Euclidean space. The input is a point sample coming from | | | an unknown manifold. The running time depends only linearly on the | -| **Tangential complex representation** | extrinsic dimension :math:`d` and exponentially on the intrinsic | +| Tangential complex representation | extrinsic dimension :math:`d` and exponentially on the intrinsic | | | dimension :math:`k`. | +----------------------------------------------------------------+------------------------------------------------------------------------+ | :doc:`tangential_complex_user` | :doc:`tangential_complex_ref` | diff --git a/cython/doc/tangential_complex_user.rst b/cython/doc/tangential_complex_user.rst index 03f9fea6..efa6d7ce 100644 --- a/cython/doc/tangential_complex_user.rst +++ b/cython/doc/tangential_complex_user.rst @@ -22,7 +22,7 @@ Let us start with the description of the Tangential complex of a simple example, with :math:`k = 1` and :math:`d = 2`. The input data is 4 points :math:`P` located on a curve embedded in 2D. -.. figure:: img/tc_example_01.png +.. figure:: ../../doc/Tangential_complex/tc_example_01.png :alt: The input :figclass: align-center @@ -31,7 +31,7 @@ example, with :math:`k = 1` and :math:`d = 2`. The input data is 4 points For each point :math:`p`, estimate its tangent subspace :math:`T_p` (e.g. using PCA). -.. figure:: img/tc_example_02.png +.. figure:: ../../doc/Tangential_complex/tc_example_02.png :alt: The estimated normals :figclass: align-center @@ -42,7 +42,7 @@ Let us add the Voronoi diagram of the points in orange. For each point :math:`p`, construct its star in the Delaunay triangulation of :math:`P` restricted to :math:`T_p`. -.. figure:: img/tc_example_03.png +.. figure:: ../../doc/Tangential_complex/tc_example_03.png :alt: The Voronoi diagram :figclass: align-center @@ -62,7 +62,7 @@ simplex is not in the star of all its vertices. Let us take the same example. -.. figure:: img/tc_example_07_before.png +.. figure:: ../../doc/Tangential_complex/tc_example_07_before.png :alt: Before :figclass: align-center @@ -70,7 +70,7 @@ Let us take the same example. Let us slightly move the tangent subspace :math:`T_q` -.. figure:: img/tc_example_07_after.png +.. figure:: ../../doc/Tangential_complex/tc_example_07_after.png :alt: After :figclass: align-center @@ -79,7 +79,7 @@ Let us slightly move the tangent subspace :math:`T_q` Now, the star of :math:`Q` contains :math:`QP`, but the star of :math:`P` does not contain :math:`QP`. We have an inconsistency. -.. figure:: img/tc_example_08.png +.. figure:: ../../doc/Tangential_complex/tc_example_08.png :alt: After :figclass: align-center @@ -122,7 +122,8 @@ This example builds the Tangential complex of point set read in an OFF file. .. testcode:: import gudhi - tc = gudhi.TangentialComplex(off_file='alphacomplexdoc.off') + tc = gudhi.TangentialComplex(off_file=gudhi.__root_source_dir__ + \ + '/data/points/alphacomplexdoc.off') result_str = 'Tangential contains ' + repr(tc.num_simplices()) + \ ' simplices - ' + repr(tc.num_vertices()) + ' vertices.' print(result_str) @@ -190,6 +191,6 @@ The output is: Bibliography ============ -.. bibliography:: bibliography.bib +.. bibliography:: ../../biblio/bibliography.bib :filter: docnames :style: unsrt diff --git a/cython/doc/witness_complex_sum.rst b/cython/doc/witness_complex_sum.rst index b65522ba..a8a126a0 100644 --- a/cython/doc/witness_complex_sum.rst +++ b/cython/doc/witness_complex_sum.rst @@ -3,15 +3,17 @@ :Euclidean version requires: CGAL :math:`\geq` 4.6.0 Eigen3 ================================================================= =================================== =================================== -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| .. 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`. | -| | | -| | The data structure is described in | -| | :cite:`boissonnatmariasimplextreealgorithmica`. | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| :doc:`witness_complex_user` | * :doc:`witness_complex_ref` | -| | * :doc:`strong_witness_complex_ref` | -| | * :doc:`euclidean_witness_complex_ref` | -| | * :doc:`euclidean_strong_witness_complex_ref` | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ ++-------------------------------------------------------------------+----------------------------------------------------------------------+ +| .. figure:: | Witness complex :math:`Wit(W,L)` is a simplicial complex defined on | +| ../../doc/Witness_complex/Witness_complex_representation.png | two sets of points in :math:`\mathbb{R}^D`. | +| :alt: Witness complex representation | | +| :figclass: align-center | The data structure is described in | +| | :cite:`boissonnatmariasimplextreealgorithmica`. | +| | | +| Witness complex representation | | ++-------------------------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`witness_complex_user` | * :doc:`witness_complex_ref` | +| | * :doc:`strong_witness_complex_ref` | +| | * :doc:`euclidean_witness_complex_ref` | +| | * :doc:`euclidean_strong_witness_complex_ref` | ++-------------------------------------------------------------------+----------------------------------------------------------------------+ diff --git a/cython/doc/witness_complex_user.rst b/cython/doc/witness_complex_user.rst index aa9cbb2c..29413269 100644 --- a/cython/doc/witness_complex_user.rst +++ b/cython/doc/witness_complex_user.rst @@ -33,7 +33,7 @@ Both definitions can be relaxed by a real value :math:`\alpha`: which leads to definitions of **weak relaxed witness complex** (or just relaxed witness complex for short) and **strong relaxed witness complex** respectively. -.. figure:: img/swit.svg +.. figure:: ../../doc/Witness_complex/swit.svg :alt: Strongly witnessed simplex :figclass: align-center @@ -126,6 +126,6 @@ Here is an example of constructing a strong witness complex filtration and compu Bibliography ============ -.. bibliography:: bibliography.bib +.. bibliography:: ../../biblio/bibliography.bib :filter: docnames :style: unsrt |