Merge branch 'master' into python_weighted_alpha_complex

2 files changed, 28 insertions, 17 deletions

diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst
index 66efe45a..9c16b04e 100644
--- a/src/python/doc/installation.rst
+++ b/src/python/doc/installation.rst
@@ -41,7 +41,7 @@ there.
 
 The library uses c++14 and requires `Boost <https://www.boost.org/>`_ :math:`\geq` 1.56.0,
 `CMake <https://www.cmake.org/>`_ :math:`\geq` 3.5  to generate makefiles,
-`NumPy <http://numpy.org>`_, `Cython <https://www.cython.org/>`_ and
+`NumPy <http://numpy.org>`_ :math:`\geq` 1.15.0, `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
@@ -99,20 +99,14 @@ Or install it definitely in your Python packages folder:
 .. code-block:: bash
 
     cd /path-to-gudhi/build/python
-    # May require sudo or administrator privileges
-    make install
+    python setup.py install # add --user to the command if you do not have the permission
+    # Or 'pip install .'
 
 .. note::
 
-    :code:`make install` is only a
-    `CMake custom targets <https://cmake.org/cmake/help/latest/command/add_custom_target.html>`_
-    to shortcut :code:`python setup.py install` command.
     It does not take into account :code:`CMAKE_INSTALL_PREFIX`.
-    But one can use :code:`python setup.py install ...` specific options in the python directory:
-
-.. code-block:: bash
-
-    python setup.py install --prefix /home/gudhi  # Install in /home/gudhi directory
+    But one can use
+    `alternate location installation <https://docs.python.org/3/install/#alternate-installation>`_.
 
 Test suites
 ===========
diff --git a/src/python/doc/wasserstein_distance_user.rst b/src/python/doc/wasserstein_distance_user.rst
index 9ffc2759..76eb1469 100644
--- a/src/python/doc/wasserstein_distance_user.rst
+++ b/src/python/doc/wasserstein_distance_user.rst
@@ -44,7 +44,7 @@ Basic example
 *************
 
 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.
+Note that persistence diagrams must be submitted as (n x 2) numpy arrays.
 
 .. testcode::
 
@@ -67,14 +67,16 @@ We can also have access to the optimal matching by letting `matching=True`.
 It is encoded as a list of indices (i,j), meaning that the i-th point in X
 is mapped to the j-th point in Y.
 An index of -1 represents the diagonal.
+It handles essential parts (points with infinite coordinates). However if the cardinalities of the essential parts differ, 
+any matching has a cost +inf and thus can be considered to be optimal. In such a case, the function returns `(np.inf, None)`.
 
 .. testcode::
 
     import gudhi.wasserstein
     import numpy as np
 
-    dgm1 = np.array([[2.7, 3.7],[9.6, 14.],[34.2, 34.974]])
-    dgm2 = np.array([[2.8, 4.45], [5, 6], [9.5, 14.1]])
+    dgm1 = np.array([[2.7, 3.7],[9.6, 14.],[34.2, 34.974], [3, np.inf]])
+    dgm2 = np.array([[2.8, 4.45], [5, 6], [9.5, 14.1], [4, np.inf]])
     cost, matchings = gudhi.wasserstein.wasserstein_distance(dgm1, dgm2, matching=True, order=1, internal_p=2)
 
     message_cost = "Wasserstein distance value = %.2f" %cost
@@ -90,16 +92,31 @@ An index of -1 represents the diagonal.
     for j in dgm2_to_diagonal:
         print("point %s in dgm2 is matched to the diagonal" %j)
 
-The output is:
+    # An example where essential part cardinalities differ
+    dgm3 = np.array([[1, 2], [0, np.inf]])
+    dgm4 = np.array([[1, 2], [0, np.inf], [1, np.inf]])
+    cost, matchings = gudhi.wasserstein.wasserstein_distance(dgm3, dgm4, matching=True, order=1, internal_p=2)
+    print("\nSecond example:")
+    print("cost:", cost)
+    print("matchings:", matchings)
+
+
+The output is: 
 
 .. testoutput::
 
-    Wasserstein distance value = 2.15
+    Wasserstein distance value = 3.15
     point 0 in dgm1 is matched to point 0 in dgm2
     point 1 in dgm1 is matched to point 2 in dgm2
+    point 3 in dgm1 is matched to point 3 in dgm2
     point 2 in dgm1 is matched to the diagonal
     point 1 in dgm2 is matched to the diagonal
 
+    Second example:
+    cost: inf
+    matchings: None
+
+
 Barycenters
 -----------
 
@@ -181,4 +198,4 @@ Tutorial
 
 This
 `notebook <https://github.com/GUDHI/TDA-tutorial/blob/master/Tuto-GUDHI-Barycenters-of-persistence-diagrams.ipynb>`_
-presents the concept of barycenter, or Fréchet mean, of a family of persistence diagrams.
\ No newline at end of file
+presents the concept of barycenter, or Fréchet mean, of a family of persistence diagrams.