Merge remote-tracking branch 'origin/master' into tomato2

11 files changed, 64 insertions, 48 deletions

diff --git a/src/python/doc/alpha_complex_sum.inc b/src/python/doc/alpha_complex_sum.inc
index 3aba0d71..aeab493f 100644
--- a/src/python/doc/alpha_complex_sum.inc
+++ b/src/python/doc/alpha_complex_sum.inc
@@ -3,15 +3,13 @@
 
    +----------------------------------------------------------------+-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
    | .. figure::                                                    | Alpha complex is a simplicial complex constructed from the finite       | :Author: Vincent Rouvreau                                                                                                 |
-   |      ../../doc/Alpha_complex/alpha_complex_representation.png  | cells of a Delaunay Triangulation.                                      |                                                                                                                           |
-   |      :alt: Alpha complex representation                        |                                                                         | :Since: GUDHI 2.0.0                                                                                                       |
-   |      :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       | :License: MIT (`GPL v3 </licensing/>`_)                                                                                   |
-   |                                                                | simplex is then said to be Gabriel), and as the minimum of the          |                                                                                                                           |
-   |                                                                | filtration values of the codimension 1 cofaces that make it not         | :Requires: `Eigen <installation.html#eigen>`_ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`_ :math:`\geq` 4.11.0 |
-   |                                                                | Gabriel otherwise.                                                      |                                                                                                                           |
+   |      ../../doc/Alpha_complex/alpha_complex_representation.png  | cells of a Delaunay Triangulation. It has the same persistent homology  |                                                                                                                           |
+   |      :alt: Alpha complex representation                        | as the Čech complex and is significantly smaller.                       | :Since: GUDHI 2.0.0                                                                                                       |
+   |      :figclass: align-center                                   |                                                                         |                                                                                                                           |
+   |                                                                |                                                                         | :License: MIT (`GPL v3 </licensing/>`_)                                                                                   |
+   |                                                                |                                                                         |                                                                                                                           |
+   |                                                                |                                                                         | :Requires: `Eigen <installation.html#eigen>`_ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`_ :math:`\geq` 4.11.0 |
    |                                                                |                                                                         |                                                                                                                           |
-   |                                                                | For performances reasons, it is advised to use CGAL :math:`\geq` 5.0.0. |                                                                                                                           |
    +----------------------------------------------------------------+-------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
    | * :doc:`alpha_complex_user`                                    | * :doc:`alpha_complex_ref`                                                                                                                                                                          |
    +----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/src/python/doc/alpha_complex_user.rst b/src/python/doc/alpha_complex_user.rst
index d49f45b4..097470c1 100644
--- a/src/python/doc/alpha_complex_user.rst
+++ b/src/python/doc/alpha_complex_user.rst
@@ -9,15 +9,33 @@ Definition
 
 .. include:: alpha_complex_sum.inc
 
-`AlphaComplex` is constructing a :doc:`SimplexTree <simplex_tree_ref>` using
+:doc:`AlphaComplex <alpha_complex_ref>` is constructing a :doc:`SimplexTree <simplex_tree_ref>` using
 `Delaunay Triangulation  <http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations>`_
 :cite:`cgal:hdj-t-19b` from the `Computational Geometry Algorithms Library <http://www.cgal.org/>`_
 :cite:`cgal:eb-19b`.
 
 Remarks
 ^^^^^^^
