clean readme

Author: ievred

README.md

@@ -0,0 +1,267 @@
+# POT: Python Optimal Transport
+
+import ot
+[![PyPI version](https: // badge.fury.io / py / POT.svg)](https: // badge.fury.io / py / POT)
+[![Anaconda Cloud](https: // anaconda.org / conda - forge / pot / badges / version.svg)](https: // anaconda.org / conda - forge / pot)
+[![Build Status](https: // travis - ci.org / rflamary / POT.svg?branch=master)](https: // travis - ci.org / rflamary / POT)
+[![Documentation Status](https: // readthedocs.org / projects / pot / badge /?version=latest)](http: // pot.readthedocs.io / en / latest /?badge=latest)
+[![Downloads](https: // pepy.tech / badge / pot)](https: // pepy.tech / project / pot)
+[![Anaconda downloads](https: // anaconda.org / conda - forge / pot / badges / downloads.svg)](https: // anaconda.org / conda - forge / pot)
+[![License](https: // anaconda.org / conda - forge / pot / badges / license.svg)](https: // github.com / rflamary / POT / blob / master / LICENSE)
+
+
+This open source Python library provide several solvers for optimization problems related to Optimal Transport for signal, image processing and machine learning.
+
+It provides the following solvers:
+
+* OT Network Flow solver for the linear program / Earth Movers Distance[1].
+* Entropic regularization OT solver with Sinkhorn Knopp Algorithm[2], stabilized version[9][10] and greedy Sinkhorn[22] with optional GPU implementation(requires cupy).
+* Sinkhorn divergence[23] and entropic regularization OT from empirical data.
+* Smooth optimal transport solvers(dual and semi - dual) for KL and squared L2 regularizations[17].
+* Non regularized Wasserstein barycenters[16] with LP solver(only small scale).
+* Bregman projections for Wasserstein barycenter[3], convolutional barycenter[21] and unmixing[4].
+* Optimal transport for domain adaptation with group lasso regularization[5]
+* Conditional gradient[6] and Generalized conditional gradient for regularized OT[7].
+* Linear OT[14] and Joint OT matrix and mapping estimation[8].
+* Wasserstein Discriminant Analysis[11](requires autograd + pymanopt).
+* Gromov - Wasserstein distances and barycenters([13] and regularized[12])
+* Stochastic Optimization for Large - scale Optimal Transport(semi - dual problem[18] and dual problem[19])
+* Non regularized free support Wasserstein barycenters[20].
+* Unbalanced OT with KL relaxation distance and barycenter[10, 25].
+* Screening Sinkhorn Algorithm for OT[26].
+* JCPOT algorithm for multi - source domain adaptation with target shift[27].
+* Partial Wasserstein and Gromov - Wasserstein(exact[29] and entropic[3] formulations).
+
+Some demonstrations(both in Python and Jupyter Notebook format) are available in the examples folder.
+
+#### Using and citing the toolbox
+
+If you use this toolbox in your research and find it useful, please cite POT using the following bibtex reference:
+```
+
+
+@misc{flamary2017pot,
+      title = {POT Python Optimal Transport library},
+      author = {Flamary, R{'e}mi and Courty, Nicolas},
+      url = {https: // github.com / rflamary / POT},
+      year = {2017}
+      }
+```
+
+## Installation
+
+The library has been tested on Linux, MacOSX and Windows. It requires a C + + compiler for building / installing the EMD solver and relies on the following Python modules:
+
+- Numpy ( >= 1.11)
+- Scipy ( >= 1.0)
+- Cython ( >= 0.23)
+- Matplotlib ( >= 1.5)
+
+#### Pip installation
+
+Note that due to a limitation of pip, `cython` and `numpy` need to be installed
+prior to installing POT. This can be done easily with
+```
+pip install numpy cython
+```
+
+You can install the toolbox through PyPI with:
+```
+pip install POT
+```
+or get the very latest version by downloading it and then running:
+```
+python setup.py install - -user  # for user install (no root)
+```
+
+
+#### Anaconda installation with conda-forge
+
+If you use the Anaconda python distribution, POT is available in [conda - forge](https: // conda - forge.org). To install it and the required dependencies:
+```
+conda install - c conda - forge pot
+```
+
+#### Post installation check
+After a correct installation, you should be able to import the module without errors:
+```python
+```
+Note that for easier access the module is name ot instead of pot.
+
+
+### Dependencies
+
+Some sub - modules require additional dependences which are discussed below
+
+* **ot.dr ** (Wasserstein dimensionality reduction) depends on autograd and pymanopt that can be installed with:
+```
+pip install pymanopt autograd
+```
+* **ot.gpu ** (GPU accelerated OT) depends on cupy that have to be installed following instructions on[this page](https: // docs - cupy.chainer.org / en / stable / install.html).
+
+
+obviously you need CUDA installed and a compatible GPU.
+
+## Examples
+
+### Short examples
+
+* Import the toolbox
+```python
+```
+* Compute Wasserstein distances
+```python
+# a,b are 1D histograms (sum to 1 and positive)
+# M is the ground cost matrix
+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
+```
+* Compute OT matrix
+```python
+# a,b are 1D histograms (sum to 1 and positive)
+# M is the ground cost matrix
+T = ot.emd(a, b, M)  # exact linear program
+T_reg = ot.sinkhorn(a, b, M, reg)  # entropic regularized OT
+```
+* Compute Wasserstein barycenter
+```python
+# A is a n*d matrix containing d  1D histograms
+# M is the ground cost matrix
+ba = ot.barycenter(A, M, reg)  # reg is regularization parameter
+```
+
+
+### Examples and Notebooks
+
+The examples folder contain several examples and use case for the library. The full documentation is available on [Readthedocs](http: // pot.readthedocs.io / ).
+
+
+Here is a list of the Python notebooks available [here](https: // github.com / rflamary / POT / blob / master / notebooks / ) if you want a quick look:
+
+* [1D optimal transport](https: // github.com / rflamary / POT / blob / master / notebooks / plot_OT_1D.ipynb)
+* [OT Ground Loss](https: // github.com / rflamary / POT / blob / master / notebooks / plot_OT_L1_vs_L2.ipynb)
+* [Multiple EMD computation](https: // github.com / rflamary / POT / blob / master / notebooks / plot_compute_emd.ipynb)
+* [2D optimal transport on empirical distributions](https: // github.com / rflamary / POT / blob / master / notebooks / plot_OT_2D_samples.ipynb)
+* [1D Wasserstein barycenter](https: // github.com / rflamary / POT / blob / master / notebooks / plot_barycenter_1D.ipynb)
+* [OT with user provided regularization](https: // github.com / rflamary / POT / blob / master / notebooks / plot_optim_OTreg.ipynb)
+* [Domain adaptation with optimal transport](https: // github.com / rflamary / POT / blob / master / notebooks / plot_otda_d2.ipynb)
+* [Color transfer in images](https: // github.com / rflamary / POT / blob / master / notebooks / plot_otda_color_images.ipynb)
+* [OT mapping estimation for domain adaptation](https: // github.com / rflamary / POT / blob / master / notebooks / plot_otda_mapping.ipynb)
+* [OT mapping estimation for color transfer in images](https: // github.com / rflamary / POT / blob / master / notebooks / plot_otda_mapping_colors_images.ipynb)
+* [Wasserstein Discriminant Analysis](https: // github.com / rflamary / POT / blob / master / notebooks / plot_WDA.ipynb)
+* [Gromov Wasserstein](https: // github.com / rflamary / POT / blob / master / notebooks / plot_gromov.ipynb)
+* [Gromov Wasserstein Barycenter](https: // github.com / rflamary / POT / blob / master / notebooks / plot_gromov_barycenter.ipynb)
+* [Fused Gromov Wasserstein](https: // github.com / rflamary / POT / blob / master / notebooks / plot_fgw.ipynb)
+* [Fused Gromov Wasserstein Barycenter](https: // github.com / rflamary / POT / blob / master / notebooks / plot_barycenter_fgw.ipynb)
+
+
+You can also see the notebooks with [Jupyter nbviewer](https: // nbviewer.jupyter.org / github / rflamary / POT / tree / master / notebooks / ).
+
+## Acknowledgements
+
+This toolbox has been created and is maintained by
+
+* [Rémi Flamary](http: // remi.flamary.com / )
+* [Nicolas Courty](http: // people.irisa.fr / Nicolas.Courty / )
+
+The contributors to this library are
+
+* [Alexandre Gramfort](http: // alexandre.gramfort.net / )
+* [Laetitia Chapel](http: // people.irisa.fr / Laetitia.Chapel / )
+* [Michael Perrot](http: // perso.univ - st - etienne.fr / pem82055 / ) (Mapping estimation)
+* [Léo Gautheron](https: // github.com / aje)(GPU implementation)
+* [Nathalie Gayraud](https: // www.linkedin.com / in / nathalie - t - h - gayraud /?ppe=1)
+* [Stanislas Chambon](https: // slasnista.github.io / )
+* [Antoine Rolet](https: // arolet.github.io / )
+* Erwan Vautier(Gromov - Wasserstein)
+* [Kilian Fatras](https: // kilianfatras.github.io / )
+* [Alain Rakotomamonjy](https: // sites.google.com / site / alainrakotomamonjy / home)
+* [Vayer Titouan](https: // tvayer.github.io / )
+* [Hicham Janati](https: // hichamjanati.github.io / ) (Unbalanced OT)
+* [Romain Tavenard](https: // rtavenar.github.io / ) (1d Wasserstein)
+* [Mokhtar Z. Alaya](http: // mzalaya.github.io / ) (Screenkhorn)
+
+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):
+
+* [Gabriel Peyré](http: // gpeyre.github.io / ) (Wasserstein Barycenters in Matlab)
+* [Nicolas Bonneel](http: // liris.cnrs.fr / ~nbonneel /) (C++ code for EMD)
+* [Marco Cuturi](http: // marcocuturi.net / ) (Sinkhorn Knopp in Matlab/Cuda)
+
+
+## Contributions and code of conduct
+
+Every contribution is welcome and should respect the[contribution guidelines](CONTRIBUTING.md). Each member of the project is expected to follow the[code of conduct](CODE_OF_CONDUCT.md).
+
+## Support
+
+You can ask questions and join the development discussion:
+
+* On the[POT Slack channel](https: // pot - toolbox.slack.com)
+* On the POT [mailing list](https: // mail.python.org / mm3 / mailman3 / lists / pot.python.org / )
+
+
+You can also post bug reports and feature requests in Github issues. Make sure to read our[guidelines](CONTRIBUTING.md) first.
+
+## References
+
+[1] Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011, December). [Displacement interpolation using Lagrangian mass transport](https: // people.csail.mit.edu / sparis / publi / 2011 / sigasia / Bonneel_11_Displacement_Interpolation.pdf). In ACM Transactions on Graphics(TOG)(Vol. 30, No. 6, p. 158). ACM.
+
+[2] Cuturi, M. (2013). [Sinkhorn distances: Lightspeed computation of optimal transport](https: // arxiv.org / pdf / 1306.0895.pdf). In Advances in Neural Information Processing Systems(pp. 2292 - 2300).
+
+[3] Benamou, J. D., Carlier, G., Cuturi, M., Nenna, L., & Peyré, G. (2015). [Iterative Bregman projections for regularized transportation problems](https: // arxiv.org / pdf / 1412.5154.pdf). SIAM Journal on Scientific Computing, 37(2), A1111 - A1138.
+
+[4] S. Nakhostin, N. Courty, R. Flamary, D. Tuia, T. Corpetti, [Supervised planetary unmixing with optimal transport](https: // hal.archives - ouvertes.fr / hal - 01377236 / document), Whorkshop on Hyperspectral Image and Signal Processing: Evolution in Remote Sensing(WHISPERS), 2016.
+
+[5] N. Courty
+R. Flamary
+D. Tuia
+A. Rakotomamonjy, [Optimal Transport for Domain Adaptation](https: // arxiv.org / pdf / 1507.00504.pdf), in IEEE Transactions on Pattern Analysis and Machine Intelligence, vol.PP, no.99, pp.1 - 1
+
+[6] Ferradans, S., Papadakis, N., Peyré, G., & Aujol, J. F. (2014). [Regularized discrete optimal transport](https: // arxiv.org / pdf / 1307.5551.pdf). SIAM Journal on Imaging Sciences, 7(3), 1853 - 1882.
+
+[7] Rakotomamonjy, A., Flamary, R., & Courty, N. (2015). [Generalized conditional gradient: analysis of convergence and applications](https: // arxiv.org / pdf / 1510.06567.pdf). arXiv preprint arXiv: 1510.06567.
+
+[8] M. Perrot, N. Courty, R. Flamary, A. Habrard(2016), [Mapping estimation for discrete optimal transport](http: // remi.flamary.com / biblio / perrot2016mapping.pdf), Neural Information Processing Systems(NIPS).
+
+[9] Schmitzer, B. (2016). [Stabilized Sparse Scaling Algorithms for Entropy Regularized Transport Problems](https: // arxiv.org / pdf / 1610.06519.pdf). arXiv preprint arXiv: 1610.06519.
+
+[10] Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). [Scaling algorithms for unbalanced transport problems](https: // arxiv.org / pdf / 1607.05816.pdf). arXiv preprint arXiv: 1607.05816.
+
+[11] Flamary, R., Cuturi, M., Courty, N., & Rakotomamonjy, A. (2016). [Wasserstein Discriminant Analysis](https: // arxiv.org / pdf / 1608.08063.pdf). arXiv preprint arXiv: 1608.08063.
+
+[12] Gabriel Peyré, Marco Cuturi, and Justin Solomon(2016), [Gromov - Wasserstein averaging of kernel and distance matrices](http: // proceedings.mlr.press / v48 / peyre16.html)  International Conference on Machine Learning(ICML).
+
+[13] Mémoli, Facundo(2011). [Gromov–Wasserstein distances and the metric approach to object matching](https: // media.adelaide.edu.au / acvt / Publications / 2011 / 2011 - Gromov % E2 % 80 % 93Wasserstein % 20Distances % 20and % 20the % 20Metric % 20Approach % 20to % 20Object % 20Matching.pdf). Foundations of computational mathematics 11.4: 417 - 487.
+
+[14] Knott, M. and Smith, C. S. (1984).[On the optimal mapping of distributions](https: // link.springer.com / article / 10.1007 / BF00934745), Journal of Optimization Theory and Applications Vol 43.
+
+[15] Peyré, G., & Cuturi, M. (2018). [Computational Optimal Transport](https: // arxiv.org / pdf / 1803.00567.pdf) .
+
+[16] Agueh, M., & Carlier, G. (2011). [Barycenters in the Wasserstein space](https: // hal.archives - ouvertes.fr / hal - 00637399 / document). SIAM Journal on Mathematical Analysis, 43(2), 904 - 924.
+
+[17] Blondel, M., Seguy, V., & Rolet, A. (2018). [Smooth and Sparse Optimal Transport](https: // arxiv.org / abs / 1710.06276). Proceedings of the Twenty - First International Conference on Artificial Intelligence and Statistics(AISTATS).
+
+[18] Genevay, A., Cuturi, M., Peyré, G. & Bach, F. (2016)[Stochastic Optimization for Large - scale Optimal Transport](https: // arxiv.org / abs / 1605.08527). Advances in Neural Information Processing Systems(2016).
+
+[19] Seguy, V., Bhushan Damodaran, B., Flamary, R., Courty, N., Rolet, A. & Blondel, M. [Large - scale Optimal Transport and Mapping Estimation](https: // arxiv.org / pdf / 1711.02283.pdf). International Conference on Learning Representation(2018)
+
+[20] Cuturi, M. and Doucet, A. (2014)[Fast Computation of Wasserstein Barycenters](http: // proceedings.mlr.press / v32 / cuturi14.html). International Conference in Machine Learning
+
+[21] Solomon, J., De Goes, F., Peyré, G., Cuturi, M., Butscher, A., Nguyen, A. & Guibas, L. (2015). [Convolutional wasserstein distances: Efficient optimal transportation on geometric domains](https: // dl.acm.org / citation.cfm?id=2766963). ACM Transactions on Graphics(TOG), 34(4), 66.
+
+[22] J. Altschuler, J.Weed, P. Rigollet, (2017)[Near - linear time approximation algorithms for optimal transport via Sinkhorn iteration](https: // papers.nips.cc / paper / 6792 - near - linear - time - approximation - algorithms - for-optimal - transport - via - sinkhorn - iteration.pdf), Advances in Neural Information Processing Systems(NIPS) 31
+
+[23] Aude, G., Peyré, G., Cuturi, M., [Learning Generative Models with Sinkhorn Divergences](https: // arxiv.org / abs / 1706.00292), Proceedings of the Twenty - First International Conference on Artficial Intelligence and Statistics, (AISTATS) 21, 2018
+
+[24] Vayer, T., Chapel, L., Flamary, R., Tavenard, R. and Courty, N. (2019). [Optimal Transport for structured data with application on graphs](http: // proceedings.mlr.press / v97 / titouan19a.html) Proceedings of the 36th International Conference on Machine Learning(ICML).
+
+[25] Frogner C., Zhang C., Mobahi H., Araya - Polo M., Poggio T. (2015). [Learning with a Wasserstein Loss](http: // cbcl.mit.edu / wasserstein / )  Advances in Neural Information Processing Systems (NIPS).
+
+[26] Alaya M. Z., Bérar M., Gasso G., Rakotomamonjy A. (2019). [Screening Sinkhorn Algorithm for Regularized Optimal Transport](https: // papers.nips.cc / paper / 9386 - screening - sinkhorn - algorithm - for-regularized - optimal - transport), Advances in Neural Information Processing Systems 33 (NeurIPS).
+
+[27] Redko I., Courty N., Flamary R., Tuia D. (2019). [Optimal Transport for Multi - source Domain Adaptation under Target Shift](http: // proceedings.mlr.press / v89 / redko19a.html), Proceedings of the Twenty - Second International Conference on Artificial Intelligence and Statistics(AISTATS) 22, 2019.
+
+[28] Caffarelli, L. A., McCann, R. J. (2020). [Free boundaries in optimal transport and Monge - Ampere obstacle problems](http: // www.math.toronto.edu / ~mccann / papers / annals2010.pdf), Annals of mathematics, 673 - 730.
+
+[29] Chapel, L., Alaya, M., Gasso, G. (2019). [Partial Gromov - Wasserstein with Applications on Positive - Unlabeled Learning](https: // arxiv.org / abs / 2002.08276), arXiv preprint arXiv: 2002.08276.