diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/_templates/module.rst | 57 | ||||
| -rw-r--r-- | docs/source/all.rst | 110 | ||||
| -rw-r--r-- | docs/source/conf.py | 25 | ||||
| -rw-r--r-- | docs/source/index.rst | 6 | ||||
| -rw-r--r-- | docs/source/readme.rst | 60 | ||||
| -rw-r--r-- | docs/source/releases.rst | 260 |
6 files changed, 392 insertions, 126 deletions
diff --git a/docs/source/_templates/module.rst b/docs/source/_templates/module.rst new file mode 100644 index 0000000..5ad89be --- /dev/null +++ b/docs/source/_templates/module.rst @@ -0,0 +1,57 @@ +{{ fullname }} +{{ underline }} + +.. automodule:: {{ fullname }} + + {% block functions %} + {% if functions %} + + Functions + --------- + + {% for item in functions %} + + .. autofunction:: {{ item }} + + .. include:: backreferences/{{fullname}}.{{item}}.examples + + .. raw:: html + + <div class="sphx-glr-clear"></div> + + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + + Classes + ------- + + {% for item in classes %} + .. autoclass:: {{ item }} + :members: + + .. include:: backreferences/{{fullname}}.{{item}}.examples + + .. raw:: html + + <div class="sphx-glr-clear"></div> + + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + + Exceptions + ---------- + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %}
\ No newline at end of file diff --git a/docs/source/all.rst b/docs/source/all.rst index a6d9790..d7b878f 100644 --- a/docs/source/all.rst +++ b/docs/source/all.rst @@ -1,94 +1,36 @@ +.. _sphx_glr_api_reference: -Python modules -============== +API and modules +=============== -ot --- +.. currentmodule:: ot -.. automodule:: ot - :members: - -ot.lp ------ -.. automodule:: ot.lp - :members: - -ot.bregman ----------- - -.. automodule:: ot.bregman - :members: - -ot.smooth ------ -.. automodule:: ot.smooth - :members: - -ot.gromov ----------- - -.. automodule:: ot.gromov - :members: - - -ot.optim --------- - -.. automodule:: ot.optim - :members: - -ot.da --------- -.. automodule:: ot.da - :members: +:py:mod:`ot`: -ot.gpu --------- +.. autosummary:: + :toctree: gen_modules/ + :template: module.rst -.. automodule:: ot.gpu - :members: + lp + bregman + smooth + gromov + optim + da + gpu + dr + utils + datasets + plot + stochastic + unbalanced + partial -ot.dr --------- +.. autosummary:: + :toctree: ../modules/generated/ + :template: module.rst -.. automodule:: ot.dr - :members: - - -ot.utils --------- - -.. automodule:: ot.utils - :members: - -ot.datasets ------------ - -.. automodule:: ot.datasets - :members: - -ot.plot -------- - -.. automodule:: ot.plot - :members: - -ot.stochastic -------------- - -.. automodule:: ot.stochastic +.. automodule:: ot :members: - -ot.unbalanced -------------- - -.. automodule:: ot.unbalanced - :members: - -ot.partial -------------- - -.. automodule:: ot.partial - :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index 880c71d..384bf40 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -36,9 +36,9 @@ class Mock(MagicMock): return MagicMock() -MOCK_MODULES = ['ot.lp.emd_wrap', 'autograd', 'pymanopt', 'cupy', 'autograd.numpy', 'pymanopt.manifolds', 'pymanopt.solvers'] +MOCK_MODULES = [ 'cupy'] # 'autograd.numpy','pymanopt.manifolds','pymanopt.solvers', -#sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) +sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) # !!!! # If extensions (or modules to document with autodoc) are in another directory, @@ -59,6 +59,7 @@ sys.path.insert(0, os.path.abspath("../..")) # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', @@ -70,6 +71,9 @@ extensions = [ 'sphinx_gallery.gen_gallery', ] +autosummary_generate = True + + napoleon_numpy_docstring = True # Add any paths that contain templates here, relative to this directory. @@ -88,7 +92,7 @@ master_doc = 'index' # General information about the project. project = u'POT Python Optimal Transport' -copyright = u'2016-2019, Rémi Flamary, Nicolas Courty' +copyright = u'2016-2020, Rémi Flamary, Nicolas Courty' author = u'Rémi Flamary, Nicolas Courty' # The version info for the project you're documenting, acts as replacement for @@ -297,7 +301,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'pot', u'POT Python Optimal Transport library Documentation', + (master_doc, 'pot', u'POT Python Optimal Transport', [author], 1) ] @@ -311,8 +315,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'POT', u'POT Python Optimal Transport library Documentation', - author, 'POT', 'Python Optimal Transport librar.', + (master_doc, 'POT', u'POT Python Optimal Transport', + author, 'POT', 'Python Optimal Transport', 'Miscellaneous'), ] @@ -333,13 +337,14 @@ texinfo_documents = [ intersphinx_mapping = {'python': ('https://docs.python.org/3', None), 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), - 'matplotlib': ('http://matplotlib.sourceforge.net/', None)} + 'matplotlib': ('http://matplotlib.org/', None)} sphinx_gallery_conf = { 'examples_dirs': ['../../examples', '../../examples/da'], 'gallery_dirs': 'auto_examples', - 'backreferences_dir': '../modules/generated/', + 'backreferences_dir': 'gen_modules/backreferences', + 'inspect_global_variables' : True, + 'doc_module' : ('ot','numpy','scipy','pylab'), 'reference_url': { - 'numpy': 'http://docs.scipy.org/doc/numpy-1.9.1', - 'scipy': 'http://docs.scipy.org/doc/scipy-0.17.0/reference'} + 'ot': None} } diff --git a/docs/source/index.rst b/docs/source/index.rst index 9078d35..be01343 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,15 +10,17 @@ Contents -------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 self quickstart all auto_examples/index + releases .. include:: readme.rst - :start-line: 5 + :start-line: 2 + Indices and tables diff --git a/docs/source/readme.rst b/docs/source/readme.rst index b00d7b7..c96f191 100644 --- a/docs/source/readme.rst +++ b/docs/source/readme.rst @@ -1,8 +1,8 @@ POT: Python Optimal Transport ============================= -|PyPI version| |Anaconda Cloud| |Build Status| |Build Status| |Codecov -Status| |Downloads| |Anaconda downloads| |License| +|PyPI version| |Anaconda Cloud| |Build Status| |Codecov Status| +|Downloads| |Anaconda downloads| |License| This open source Python library provide several solvers for optimization problems related to Optimal Transport for signal, image processing and @@ -29,9 +29,9 @@ POT provides the following generic OT solvers (links to examples): [26] <auto_examples/plot_screenkhorn_1D.html>`__ with optional GPU implementation (requires cupy). - Bregman projections for `Wasserstein - barycenter <auto_examples/plot_barycenter_lp_vs_entropic.html>`__ + barycenter <auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html>`__ [3], `convolutional - barycenter <auto_examples/plot_convolutional_barycenter.html>`__ + barycenter <auto_examples/barycenters/plot_convolutional_barycenter.html>`__ [21] and unmixing [4]. - Sinkhorn divergence [23] and entropic regularization OT from empirical data. @@ -39,68 +39,69 @@ POT provides the following generic OT solvers (links to examples): solvers <auto_examples/plot_OT_1D_smooth.html>`__ (dual and semi-dual) for KL and squared L2 regularizations [17]. - Non regularized `Wasserstein barycenters - [16] <auto_examples/plot_barycenter_lp_vs_entropic.html>`__) + [16] <auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html>`__) with LP solver (only small scale). - `Gromov-Wasserstein - distances <auto_examples/plot_gromov.html>`__ + distances <auto_examples/gromov/plot_gromov.html>`__ and `GW - barycenters <auto_examples/plot_gromov_barycenter.html>`__ + barycenters <auto_examples/gromov/plot_gromov_barycenter.html>`__ (exact [13] and regularized [12]) - `Fused-Gromov-Wasserstein distances - solver <auto_examples/plot_fgw.html#sphx-glr-auto-examples-plot-fgw-py>`__ + solver <auto_examples/gromov/plot_fgw.html#sphx-glr-auto-examples-plot-fgw-py>`__ and `FGW - barycenters <auto_examples/plot_barycenter_fgw.html>`__ + barycenters <auto_examples/gromov/plot_barycenter_fgw.html>`__ [24] - `Stochastic solver <auto_examples/plot_stochastic.html>`__ for Large-scale Optimal Transport (semi-dual problem [18] and dual problem [19]) - Non regularized `free support Wasserstein - barycenters <auto_examples/plot_free_support_barycenter.html>`__ + barycenters <auto_examples/barycenters/plot_free_support_barycenter.html>`__ [20]. - `Unbalanced - OT <auto_examples/plot_UOT_1D.html>`__ + OT <auto_examples/unbalanced-partial/plot_UOT_1D.html>`__ with KL relaxation and - `barycenter <auto_examples/plot_UOT_barycenter_1D.html>`__ + `barycenter <auto_examples/unbalanced-partial/plot_UOT_barycenter_1D.html>`__ [10, 25]. - `Partial Wasserstein and - Gromov-Wasserstein <auto_examples/plot_partial_wass_and_gromov.html>`__ + Gromov-Wasserstein <auto_examples/unbalanced-partial/plot_partial_wass_and_gromov.html>`__ (exact [29] and entropic [3] formulations). POT provides the following Machine Learning related solvers: - `Optimal transport for domain - adaptation <auto_examples/plot_otda_classes.html>`__ + adaptation <auto_examples/domain-adaptation/plot_otda_classes.html>`__ with `group lasso - regularization <auto_examples/plot_otda_classes.html>`__, + regularization <auto_examples/domain-adaptation/plot_otda_classes.html>`__, `Laplacian - regularization <auto_examples/plot_otda_laplacian.html>`__ + regularization <auto_examples/domain-adaptation/plot_otda_laplacian.html>`__ [5] [30] and `semi supervised - setting <auto_examples/plot_otda_semi_supervised.html>`__. + setting <auto_examples/domain-adaptation/plot_otda_semi_supervised.html>`__. - `Linear OT - mapping <auto_examples/plot_otda_linear_mapping.html>`__ + mapping <auto_examples/domain-adaptation/plot_otda_linear_mapping.html>`__ [14] and `Joint OT mapping - estimation <auto_examples/plot_otda_mapping.html>`__ + estimation <auto_examples/domain-adaptation/plot_otda_mapping.html>`__ [8]. - `Wasserstein Discriminant - Analysis <auto_examples/plot_WDA.html>`__ + Analysis <auto_examples/others/plot_WDA.html>`__ [11] (requires autograd + pymanopt). - `JCPOT algorithm for multi-source domain adaptation with target - shift <auto_examples/plot_otda_jcpot.html>`__ + shift <auto_examples/domain-adaptation/plot_otda_jcpot.html>`__ [27]. -Some demonstrations are available in the +Some other examples are available in the `documentation <auto_examples/index.html>`__. 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: +POT using the following reference: :: - Rémi Flamary and Nicolas Courty, POT Python Optimal Transport library, Website: https://pythonot.github.io/, 2017 + Rémi Flamary and Nicolas Courty, POT Python Optimal Transport library, + Website: https://pythonot.github.io/, 2017 In Bibtex format: @@ -141,11 +142,11 @@ You can install the toolbox through PyPI with: pip install POT -or get the very latest version by downloading it and then running: +or get the very latest version by running: :: - python setup.py install --user # for user install (no root) + pip install -U https://github.com/PythonOT/POT/archive/master.zip # with --user for user install (no root) Anaconda installation with conda-forge ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -232,7 +233,7 @@ Examples and Notebooks ~~~~~~~~~~~~~~~~~~~~~~ The examples folder contain several examples and use case for the -library. The full documentation is available on +library. The full documentation with examples and output is available on https://PythonOT.github.io/. Acknowledgements @@ -245,7 +246,8 @@ This toolbox has been created and is maintained by The contributors to this library are -- `Alexandre Gramfort <http://alexandre.gramfort.net/>`__ (CI) +- `Alexandre Gramfort <http://alexandre.gramfort.net/>`__ (CI, + documentation) - `Laetitia Chapel <http://people.irisa.fr/Laetitia.Chapel/>`__ (Partial OT) - `Michael Perrot <http://perso.univ-st-etienne.fr/pem82055/>`__ @@ -452,8 +454,6 @@ NIPS Workshop on Optimal Transport and Machine Learning OTML, 2014. :target: https://badge.fury.io/py/POT .. |Anaconda Cloud| image:: https://anaconda.org/conda-forge/pot/badges/version.svg :target: https://anaconda.org/conda-forge/pot -.. |Build Status| image:: https://travis-ci.org/PythonOT/POT.svg?branch=master - :target: https://travis-ci.org/PythonOT/POT .. |Build Status| image:: https://github.com/PythonOT/POT/workflows/build/badge.svg :target: https://github.com/PythonOT/POT/actions .. |Codecov Status| image:: https://codecov.io/gh/PythonOT/POT/branch/master/graph/badge.svg diff --git a/docs/source/releases.rst b/docs/source/releases.rst new file mode 100644 index 0000000..075108f --- /dev/null +++ b/docs/source/releases.rst @@ -0,0 +1,260 @@ +Releases +======== + +0.6 +--- + +*July 2019* + +This is the first official stable release of POT and this means a jump +to 0.6! The library has been used in the wild for a while now and we +have reached a state where a lot of fundamental OT solvers are available +and tested. It has been quite stable in the last months but kept the +beta flag in its Pypi classifiers until now. + +Note that this release will be the last one supporting officially Python +2.7 (See https://python3statement.org/ for more reasons). For next +release we will keep the travis tests for Python 2 but will make them +non necessary for merge in 2020. + +The features are never complete in a toolbox designed for solving +mathematical problems and research but with the new contributions we now +implement algorithms and solvers from 24 scientific papers (listed in +the README.md file). New features include a direct implementation of the +`empirical Sinkhorn +divergence <all.html#ot.bregman.empirical_sinkhorn_divergence>`__ +, a new efficient (Cython implementation) solver for `EMD in +1D <all.html#ot.lp.emd_1d>`__ and +corresponding `Wasserstein +1D <all.html#ot.lp.wasserstein_1d>`__. +We now also have implementations for `Unbalanced +OT <auto_examples/plot_UOT_1D.html>`__ +and a solver for `Unbalanced OT +barycenters <auto_examples/plot_UOT_barycenter_1D.html>`__. +A new variant of Gromov-Wasserstein divergence called `Fused +Gromov-Wasserstein <all.html?highlight=fused_#ot.gromov.fused_gromov_wasserstein>`__ +has been also contributed with exemples of use on `structured +data <auto_examples/plot_fgw.html>`__ +and computing `barycenters of labeld +graphs <auto_examples/plot_barycenter_fgw.html>`__. + +A lot of work has been done on the documentation with several new +examples corresponding to the new features and a lot of corrections for +the docstrings. But the most visible change is a new `quick start +guide <quickstart.html>`__ for POT +that gives several pointers about which function or classes allow to +solve which specific OT problem. When possible a link is provided to +relevant examples. + +We will also provide with this release some pre-compiled Python wheels +for Linux 64bit on github and pip. This will simplify the install +process that before required a C compiler and numpy/cython already +installed. + +Finally we would like to acknowledge and thank the numerous contributors +of POT that has helped in the past build the foundation and are still +contributing to bring new features and solvers to the library. + +Features +^^^^^^^^ + +- Add compiled manylinux 64bits wheels to pip releases (PR #91) +- Add quick start guide (PR #88) +- Make doctest work on travis (PR #90) +- Update documentation (PR #79, PR #84) +- Solver for EMD in 1D (PR #89) +- Solvers for regularized unbalanced OT (PR #87, PR#99) +- Solver for Fused Gromov-Wasserstein (PR #86) +- Add empirical Sinkhorn and empirical Sinkhorn divergences (PR #80) + +Closed issues +^^^^^^^^^^^^^ + +- Issue #59 fail when using "pip install POT" (new details in doc+ + hopefully wheels) +- Issue #85 Cannot run gpu modules +- Issue #75 Greenkhorn do not return log (solved in PR #76) +- Issue #82 Gromov-Wasserstein fails when the cost matrices are + slightly different +- Issue #72 Macosx build problem + +0.5.0 +----- + +*Sep 2018* + +POT is 2 years old! This release brings numerous new features to the +toolbox as listed below but also several bug correction. + +| Among the new features, we can highlight a `non-regularized + Gromov-Wasserstein + solver <auto_examples/plot_gromov.html>`__, + a new `greedy variant of + sinkhorn <all.html#ot.bregman.greenkhorn>`__, +| `non-regularized <all.html#ot.lp.barycenter>`__, + `convolutional + (2D) <auto_examples/plot_convolutional_barycenter.html>`__ + and `free + support <auto_examples/plot_free_support_barycenter.html>`__ + Wasserstein barycenters and + `smooth <https://github.com/rflamary/POT/blob/prV0.5/notebooks/plot_OT_1D_smooth.html>`__ + and + `stochastic <all.html#ot.stochastic.sgd_entropic_regularization>`__ + implementation of entropic OT. + +POT 0.5 also comes with a rewriting of ot.gpu using the cupy framework +instead of the unmaintained cudamat. Note that while we tried to keed +changes to the minimum, the OTDA classes were deprecated. If you are +happy with the cudamat implementation, we recommend you stay with stable +release 0.4 for now. + +The code quality has also improved with 92% code coverage in tests that +is now printed to the log in the Travis builds. The documentation has +also been greatly improved with new modules and examples/notebooks. + +This new release is so full of new stuff and corrections thanks to the +old and new POT contributors (you can see the list in the +`readme <https://github.com/rflamary/POT/blob/master/README.md>`__). + +Features +^^^^^^^^ + +- Add non regularized Gromov-Wasserstein solver (PR #41) +- Linear OT mapping between empirical distributions and 90% test + coverage (PR #42) +- Add log parameter in class EMDTransport and SinkhornLpL1Transport (PR + #44) +- Add Markdown format for Pipy (PR #45) +- Test for Python 3.5 and 3.6 on Travis (PR #46) +- Non regularized Wasserstein barycenter with scipy linear solver + and/or cvxopt (PR #47) +- Rename dataset functions to be more sklearn compliant (PR #49) +- Smooth and sparse Optimal transport implementation with entropic and + quadratic regularization (PR #50) +- Stochastic OT in the dual and semi-dual (PR #52 and PR #62) +- Free support barycenters (PR #56) +- Speed-up Sinkhorn function (PR #57 and PR #58) +- Add convolutional Wassersein barycenters for 2D images (PR #64) +- Add Greedy Sinkhorn variant (Greenkhorn) (PR #66) +- Big ot.gpu update with cupy implementation (instead of un-maintained + cudamat) (PR #67) + +Deprecation +^^^^^^^^^^^ + +Deprecated OTDA Classes were removed from ot.da and ot.gpu for version +0.5 (PR #48 and PR #67). The deprecation message has been for a year +here since 0.4 and it is time to pull the plug. + +Closed issues +^^^^^^^^^^^^^ + +- Issue #35 : remove import plot from ot/\ **init**.py (See PR #41) +- Issue #43 : Unusable parameter log for EMDTransport (See PR #44) +- Issue #55 : UnicodeDecodeError: 'ascii' while installing with pip + +0.4 +--- + +*15 Sep 2017* + +This release contains a lot of contribution from new contributors. + +Features +^^^^^^^^ + +- Automatic notebooks and doc update (PR #27) +- Add gromov Wasserstein solver and Gromov Barycenters (PR #23) +- emd and emd2 can now return dual variables and have max\_iter (PR #29 + and PR #25) +- New domain adaptation classes compatible with scikit-learn (PR #22) +- Proper tests with pytest on travis (PR #19) +- PEP 8 tests (PR #13) + +Closed issues +^^^^^^^^^^^^^ + +- emd convergence problem du to fixed max iterations (#24) +- Semi supervised DA error (#26) + +0.3.1 +----- + +*11 Jul 2017* + +- Correct bug in emd on windows + +0.3 +--- + +*7 Jul 2017* + +- emd\* and sinkhorn\* are now performed in parallel for multiple + target distributions +- emd and sinkhorn are for OT matrix computation +- emd2 and sinkhorn2 are for OT loss computation +- new notebooks for emd computation and Wasserstein Discriminant + Analysis +- relocate notebooks +- update documentation +- clean\_zeros(a,b,M) for removimg zeros in sparse distributions +- GPU implementations for sinkhorn and group lasso regularization + +V0.2 +---- + +*7 Apr 2017* + +- New dimensionality reduction method (WDA) +- Efficient method emd2 returns only tarnsport (in paralell if several + histograms given) + +0.1.11 +------ + +*5 Jan 2017* + +- Add sphinx gallery for better documentation +- Small efficiency tweak in sinkhorn +- Add simple tic() toc() functions for timing + +0.1.10 +------ + +*7 Nov 2016* \* numerical stabilization for sinkhorn (log domain and +epsilon scaling) + +0.1.9 +----- + +*4 Nov 2016* + +- Update classes and examples for domain adaptation +- Joint OT matrix and mapping estimation + +0.1.7 +----- + +*31 Oct 2016* + +- Original Domain adaptation classes + +0.1.3 +----- + +- pipy works + +First pre-release +----------------- + +*28 Oct 2016* + +It provides the following solvers: \* OT solver for the linear program/ +Earth Movers Distance. \* Entropic regularization OT solver with +Sinkhorn Knopp Algorithm. \* Bregman projections for Wasserstein +barycenter [3] and unmixing. \* Optimal transport for domain adaptation +with group lasso regularization \* Conditional gradient and Generalized +conditional gradient for regularized OT. + +Some demonstrations (both in Python and Jupyter Notebook format) are +available in the examples folder. |