-When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha^2`,
-the complex is a Delaunay complex (with special filtration values).
+* When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha^2`, the complex is a Delaunay
+  complex (with special filtration values). The Delaunay complex without filtration values is also available by
+  passing :code:`default_filtration_value = True` to :func:`~gudhi.AlphaComplex.create_simplex_tree`.
+* For people only interested in the topology of the Alpha complex (for instance persistence), Alpha complex is
+  equivalent to the `Čech complex <https://gudhi.inria.fr/doc/latest/group__cech__complex.html>`_ and much smaller if
+  you do not bound the radii. `Čech complex <https://gudhi.inria.fr/doc/latest/group__cech__complex.html>`_ can still
+  make sense in higher dimension precisely because you can bound the radii.
+* Using the default :code:`precision = 'safe'` makes the construction safe.
+  If you pass :code:`precision = 'exact'` to :func:`~gudhi.AlphaComplex.__init__`, the filtration values are the exact
+  ones converted to float. This can be very slow.
+  If you pass :code:`precision = 'safe'` (the default), the filtration values are only
+  guaranteed to have a small multiplicative error compared to the exact value.
+  A drawback, when computing persistence, is that an empty exact interval [10^12,10^12] may become a
+  non-empty approximate interval [10^12,10^12+10^6].
+  Using :code:`precision = 'fast'` makes the computations slightly faster, and the combinatorics are still exact, but
+  the computation of filtration values can exceptionally be arbitrarily bad. In all cases, we still guarantee that the
+  output is a valid filtration (faces have a filtration value no larger than their cofaces).
+* For performances reasons, it is advised to use Alpha_complex with `CGAL <installation.html#cgal>`_ :math:`\geq` 5.0.0.
+
+For performances reasons, it is advised to use CGAL :math:`\geq` 5.0.0.
 
 Example from points
 -------------------
diff --git a/src/python/doc/bottleneck_distance_user.rst b/src/python/doc/bottleneck_distance_user.rst
index 89da89d3..6c6e08d9 100644
--- a/src/python/doc/bottleneck_distance_user.rst
+++ b/src/python/doc/bottleneck_distance_user.rst
@@ -9,14 +9,23 @@ Definition
 
 .. include:: bottleneck_distance_sum.inc
 
-This implementation is based on ideas from "Geometry Helps in Bottleneck Matching and Related Problems"
-:cite:`DBLP:journals/algorithmica/EfratIK01`. Another relevant publication, although it was not used is
-"Geometry Helps to Compare Persistence Diagrams" :cite:`Kerber:2017:GHC:3047249.3064175`.
+This implementation by François Godi is based on ideas from "Geometry Helps in Bottleneck Matching and Related Problems"
+:cite:`DBLP:journals/algorithmica/EfratIK01` and requires `CGAL <installation.html#cgal>`_ (`GPL v3 </licensing/>`_).
 
-Function
---------
 .. autofunction:: gudhi.bottleneck_distance
 
+This other implementation comes from `Hera
+<https://bitbucket.org/grey_narn/hera/src/master/>`_ (BSD-3-Clause) which is
+based on "Geometry Helps to Compare Persistence Diagrams"
+:cite:`Kerber:2017:GHC:3047249.3064175` by Michael Kerber, Dmitriy
+Morozov, and Arnur Nigmetov.
+
+.. warning::
+   Beware that its approximation allows for a multiplicative error, while the function above uses an additive error.
+
+.. autofunction:: gudhi.hera.bottleneck_distance
+
+
 Distance computation
 --------------------
 
diff --git a/src/python/doc/cubical_complex_sum.inc b/src/python/doc/cubical_complex_sum.inc
index 28bf8e94..87db184d 100644
--- a/src/python/doc/cubical_complex_sum.inc
+++ b/src/python/doc/cubical_complex_sum.inc
@@ -2,9 +2,9 @@
    :widths: 30 40 30
 
    +--------------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------+
-   | .. figure::                                                              | The cubical complex is an example of a structured complex useful in  | :Author: Pawel Dlotko       |
-   |      ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image    |                             |
-   |      :alt: Cubical complex representation                                | analysis.                                                            | :Since: GUDHI 2.0.0         |
+   | .. figure::                                                              | The cubical complex represents a grid as a cell complex with         | :Author: Pawel Dlotko       |
+   |      ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | cells of all dimensions.                                             |                             |
+   |      :alt: Cubical complex representation                                |                                                                      | :Since: GUDHI 2.0.0         |
    |      :figclass: align-center                                             |                                                                      |                             |
    |                                                                          |                                                                      | :License: MIT               |
    |                                                                          |                                                                      |                             |
diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst
index 56c58e0d..040e57a4 100644
--- a/src/python/doc/index.rst
+++ b/src/python/doc/index.rst
@@ -53,8 +53,8 @@ Tangential complex
 Topological descriptors computation
 ***********************************
 
