update from upstream/master and merge CMakeLists

14 files changed, 109 insertions, 65 deletions

diff --git a/src/python/doc/_templates/layout.html b/src/python/doc/_templates/layout.html
index 2f2d9c72..a672a281 100644
--- a/src/python/doc/_templates/layout.html
+++ b/src/python/doc/_templates/layout.html
@@ -201,7 +201,7 @@
                   <a href="#">Download</a>
                     <ul class="dropdown">
                         <li><a href="/licensing/">Licensing</a></li>
-                        <li><a href="https://gforge.inria.fr/frs/download.php/latestzip/5253/library-latest.zip" target="_blank">Get the latest sources</a></li>
+                        <li><a href="https://github.com/GUDHI/gudhi-devel/releases/latest" target="_blank">Get the latest sources</a></li>
                         <li><a href="/conda/">Conda package</a></li>
                         <li><a href="/dockerfile/">Dockerfile</a></li>
                     </ul>
diff --git a/src/python/doc/alpha_complex_sum.inc b/src/python/doc/alpha_complex_sum.inc
index c5ba9dc7..b5af0d27 100644
--- a/src/python/doc/alpha_complex_sum.inc
+++ b/src/python/doc/alpha_complex_sum.inc
@@ -5,16 +5,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                        |                                                                        | :Introduced in: 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 simplex  | :Copyright: MIT (`GPL v3 </licensing/>`_)                                                                                   |
-   |                                                                | is then said to be Gabriel), and as the minimum of the filtration      |                                                                                                                             |
-   |                                                                | values of the codimension 1 cofaces that make it not Gabriel           | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 |
-   |                                                                | otherwise. All simplices that have a filtration value strictly         |                                                                                                                             |
-   |                                                                | greater than a given alpha squared value are not inserted into the     |                                                                                                                             |
-   |                                                                | complex.                                                               |                                                                                                                             |
+   |      :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      | :Copyright: 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.                                                     |                                                                                                                             |
    |                                                                |                                                                        |                                                                                                                             |
-   |                                                                | This package requires having CGAL version 4.7 or higher (4.8.1 is      |                                                                                                                             |
-   |                                                                | advised for better performance).                                       |                                                                                                                             |
+   |                                                                | For performances reasons, it is advised to use CGAL ≥ 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 b7e69e12..60319e84 100644
--- a/src/python/doc/alpha_complex_user.rst
+++ b/src/python/doc/alpha_complex_user.rst
@@ -16,7 +16,8 @@ Definition
 
 Remarks
 ^^^^^^^
-When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha`, 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).
 
 Example from points
 -------------------
@@ -137,19 +138,20 @@ sets the filtration value (0 in case of a vertex - propagation will have no effe
 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).
+As the squared radii computed by CGAL are an approximation, it might happen that these
+:math:`\alpha^2` values do not quite define a proper filtration (i.e. non-decreasing with
+respect to inclusion).
 We fix that up by calling :func:`~gudhi.SimplexTree.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.
+The simplex tree is pruned from the given maximum :math:`\alpha^2` value (cf.
 :func:`~gudhi.SimplexTree.prune_above_filtration`). Note that this does not provide any kind
 of speed-up, since we always first build the full filtered complex, so it is recommended not to use
 :paramref:`~gudhi.AlphaComplex.create_simplex_tree.max_alpha_square`.
-In the following example, a threshold of 59 is used.
+In the following example, a threshold of :math:`\alpha^2 = 32.0` is used.
 
 
 Example from OFF file
@@ -166,7 +168,7 @@ Then, it is asked to display information about the alpha complex:
     import gudhi
     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)
+    simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=32.0)
     result_str = 'Alpha complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \
         repr(simplex_tree.num_simplices()) + ' simplices - ' + \
         repr(simplex_tree.num_vertices()) + ' vertices.'
@@ -179,7 +181,7 @@ the program output is:
 
 .. testoutput::
 
-   Alpha complex is of dimension 2 - 23 simplices - 7 vertices.
+   Alpha complex is of dimension 2 - 20 simplices - 7 vertices.
    [0] -> 0.00
    [1] -> 0.00
    [2] -> 0.00
@@ -200,9 +202,6 @@ the program output is:
    [4, 6] -> 22.74
    [4, 5, 6] -> 22.74
    [3, 6] -> 30.25
