[MRG] Update doc and exemples (#754)

* update readme

* big reoganization of exmaples

* documenttaion withe xmaple in multiple sections

* add all chnages

* add all chnages

* add bure bary to gaussian section

* other example

* fix readme links

* update readme

* change coot imahe

Author: rflamary

CONTRIBUTORS.md

@@ -12,6 +12,11 @@ It is currently maintained by :
 
 ## Contributors
 
+<a href="https://github.com/PythonOT/POT/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=PythonOT/POT" />
+</a>
+
+
 The contributors to this library are:
 
 * [Rémi Flamary](http://remi.flamary.com/) (EMD wrapper, Pytorch backend, DA
@@ -54,6 +59,7 @@ The contributors to this library are:
 * [Julie Delon](https://judelo.github.io/) (GMM OT)
 * [Samuel Boïté](https://samuelbx.github.io/) (GMM OT)
 
+
 ## Acknowledgments
 
 This toolbox benefit a lot from open source research and we would like to thank the following persons for providing some code (in various languages):

README.md

@@ -14,21 +14,36 @@ learning.
 
 Website and documentation: [https://PythonOT.github.io/](https://PythonOT.github.io/)
 
-Source Code (MIT): [https://github.com/PythonOT/POT](https://github.com/PythonOT/POT)
+Source Code (MIT):
+[https://github.com/PythonOT/POT](https://github.com/PythonOT/POT)
 
-POT provides the following generic OT solvers (links to examples):
+
+POT has the following main features:
+* A large set of differentiable solvers for optimal transport problems, including:
+  *  Exact linear OT, entropic and quadratic regularized OT, 
+  *  Gromov-Wasserstein (GW) distances, Fused GW distances and variants of
+     quadratic OT,
+  *  Unbalanced and partial OT for different divergences,
+*  OT barycenters (Wasserstein and GW) for fixed and free support,
+*  Fast OT solvers in 1D, on the circle and between Gaussian Mixture Models (GMMs),
+*  Many ML related solvers, such as domain adaptation, optimal transport mapping
+   estimation, subspace learning, Graph Neural Networks (GNNs) layers.
+*  Several backends for easy use with Pytorch, Jax, Tensorflow, Numpy and Cupy arrays.
+
+### Implemented Features
+
+POT provides the following generic OT solvers:
 
 * [OT Network Simplex solver](https://pythonot.github.io/auto_examples/plot_OT_1D.html) for the linear program/ Earth Movers Distance [1] .
 * [Conditional gradient](https://pythonot.github.io/auto_examples/plot_optim_OTreg.html) [6] and [Generalized conditional gradient](https://pythonot.github.io/auto_examples/plot_optim_OTreg.html) for regularized OT [7].
 * Entropic regularization OT solver with [Sinkhorn Knopp
   Algorithm](https://pythonot.github.io/auto_examples/plot_OT_1D.html) [2] ,
-  stabilized version [9] [10] [34], lazy CPU/GPU solver from geomloss [60] [61], greedy Sinkhorn [22] and [Screening
-  Sinkhorn [26]
-  ](https://pythonot.github.io/auto_examples/plot_screenkhorn_1D.html).
+  stabilized version [9] [10] [34], lazy CPU/GPU solver from geomloss [60] [61], greedy Sinkhorn [22] and Screening
+  Sinkhorn [26].
 * Bregman projections for [Wasserstein barycenter](https://pythonot.github.io/auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html) [3], [convolutional barycenter](https://pythonot.github.io/auto_examples/barycenters/plot_convolutional_barycenter.html) [21]  and unmixing [4].
 * Sinkhorn divergence [23] and entropic regularization OT from empirical data.
 * Debiased Sinkhorn barycenters [Sinkhorn divergence barycenter](https://pythonot.github.io/auto_examples/barycenters/plot_debiased_barycenter.html) [37]
-* [Smooth optimal transport solvers](https://pythonot.github.io/auto_examples/plot_OT_1D_smooth.html) (dual and semi-dual) for KL and squared L2 regularizations [17].
+* Smooth optimal transport solvers (dual and semi-dual) for KL and squared L2 regularizations [17].
 * Weak OT solver between empirical distributions [39]
 * Non regularized [Wasserstein barycenters [16] ](https://pythonot.github.io/auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html) with LP solver (only small scale).
 * [Gromov-Wasserstein distances](https://pythonot.github.io/auto_examples/gromov/plot_gromov.html) and [GW barycenters](https://pythonot.github.io/auto_examples/gromov/plot_gromov_barycenter.html)  (exact [13] and regularized [12,51]), differentiable using gradients from Graph Dictionary Learning [38]
@@ -42,15 +57,16 @@ POT provides the following generic OT solvers (links to examples):
 * [One dimensional Unbalanced OT](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_UOT_1D.html) with KL relaxation and [barycenter](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_UOT_barycenter_1D.html) [10, 25]. Also [exact unbalanced OT](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_unbalanced_ot.html) with KL and quadratic regularization and the [regularization path of UOT](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_regpath.html) [41]
 * [Partial Wasserstein and Gromov-Wasserstein](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_partial_wass_and_gromov.html) and [Partial Fused Gromov-Wasserstein](https://pythonot.github.io/auto_examples/gromov/plot_partial_fgw.html) (exact [29] and entropic [3] formulations).
 * [Sliced Wasserstein](https://pythonot.github.io/auto_examples/sliced-wasserstein/plot_variance.html) [31, 32] and Max-sliced Wasserstein [35] that can be used for gradient flows [36].
-* [Wasserstein distance on the circle](https://pythonot.github.io/auto_examples/plot_compute_wasserstein_circle.html) [44, 45]
-* [Spherical Sliced Wasserstein](https://pythonot.github.io/auto_examples/sliced-wasserstein/plot_variance_ssw.html) [46]
+* [Wasserstein distance on the
+  circle](https://pythonot.github.io/auto_examples/sliced-wasserstein/plot_compute_wasserstein_circle.html)
+  [44, 45] and  [Spherical Sliced Wasserstein](https://pythonot.github.io/auto_examples/sliced-wasserstein/plot_variance_ssw.html) [46]
 * [Graph Dictionary Learning solvers](https://pythonot.github.io/auto_examples/gromov/plot_gromov_wasserstein_dictionary_learning.html) [38].
 * [Semi-relaxed (Fused) Gromov-Wasserstein divergences](https://pythonot.github.io/auto_examples/gromov/plot_semirelaxed_fgw.html) with corresponding [barycenter solvers](https://pythonot.github.io/auto_examples/gromov/plot_semirelaxed_gromov_wasserstein_barycenter.hmtl) (exact and regularized [48]).
 * [Quantized (Fused) Gromov-Wasserstein distances](https://pythonot.github.io/auto_examples/gromov/plot_quantized_gromov_wasserstein.html) [68].
 * [Efficient Discrete Multi Marginal Optimal Transport Regularization](https://pythonot.github.io/auto_examples/others/plot_demd_gradient_minimize.html) [50].
 * [Several backends](https://pythonot.github.io/quickstart.html#solving-ot-with-multiple-backends) for easy use of POT with  [Pytorch](https://pytorch.org/)/[jax](https://github.com/google/jax)/[Numpy](https://numpy.org/)/[Cupy](https://cupy.dev/)/[Tensorflow](https://www.tensorflow.org/) arrays.
 * [Smooth Strongly Convex Nearest Brenier Potentials](https://pythonot.github.io/auto_examples/others/plot_SSNB.html#sphx-glr-auto-examples-others-plot-ssnb-py) [58], with an extension to bounding potentials using [59].
-* [Gaussian Mixture Model OT](https://pythonot.github.io/auto_examples/others/plot_GMMOT_plan.html#sphx-glr-auto-examples-others-plot-gmmot-plan-py) [69].
+* [Gaussian Mixture Model OT](https://pythonot.github.io/auto_examples/gaussian_gmm/plot_GMMOT_plan.html#sphx-glr-auto-examples-others-plot-gmmot-plan-py) [69].
 * [Co-Optimal Transport](https://pythonot.github.io/auto_examples/others/plot_COOT.html) [49] and
 [unbalanced Co-Optimal Transport](https://pythonot.github.io/auto_examples/others/plot_learning_weights_with_COOT.html) [71].
 * Fused unbalanced Gromov-Wasserstein [70].
@@ -173,6 +189,12 @@ import ot
 ```python
 # a,b are 1D histograms (sum to 1 and positive)
 # M is the ground cost matrix
+
+# With the unified  API :
+Wd = ot.solve(M, a, b).value # exact linear program
+Wd_reg = ot.solve(M, a, b, reg=reg).value # entropic regularized OT
+
+# With the old API :
 Wd = ot.emd2(a, b, M) # exact linear program
 Wd_reg = ot.sinkhorn2(a, b, M, reg) # entropic regularized OT
 # if b is a matrix compute all distances to a and return a vector
@@ -183,10 +205,29 @@ Wd_reg = ot.sinkhorn2(a, b, M, reg) # entropic regularized OT
 ```python
 # a,b are 1D histograms (sum to 1 and positive)
 # M is the ground cost matrix
+
+# With the unified API :
+T = ot.solve(M, a, b).plan # exact linear program
+T_reg = ot.solve(M, a, b, reg=reg).plan # entropic regularized OT
+
+# With the old API :
 T = ot.emd(a, b, M) # exact linear program
 T_reg = ot.sinkhorn(a, b, M, reg) # entropic regularized OT
 ```
 
+* Compute OT on empirical distributions
+
+```python
+# X and Y are two 2D arrays of shape (n_samples, n_features)
+
+# with squared euclidean metric
+T = ot.solve_sample(X, Y).plan # exact linear program
+T_reg = ot.solve_sample(X, Y, reg=reg).plan # entropic regularized OT
+
+Wass_2 = ot.solve_sample(X, Y).value # Squared Wasserstein_2
+Wass_1 = ot.solve_sample(X, Y, metric='euclidean').value # Wasserstein 1
+```
+
 * Compute Wasserstein barycenter
 
 ```python
@@ -209,7 +250,11 @@ It is currently maintained by :
 * [Rémi Flamary](https://remi.flamary.com/)
 * [Cédric Vincent-Cuaz](https://cedricvincentcuaz.github.io/)
 
-The numerous contributors to this library are listed [here](CONTRIBUTORS.md).
+The POT contributors to this library are listed [here](CONTRIBUTORS.md).
+
+<a href="https://github.com/PythonOT/POT/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=PythonOT/POT" />
+</a>
 
 POT has benefited from the financing or manpower from the following partners:
 

RELEASES.md

@@ -21,6 +21,7 @@
 - Fix reg_div function compatibility with numpy in `ot.unbalanced.lbfgsb_unbalanced` via new function `ot.utils.fun_to_numpy` (PR #731)
 - Added to each example in the examples gallery the information about the release version in which it was introduced (PR #743)
 - Removed release information from quickstart guide (PR #744)
+- Update REAMDE with new API and reorganize examples (PR #754)
 
 #### Closed issues
 - Fixed `ot.mapping` solvers which depended on deprecated `cvxpy` `ECOS` solver (PR #692, Issue #668)

docs/source/conf.py

@@ -15,7 +15,7 @@
 import sys
 import os
 import re
-
+import datetime
 
 # !!!! allow readthedoc compilation
 try:
@@ -90,7 +90,7 @@ def __getattr__(cls, name):
 
 # General information about the project.
 project = "POT Python Optimal Transport"
-copyright = "2016-2023, POT Contributors"
+copyright = "2016-{}, POT Contributors".format(datetime.datetime.now().year)
 author = "Rémi Flamary, POT Contributors"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -356,4 +356,5 @@ def __getattr__(cls, name):
     "doc_module": ("ot", "numpy", "scipy", "pylab"),
     "matplotlib_animations": True,
     "reference_url": {"ot": None},
+    "copyfile_regex": r"index.rst",
 }

examples/README.txt

@@ -0,0 +1,4 @@
+
+
+Differentiable OT with PyTorch
+------------------------------

examples/backends/README.txt

@@ -15,6 +15,8 @@
 #
 # License: MIT License
 
+# sphinx_gallery_thumbnail_number = 2
+
 import numpy as np
 import matplotlib.pyplot as plt
 import ot

examples/backends/index.rst

@@ -1,5 +1,5 @@
 
 
 
-Domain adaptation examples
+Domain adaptation with OT
 --------------------------