-Persistence cohomology
-======================
+Persistent cohomology
+=====================
 
 .. include:: persistent_cohomology_sum.inc
 
diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst
index de09c5b3..a66e910e 100644
--- a/src/python/doc/installation.rst
+++ b/src/python/doc/installation.rst
@@ -260,6 +260,13 @@ a flag `enable_autodiff=True` is used). In order to reduce code duplication, we
 use `EagerPy <https://eagerpy.jonasrauber.de/>`_ which wraps arrays from
 PyTorch, TensorFlow and JAX in a common interface.
 
+Joblib
+------
+
+`Joblib <https://joblib.readthedocs.io/>`_ is used both as a dependency of `Scikit-learn`_,
+and directly for parallelism in some modules (:class:`~gudhi.point_cloud.knn.KNearestNeighbors`,
+:func:`~gudhi.representations.metrics.pairwise_persistence_diagram_distances`).
+
 Hnswlib
 -------
 
diff --git a/src/python/doc/persistent_cohomology_sum.inc b/src/python/doc/persistent_cohomology_sum.inc
index a1ff2eee..58e44b8a 100644
--- a/src/python/doc/persistent_cohomology_sum.inc
+++ b/src/python/doc/persistent_cohomology_sum.inc
@@ -6,9 +6,7 @@
    |      ../../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  | :Since: GUDHI 2.0.0                           |
    |                                                                 | 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    | :License: MIT                                 |
-   |      Torus                                                      | theory is essentially composed of three elements: topological spaces, |                                               |
-   |                                                                 | their homology groups and an evolution scheme.                        |                                               |
+   |      Rips Persistent Cohomology on a 3D Torus                   | features when the topological space is changing.                      | :License: MIT                                 |
    |                                                                 |                                                                       |                                               |
    |                                                                 | Computation of persistent cohomology using the algorithm of           |                                               |
    |                                                                 | :cite:`DBLP:journals/dcg/SilvaMV11` and                               |                                               |
diff --git a/src/python/doc/rips_complex_ref.rst b/src/python/doc/rips_complex_ref.rst
index 2aa6b268..f0582d5c 100644
--- a/src/python/doc/rips_complex_ref.rst
+++ b/src/python/doc/rips_complex_ref.rst
@@ -13,8 +13,6 @@ Rips complex reference manual
 
    .. automethod:: gudhi.RipsComplex.__init__
 
-.. _weighted-rips-complex-reference-manual:
-
 ======================================
 Weighted Rips complex reference manual
 ======================================
@@ -26,8 +24,6 @@ Weighted Rips complex reference manual
 
    .. automethod:: gudhi.weighted_rips_complex.WeightedRipsComplex.__init__
 
-.. _dtm-rips-complex-reference-manual:
-
 =================================
 DTM Rips complex reference manual
 =================================
diff --git a/src/python/doc/rips_complex_sum.inc b/src/python/doc/rips_complex_sum.inc
index 9cd8074b..c123ea2a 100644
--- a/src/python/doc/rips_complex_sum.inc
+++ b/src/python/doc/rips_complex_sum.inc
@@ -2,21 +2,13 @@
    :widths: 30 40 30
 
    +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------+
-   | .. figure::                                                    | Rips complex is a simplicial complex constructed from a one skeleton   | :Authors: Clément Maria, Pawel Dlotko, Vincent Rouvreau, Marc Glisse |
-   |      ../../doc/Rips_complex/rips_complex_representation.png    | graph.                                                                 |                                                                      |
+   | .. figure::                                                    | The Vietoris-Rips complex is a simplicial complex built as the         | :Authors: Clément Maria, Pawel Dlotko, Vincent Rouvreau, Marc Glisse |
+   |      ../../doc/Rips_complex/rips_complex_representation.png    | clique-complex of a proximity graph.                                   |                                                                      |
    |      :figclass: align-center                                   |                                                                        | :Since: GUDHI 2.0.0                                                  |
