11
2- Quick start guide
3- =================
2+ User guide
3+ ==========
44
55In the following we provide some pointers about which functions and classes
66to use for different problems related to optimal transport (OT) and machine
@@ -136,12 +136,12 @@ instance the memory cost for an OT problem is always :math:`\mathcal{O}(n^2)` in
136136memory because the cost matrix has to be computed. The exact solver in of time
137137complexity :math: `\mathcal {O}(n^3 \log (n))` and the Sinkhorn solver has been
138138proven to be nearly :math: `\mathcal {O}(n^2 )` which is still too complex for very
139- large scale solvers.
139+ large scale solvers. For all the generic solvers we need to compute the cost
140+ matrix and the OT matrix of memory size :math: `\mathcal {O}(n^2 )` which can be
141+ prohibitive for very large scale problems.
140142
141-
142- If you need to solve OT with large number of samples, we recommend to use
143- entropic regularization and memory efficient implementation of Sinkhorn as
144- proposed in `GeomLoss <https://www.kernel-operations.io/geomloss/ >`_. This
143+ If you need to solve OT with large number of samples, we provide "lazy" memory efficient implementation of Sinkhorn in pure
144+ python and using `GeomLoss <https://www.kernel-operations.io/geomloss/ >`_. This
145145implementation is compatible with Pytorch and can handle large number of
146146samples. Another approach to estimate the Wasserstein distance for very large
147147number of sample is to use the trick from `Wasserstein GAN
@@ -193,15 +193,19 @@ that will return the optimal transport matrix :math:`\gamma^*`:
193193
194194 # a and b are 1D histograms (sum to 1 and positive)
195195 # M is the ground cost matrix
196+
197+ # unified API
198+ T = ot.solve(M, a, b).plan # exact linear program
199+
200+ # classical API
196201 T = ot.emd(a, b, M) # exact linear program
197202
198203
199204implemented in C from [1 ]_. It has a complexity of :math: `O(n^3 )` but the
200205solver is quite efficient and uses sparsity of the solution.
201206
202207
203-
204- .. minigallery :: ot.emd
208+ .. minigallery :: ot.emd, ot.solve
205209 :add-heading: Examples of use for :any: `ot.emd `
206210 :heading-level: "
207211
@@ -226,7 +230,12 @@ It can computed from an already estimated OT matrix with
226230
227231 # a and b are 1D histograms (sum to 1 and positive)
228232 # M is the ground cost matrix
229- W = ot.emd2(a, b, M) # Wasserstein distance / EMD value
233+
234+ # Wasserstein distance / EMD value with unified API
235+ W = ot.solve(M, a, b, return_matrix = False ).value
236+
237+ # with classical API
238+ W = ot.emd2(a, b, M)
230239
231240Wasserstein distance
232241<https://en.wikipedia.org/wiki/Wasserstein_metric> `_ between distributions a and
@@ -246,7 +255,7 @@ the :math:`W_1` Wasserstein distance can be done directly with :any:`ot.emd2`
246255when providing :code: `M = ot.dist(xs, xt, metric='euclidean') ` to use the Euclidean
247256distance.
248257
249- .. minigallery :: ot.emd2
258+ .. minigallery :: ot.emd2, ot.solve
250259 :add-heading: Examples of use for :any: `ot.emd2 `
251260 :heading-level: "
252261
@@ -274,6 +283,10 @@ distributions. In the case when the finite sample dataset is supposed Gaussian,
274283we provide :any: `ot.gaussian.bures_wasserstein_mapping ` that returns the parameters for the
275284Monge mapping.
276285
286+ All those special cases are accessible with the unified API of POT through the
287+ function :any: `ot.solve_sample ` with the parameter :code: `method ` that allows to
288+ choose the method used to solve the problem (with :code: `method='1D' ` or :code: `method='gaussian' `).
289+
277290
278291Regularized Optimal Transport
279292-----------------------------
@@ -330,13 +343,15 @@ The Sinkhorn-Knopp algorithm is implemented in :any:`ot.sinkhorn` and
330343linear term. Note that the regularization parameter :math: `\lambda ` in the
331344equation above is given to those functions with the parameter :code: `reg `.
332345
333- >>> import ot
334- >>> a = [.5 , .5 ]
335- >>> b = [.5 , .5 ]
336- >>> M = [[0 ., 1 .], [1 ., 0 .]]
337- >>> ot.sinkhorn(a, b, M, 1 )
338- array([[ 0.36552929, 0.13447071],
339- [ 0.13447071, 0.36552929]])
346+ .. code :: python
347+
348+ # unified API
349+ P = ot.solve(M, a, b, reg = 1 ).plan # OT Sinkhorn matrix
350+ loss = ot.solve(M, a, b, reg = 1 ).value # OT Sinkhorn value
351+
352+ # classical API
353+ P = ot.sinkhorn(a, b, M, reg = 1 ) # OT Sinkhorn matrix
354+ loss = ot.sinkhorn2(a, b, M, reg = 1 ) # OT Sinkhorn value
340355
341356
342357
@@ -406,13 +421,10 @@ implementations are not optimized for speed but provide a robust implementation
406421of algorithms in [18 ]_ [19 ]_.
407422
408423
409- .. minigallery :: ot.sinkhorn
410- :add-heading: Examples of use for :any: ` ot.sinkhorn `
424+ .. minigallery :: ot.sinkhorn ot.sinkhorn2
425+ :add-heading: Examples of use for Sinkhorn algorithm
411426 :heading-level: "
412427
413- .. minigallery :: ot.sinkhorn2
414- :add-heading: Examples of use for :any: `ot.sinkhorn2 `
415- :heading-level: "
416428
417429
418430Other regularizations
@@ -969,18 +981,6 @@ For instance, to disable TensorFlow, set `export POT_BACKEND_DISABLE_TENSORFLOW=
969981It's important to note that the `numpy ` backend cannot be disabled.
970982
971983
972- List of compatible modules
973- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
974-
975- This list will get longer for new releases and will hopefully disappear when POT
976- become fully implemented with the backend.
977-
978- - :any: `ot.bregman `
979- - :any: `ot.gromov ` (some functions use CPU only solvers with copy overhead)
980- - :any: `ot.optim ` (some functions use CPU only solvers with copy overhead)
981- - :any: `ot.sliced `
982- - :any: `ot.utils ` (partial)
983-
984984
985985FAQ
986986---
0 commit comments