Merge branch 'master' into bwgd_barycenter

Author: clbonet

CONTRIBUTORS.md

@@ -48,7 +48,7 @@ The contributors to this library are:
 * [Camille Le Coz](https://www.linkedin.com/in/camille-le-coz-8593b91a1/) (EMD2 debug)
 * [Eduardo Fernandes Montesuma](https://eddardd.github.io/my-personal-blog/) (Free support sinkhorn barycenter)
 * [Theo Gnassounou](https://github.com/tgnassou) (OT between Gaussian distributions)
-* [Clément Bonet](https://clbonet.github.io) (Wassertstein on circle, Spherical Sliced-Wasserstein)
+* [Clément Bonet](https://clbonet.github.io) (Wasserstein on circle, Spherical Sliced-Wasserstein)
 * [Ronak Mehta](https://ronakrm.github.io) (Efficient Discrete Multi Marginal Optimal Transport Regularization)
 * [Xizheng Yu](https://github.com/x12hengyu) (Efficient Discrete Multi Marginal Optimal Transport Regularization)
 * [Sonia Mazelet](https://github.com/SoniaMaz8) (Template based GNN layers)

README.md

@@ -51,7 +51,7 @@ POT provides the following generic OT solvers (links to examples):
 * [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 [69]
+* [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].
 * [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].

RELEASES.md

@@ -6,12 +6,15 @@
 - Implement CG solvers for partial FGW (PR #687)
 - Added feature `grad=last_step` for `ot.solvers.solve` (PR #693)
 - Automatic PR labeling and release file update check (PR #704)
+- Reorganize sub-module `ot/lp/__init__.py` into separate files (PR #714)
+- Fix documentation in the module `ot.gaussian` (PR #718)
 
 #### Closed issues
 - Fixed `ot.mapping` solvers which depended on deprecated `cvxpy` `ECOS` solver (PR #692, Issue #668)
 - Fixed numerical errors in `ot.gmm` (PR #690, Issue #689)
 - Add version number to the documentation (PR #696)
 - Update doc for default regularization in `ot.unbalanced` sinkhorn solvers (Issue #691, PR #700)
+- Clean documentation for `gromov`, `lp` and `unbalanced` folders (PR #710)
 
 ## 0.9.5
 

ot/gaussian.py

@@ -694,7 +694,7 @@ def empirical_bures_wasserstein_barycenter(
 
     The function estimates the optimal barycenter of the
     empirical distributions. This is equivalent to resolving the fixed point
-     algorithm for multiple Gaussian distributions :math:`\left{\mathcal{N}(\mu,\Sigma)\right}_{i=1}^n`
+    algorithm for multiple Gaussian distributions :math:`\left\{\mathcal{N}(\mu,\Sigma)\right\}_{i=1}^n`
     :ref:`[1] <references-OT-mapping-linear-barycenter>`.
 
     The barycenter still following a Gaussian distribution :math:`\mathcal{N}(\mu_b,\Sigma_b)`

ot/gmm.py

@@ -12,7 +12,7 @@
 from .backend import get_backend
 from .lp import emd2, emd
 import numpy as np
-from .lp import dist
+from .utils import dist
 from .gaussian import bures_wasserstein_mapping
 
 

ot/gromov/_lowrank.py

@@ -92,14 +92,14 @@ def lowrank_gromov_wasserstein_samples(
 
     where :
 
-    - :math: `A` is the (`dim_a`, `dim_a`) square pairwise cost matrix of the source domain.
-    - :math: `B` is the (`dim_a`, `dim_a`) square pairwise cost matrix of the target domain.
-    - :math: `\mathcal{Q}_{A,B}` is quadratic objective function of the Gromov Wasserstein plan.
-    - :math: `Q` and `R` are the low-rank matrix decomposition of the Gromov-Wasserstein plan.
-    - :math: `g` is the weight vector for the low-rank decomposition of the Gromov-Wasserstein plan.
+    - :math:`A` is the (`dim_a`, `dim_a`) square pairwise cost matrix of the source domain.
+    - :math:`B` is the (`dim_a`, `dim_a`) square pairwise cost matrix of the target domain.
+    - :math:`\mathcal{Q}_{A,B}` is quadratic objective function of the Gromov Wasserstein plan.
+    - :math:`Q` and `R` are the low-rank matrix decomposition of the Gromov-Wasserstein plan.
+    - :math:`g` is the weight vector for the low-rank decomposition of the Gromov-Wasserstein plan.
     - :math:`\mathbf{a}` and :math:`\mathbf{b}` are source and target weights (histograms, both sum to 1).
-    - :math: `r` is the rank of the Gromov-Wasserstein plan.
-    - :math: `\mathcal{C(a,b,r)}` are the low-rank couplings of the OT problem.
+    - :math:`r` is the rank of the Gromov-Wasserstein plan.
+    - :math:`\mathcal{C(a,b,r)}` are the low-rank couplings of the OT problem.
     - :math:`H((Q,R,g))` is the values of the three respective entropies evaluated for each term.
 
 

ot/gromov/_partial.py

@@ -185,7 +185,7 @@ def partial_gromov_wasserstein(
     if m is None:
         m = min(np.sum(p), np.sum(q))
     elif m < 0:
-        raise ValueError("Problem infeasible. Parameter m should be greater" " than 0.")
+        raise ValueError("Problem infeasible. Parameter m should be greater than 0.")
     elif m > min(np.sum(p), np.sum(q)):
         raise ValueError(
             "Problem infeasible. Parameter m should lower or"
@@ -654,7 +654,7 @@ def partial_fused_gromov_wasserstein(
     if m is None:
         m = min(np.sum(p), np.sum(q))
     elif m < 0:
-        raise ValueError("Problem infeasible. Parameter m should be greater" " than 0.")
+        raise ValueError("Problem infeasible. Parameter m should be greater than 0.")
     elif m > min(np.sum(p), np.sum(q)):
         raise ValueError(
             "Problem infeasible. Parameter m should lower or"
@@ -1002,18 +1002,18 @@ def solve_partial_gromov_linesearch(
     Parameters
     ----------
 
-    G : array-like, shape(ns,nt)
+    G : array-like, shape(ns, nt)
         The transport map at a given iteration of the FW
-    deltaG : array-like (ns,nt)
+    deltaG : array-like, shape (ns, nt)
         Difference between the optimal map `Gc` found by linearization in the
         FW algorithm and the value at a given iteration
     cost_G : float
         Value of the cost at `G`
-    df_G : array-like (ns,nt)
+    df_G : array-like, shape (ns, nt)
         Gradient of the GW cost at `G`
-    df_Gc : array-like (ns,nt)
+    df_Gc : array-like, shape (ns, nt)
         Gradient of the GW cost at `Gc`
-    M : array-like (ns,nt)
+    M : array-like, shape (ns, nt)
         Cost matrix between the features.
     reg : float
         Regularization parameter.
@@ -1032,7 +1032,7 @@ def solve_partial_gromov_linesearch(
         nb of function call. Useless here
     cost_G : float
         The value of the cost for the next iteration
-    df_G : array-like (ns,nt)
+    df_G : array-like, shape (ns, nt)
         Updated gradient of the GW cost
 
     References
@@ -1173,7 +1173,7 @@ def entropic_partial_gromov_wasserstein(
 
     Returns
     -------
-    :math: `gamma` : (dim_a, dim_b) ndarray
+    :math:`gamma` : ndarray, shape (dim_a, dim_b)
         Optimal transportation matrix for the given parameters
     log : dict
         log dictionary returned only if `log` is `True`
@@ -1213,7 +1213,7 @@ def entropic_partial_gromov_wasserstein(
     if m is None:
         m = min(nx.sum(p), nx.sum(q))
     elif m < 0:
-        raise ValueError("Problem infeasible. Parameter m should be greater" " than 0.")
+        raise ValueError("Problem infeasible. Parameter m should be greater than 0.")
     elif m > min(nx.sum(p), nx.sum(q)):
         raise ValueError(
             "Problem infeasible. Parameter m should lower or"

ot/gromov/_quantized.py

@@ -375,7 +375,7 @@ def get_graph_partition(
         raise ValueError(
             f"""
             Unknown `part_method='{part_method}'`. Use one of:
-            {'random', 'louvain', 'fluid', 'spectral', 'GW', 'FGW'}.
+            {"random", "louvain", "fluid", "spectral", "GW", "FGW"}.
             """
         )
     return nx.from_numpy(part, type_as=C0)
@@ -447,7 +447,7 @@ def get_graph_representants(C, part, rep_method="pagerank", random_state=0, nx=N
         raise ValueError(
             f"""
             Unknown `rep_method='{rep_method}'`. Use one of:
-            {'random', 'pagerank'}.
+            {"random", "pagerank"}.
             """
         )
 
@@ -953,7 +953,7 @@ def get_partition_and_representants_samples(
     else:
         raise ValueError(
             f"""
-            Unknown `method='{method}'`. Use one of: {'random', 'kmeans'}
+            Unknown `method='{method}'`. Use one of: {"random", "kmeans"}
             """
         )