-   |                                                                | The filtration value of each edge is computed from a user-given        |                                                                      |
-   |                                                                | distance function and is inserted until a user-given threshold         | :License: MIT                                                        |
-   |                                                                | value.                                                                 |                                                                      |
+   |                                                                | We also provide sparse approximations, to speed-up the computation     |                                                                      |
+   |                                                                | of persistent homology, and weighted versions, which are more robust   | :License: MIT                                                        |
+   |                                                                | to outliers.                                                           |                                                                      |
    |                                                                |                                                                        |                                                                      |
-   |                                                                | This complex can be built from a point cloud and a distance function,  |                                                                      |
-   |                                                                | or from a distance matrix.                                             |                                                                      |
-   |                                                                |                                                                        |                                                                      |
-   |                                                                | Weighted Rips complex constructs a simplicial complex from a distance  |                                                                      |
-   |                                                                | matrix and weights on vertices.                                        |                                                                      |
-   |                                                                |                                                                        |                                                                      |
-   |                                                                | DTM Rips complex builds a simplicial complex from a point set or       |                                                                      |
-   |                                                                | a distance matrix.                                                     |                                                                      |
    +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------+
    | * :doc:`rips_complex_user`                                     | * :doc:`rips_complex_ref`                                                                                                                     |
    +----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/src/python/doc/rips_complex_user.rst b/src/python/doc/rips_complex_user.rst
index dd2f2cc0..6048cc4e 100644
--- a/src/python/doc/rips_complex_user.rst
+++ b/src/python/doc/rips_complex_user.rst
@@ -400,12 +400,10 @@ The output is:
 
     [(0, (3.1622776601683795, inf)), (0, (3.1622776601683795, 5.39834563766817)), (0, (3.1622776601683795, 5.39834563766817))]
 
-.. _dtm-rips-complex:
-
 DTM Rips Complex
 ----------------
 
-`DTMRipsComplex <rips_complex_ref.html#dtm-rips-complex-reference-manual>`_ builds a simplicial complex from a point set or a full distance matrix (in the form of ndarray), as described in the above example.
+:class:`~gudhi.dtm_rips_complex.DTMRipsComplex` builds a simplicial complex from a point set or a full distance matrix (in the form of ndarray), as described in the above example.
 This class constructs a weighted Rips complex giving larger weights to outliers, which reduces their impact on the persistence diagram. See `this notebook <https://github.com/GUDHI/TDA-tutorial/blob/master/Tuto-GUDHI-DTM-filtrations.ipynb>`_ for some experiments.
 
 .. testcode::
diff --git a/src/python/doc/tangential_complex_sum.inc b/src/python/doc/tangential_complex_sum.inc
index 22314a2d..2f330a07 100644
--- a/src/python/doc/tangential_complex_sum.inc
+++ b/src/python/doc/tangential_complex_sum.inc
@@ -3,10 +3,10 @@
 
    +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
    | .. figure::                                                    | A Tangential Delaunay complex is a simplicial complex designed to      | :Author:    Clément Jamin                                                                                                 |
-   |      ../../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   | :Since:    GUDHI 2.0.0                                                                                                    |
-   |                                                                | an unknown manifold. The running time depends only linearly on the     |                                                                                                                           |
-   |                                                                | extrinsic dimension :math:`d` and exponentially on the intrinsic       | :License: MIT (`GPL v3 </licensing/>`_)                                                                                   |
+   |      ../../doc/Tangential_complex/tc_examples.png              | reconstruct a :math:`k`-dimensional manifold embedded in               |                                                                                                                           |
+   |      :figclass: align-center                                   | :math:`d`-dimensional Euclidean space. The input is a point sample     | :Since:    GUDHI 2.0.0                                                                                                    |
+   |                                                                | coming from an unknown manifold. The running time depends only linearly|                                                                                                                           |
+   |                                                                | on the extrinsic dimension :math:`d` and exponentially on the intrinsic| :License: MIT (`GPL v3 </licensing/>`_)                                                                                   |
    |                                                                | dimension :math:`k`.                                                   |                                                                                                                           |
    |                                                                |                                                                        | :Requires: `Eigen <installation.html#eigen>`_ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`_ :math:`\geq` 4.11.0 |
    +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+