-   [2, 6] -> 36.50
-   [2, 3, 6] -> 36.50
-   [2, 4, 6] -> 37.24
 
 CGAL citations
 ==============
diff --git a/src/python/doc/cubical_complex_user.rst b/src/python/doc/cubical_complex_user.rst
index b13b500e..56cf0170 100644
--- a/src/python/doc/cubical_complex_user.rst
+++ b/src/python/doc/cubical_complex_user.rst
@@ -142,8 +142,7 @@ Or it can be defined as follows:
 .. testcode::
 
     from gudhi import PeriodicCubicalComplex as pcc
-    periodic_cc = pcc(dimensions=[3,3],
-         top_dimensional_cells= [0, 0, 0, 0, 1, 0, 0, 0, 0],
+    periodic_cc = pcc(top_dimensional_cells = [[0, 0, 0], [0, 1, 0], [0, 0, 0]],
          periodic_dimensions=[True, False])
     result_str = 'Periodic cubical complex is of dimension ' + repr(periodic_cc.dimension()) + ' - ' + \
         repr(periodic_cc.num_simplices()) + ' simplices.'
diff --git a/src/python/doc/reader_utils_ref.rst b/src/python/doc/diagram_readers_ref.rst
index f3ecebad..c79daf9c 100644
--- a/src/python/doc/reader_utils_ref.rst
+++ b/src/python/doc/diagram_readers_ref.rst
@@ -2,13 +2,9 @@
 
 .. To get rid of WARNING: document isn't included in any toctree
 
-=============================
-Reader utils reference manual
-=============================
-
-.. autofunction:: gudhi.read_off
-
-.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file
+================================
+Diagram readers reference manual
+================================
 
 .. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension
 
diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst
index c36a578f..3387a64f 100644
--- a/src/python/doc/index.rst
+++ b/src/python/doc/index.rst
@@ -6,8 +6,8 @@ GUDHI Python modules documentation
      :alt: Gudhi banner
      :figclass: align-center
 
-Complexes
-*********
+Data structures for cell complexes
+**********************************
 
 Cubical complexes
 =================
@@ -17,18 +17,26 @@ Cubical complexes
 Simplicial complexes
 ====================
 
+Simplex tree
+------------
+
+.. include:: simplex_tree_sum.inc
+
+Filtrations and reconstructions
+*******************************
+
 Alpha complex
--------------
+=============
 
 .. include:: alpha_complex_sum.inc
 
 Rips complex
-------------
+============
 
 .. include:: rips_complex_sum.inc
 
 Witness complex
----------------
+===============
 
 .. include:: witness_complex_sum.inc
 
@@ -37,16 +45,10 @@ Cover complexes
 
 .. include:: nerve_gic_complex_sum.inc
 
-Data structures and basic operations
-************************************
-
-Data structures
-===============
-
-Simplex tree
-------------
+Tangential complex
+==================
 
-.. include:: simplex_tree_sum.inc
+.. include:: tangential_complex_sum.inc
 
 Topological descriptors computation
 ***********************************
@@ -56,15 +58,6 @@ Persistence cohomology
 
 .. include:: persistent_cohomology_sum.inc
 
-Manifold reconstruction
-***********************
-
-Tangential complex
-==================
-
-.. include:: tangential_complex_sum.inc
-
-
 Topological descriptors tools
 *****************************
 
@@ -88,6 +81,11 @@ Persistence graphical tools
 
 .. include:: persistence_graphical_tools_sum.inc
 
+Point cloud utilities
+*********************
+
+.. include:: point_cloud_sum.inc
+
 Bibliography
 ************
 
diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst
index 50a697c7..d459145b 100644
--- a/src/python/doc/installation.rst
+++ b/src/python/doc/installation.rst
@@ -14,10 +14,11 @@ Compiling
 *********
 The library uses c++14 and requires `Boost <https://www.boost.org/>`_ ≥ 1.56.0,
 `CMake <https://www.cmake.org/>`_ ≥ 3.1  to generate makefiles,
-`NumPy <http://numpy.org>`_ and `Cython <https://www.cython.org/>`_ to compile
+`NumPy <http://numpy.org>`_, `Cython <https://www.cython.org/>`_ and
+`pybind11 <https://github.com/pybind/pybind11>`_ to compile
 the GUDHI Python module.
 It is a multi-platform library and compiles on Linux, Mac OSX and Visual
-Studio 2015.
+Studio 2017.
 
 On `Windows <https://wiki.python.org/moin/WindowsCompilers>`_ , only Python
 ≥ 3.5 are available because of the required Visual Studio version.
@@ -257,6 +258,13 @@ The :doc:`Wasserstein distance </wasserstein_distance_user>`
 module requires `POT <https://pot.readthedocs.io/>`_, a library that provides
 several solvers for optimization problems related to Optimal Transport.
 
+Scikit-learn
+============
+
+The :doc:`persistence representations </representations>` module require
+`scikit-learn <https://scikit-learn.org/>`_, a Python-based ecosystem of
+open-source software for machine learning.
+
 SciPy
 =====
 
diff --git a/src/python/doc/persistence_graphical_tools_user.rst b/src/python/doc/persistence_graphical_tools_user.rst
index f41a926b..80002db6 100644
--- a/src/python/doc/persistence_graphical_tools_user.rst
+++ b/src/python/doc/persistence_graphical_tools_user.rst
@@ -24,7 +24,7 @@ This function can display the persistence result as a barcode:
     import gudhi
 
     off_file = gudhi.__root_source_dir__ + '/data/points/tore3D_300.off'
-    point_cloud = gudhi.read_off(off_file=off_file)
+    point_cloud = gudhi.read_points_from_off_file(off_file=off_file)
 
     rips_complex = gudhi.RipsComplex(points=point_cloud, max_edge_length=0.7)
     simplex_tree = rips_complex.create_simplex_tree(max_dimension=3)
diff --git a/src/python/doc/point_cloud.rst b/src/python/doc/point_cloud.rst
new file mode 100644
index 00000000..d668428a
--- /dev/null
+++ b/src/python/doc/point_cloud.rst
@@ -0,0 +1,22 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+============================
+Point cloud utilities manual
+============================
+
+File Readers
+------------
+
+.. autofunction:: gudhi.read_points_from_off_file
+
+.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file
+
+Subsampling
+-----------
+
+.. automodule:: gudhi.subsampling
+   :members:
+   :special-members:
+   :show-inheritance:
diff --git a/src/python/doc/point_cloud_sum.inc b/src/python/doc/point_cloud_sum.inc
new file mode 100644
index 00000000..85d52de7
--- /dev/null
+++ b/src/python/doc/point_cloud_sum.inc
@@ -0,0 +1,15 @@
+.. table::
+   :widths: 30 50 20
+
+   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
+   | | :math:`(x_1, x_2, \ldots, x_d)`                              | Utilities to process point clouds: read from file, subsample, etc.     | :Author: Vincent Rouvreau                                                                                                   |
+   | | :math:`(y_1, y_2, \ldots, y_d)`                              |                                                                        |                                                                                                                             |
+   |                                                                |                                                                        | :Introduced in: GUDHI 2.0.0                                                                                                 |
+   |                                                                |                                                                        |                                                                                                                             |
+   |                                                                |                                                                        | :Copyright: MIT (`GPL v3 </licensing/>`_)                                                                                   |
+   |                                                                | Parts of this package require CGAL.                                    |                                                                                                                             |
+   |                                                                |                                                                        | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 |
+   |                                                                |                                                                        |                                                                                                                             |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
+   | * :doc:`point_cloud`                                                                                                                                                                                                                                                  |
+   +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/src/python/doc/rips_complex_user.rst b/src/python/doc/rips_complex_user.rst
index a8659542..a27573e8 100644
--- a/src/python/doc/rips_complex_user.rst
+++ b/src/python/doc/rips_complex_user.rst
@@ -136,7 +136,8 @@ Finally, it is asked to display information about the Rips complex.
 .. testcode::
 
     import gudhi
-    point_cloud = gudhi.read_off(off_file=gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off')
+    off_file = gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off'
+    point_cloud = gudhi.read_points_from_off_file(off_file = off_file)
     rips_complex = gudhi.RipsComplex(points=point_cloud, 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()) + ' - ' + \
diff --git a/src/python/doc/wasserstein_distance_sum.inc b/src/python/doc/wasserstein_distance_sum.inc
index ffd4d312..a97f428d 100644
--- a/src/python/doc/wasserstein_distance_sum.inc
+++ b/src/python/doc/wasserstein_distance_sum.inc
@@ -2,12 +2,12 @@
    :widths: 30 50 20
 
    +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+
-   | .. figure::                                                     | The p-Wasserstein distance measures the similarity between two       | :Author: Theo Lacombe                                            |
+   | .. figure::                                                     | The q-Wasserstein distance measures the similarity between two       | :Author: Theo Lacombe                                            |
    |      ../../doc/Bottleneck_distance/perturb_pd.png               | persistence diagrams. It's the minimum value c that can be achieved  |                                                                  |
    |      :figclass: align-center                                    | by a perfect matching between the points of the two diagrams (+ all  | :Introduced in: GUDHI 3.1.0                                      |
    |                                                                 | diagonal points), where the value of a matching is defined as the    |                                                                  |
-   |      Wasserstein distance is the p-th root of the sum of the    | p-th root of the sum of all edge lengths to the power p. Edge lengths| :Copyright: MIT                                                  |
-   |      edge lengths to the power p.                               | are measured in norm q, for :math:`1 \leq q \leq \infty`.            |                                                                  |
+   |      Wasserstein distance is the q-th root of the sum of the    | q-th root of the sum of all edge lengths to the power q. Edge lengths| :Copyright: MIT                                                  |
+   |      edge lengths to the power q.                               | are measured in norm p, for :math:`1 \leq p \leq \infty`.            |                                                                  |
    |                                                                 |                                                                      | :Requires: Python Optimal Transport (POT) :math:`\geq` 0.5.1     |
    +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+
    | * :doc:`wasserstein_distance_user`                              |                                                                                                                                         |
diff --git a/src/python/doc/wasserstein_distance_user.rst b/src/python/doc/wasserstein_distance_user.rst
index a049cfb5..94b454e2 100644
--- a/src/python/doc/wasserstein_distance_user.rst
+++ b/src/python/doc/wasserstein_distance_user.rst
@@ -9,17 +9,26 @@ Definition
 
 .. include:: wasserstein_distance_sum.inc
 
-This implementation is based on ideas from "Large Scale Computation of Means and Cluster for Persistence Diagrams via Optimal Transport".
+Functions
+---------
+This implementation uses the Python Optimal Transport library and is based on
+ideas from "Large Scale Computation of Means and Cluster for Persistence
+Diagrams via Optimal Transport" :cite:`10.5555/3327546.3327645`.
 
-Function
---------
 .. autofunction:: gudhi.wasserstein.wasserstein_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.
+
+.. autofunction:: gudhi.hera.wasserstein_distance
 
 Basic example
 -------------
 
-This example computes the 1-Wasserstein distance from 2 persistence diagrams with euclidean ground metric.
+This example computes the 1-Wasserstein distance from 2 persistence diagrams with Euclidean ground metric.
 Note that persistence diagrams must be submitted as (n x 2) numpy arrays and must not contain inf values.
 
 .. testcode::
@@ -30,7 +39,7 @@ Note that persistence diagrams must be submitted as (n x 2) numpy arrays and mus
     diag1 = np.array([[2.7, 3.7],[9.6, 14.],[34.2, 34.974]])
     diag2 = np.array([[2.8, 4.45],[9.5, 14.1]])
 
-    message = "Wasserstein distance value = " + '%.2f' % gudhi.wasserstein.wasserstein_distance(diag1, diag2, q=2., p=1.)
+    message = "Wasserstein distance value = " + '%.2f' % gudhi.wasserstein.wasserstein_distance(diag1, diag2, order=1., internal_p=2.)
     print(message)
 
 The output is:
diff --git a/src/python/doc/witness_complex_user.rst b/src/python/doc/witness_complex_user.rst
index 45ba5b3b..7087fa98 100644
--- a/src/python/doc/witness_complex_user.rst
+++ b/src/python/doc/witness_complex_user.rst
@@ -101,7 +101,7 @@ Let's start with a simple example, which reads an off point file and computes a
             print("#####################################################################")
             print("EuclideanWitnessComplex creation from points read in a OFF file")
 
-            witnesses = gudhi.read_off(off_file=args.file)
+            witnesses = gudhi.read_points_from_off_file(off_file=args.file)
             landmarks = gudhi.pick_n_random_points(points=witnesses, nb_points=args.number_of_landmarks)
 
             message = "EuclideanWitnessComplex with max_edge_length=" + repr(args.max_alpha_square) + \