Merge pull request #95 from tlacombe/wdist-theo

wasserstein distance added on fork

4 files changed, 70 insertions, 3 deletions

diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst
index e379bc23..16d918bc 100644
--- a/src/python/doc/index.rst
+++ b/src/python/doc/index.rst
@@ -73,6 +73,11 @@ Bottleneck distance
 
 .. include:: bottleneck_distance_sum.inc
 
+Wasserstein distance
+===================
+
+.. include:: wasserstein_distance_sum.inc
+
 Persistence graphical tools
 ===========================
 
diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst
index 5369efb0..7699a5bb 100644
--- a/src/python/doc/installation.rst
+++ b/src/python/doc/installation.rst
@@ -215,12 +215,20 @@ The following examples require the `Matplotlib <http://matplotlib.org>`_:
     * :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>`
 
+Python Optimal Transport
+========================
+
+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.
+
 SciPy
 =====
 
-The :doc:`persistence graphical tools </persistence_graphical_tools_user>`
-module requires `SciPy <http://scipy.org>`_, a Python-based ecosystem of
-open-source software for mathematics, science, and engineering.
+The :doc:`persistence graphical tools </persistence_graphical_tools_user>` and
+:doc:`Wasserstein distance </wasserstein_distance_user>` modules require `SciPy
+<http://scipy.org>`_, a Python-based ecosystem of open-source software for
+mathematics, science, and engineering.
 
 Threading Building Blocks
 =========================
diff --git a/src/python/doc/wasserstein_distance_sum.inc b/src/python/doc/wasserstein_distance_sum.inc
new file mode 100644
index 00000000..ffd4d312
--- /dev/null
+++ b/src/python/doc/wasserstein_distance_sum.inc
@@ -0,0 +1,14 @@
+.. table::
+   :widths: 30 50 20
+
+   +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+
+   | .. figure::                                                     | The p-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`.            |                                                                  |
+   |                                                                 |                                                                      | :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
new file mode 100644
index 00000000..bcb7f19d
--- /dev/null
+++ b/src/python/doc/wasserstein_distance_user.rst
@@ -0,0 +1,40 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+Wasserstein distance user manual
+===============================
+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".
+
+Function
+--------
+.. autofunction:: gudhi.wasserstein_distance
+
+
+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.
+
+.. testcode::
+
+    import gudhi
+    import numpy as np
+
+    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_distance(diag1, diag2, q=2., p=1.)
+    print(message)
+
+The output is:
+
+.. testoutput::
+
+    Wasserstein distance value = 1.45