Geometric Loss functions between sampled measures, images and volumes
---------------------------------------------------------------------
The **GeomLoss** library provides efficient GPU implementations for:
- `Kernel norms `_
(also known as `Maximum Mean Discrepancies `_).
- `Hausdorff divergences `_, which are
positive definite generalizations of the
`Chamfer-ICP `_ loss
and are
analogous to **log-likelihoods** of Gaussian Mixture Models.
- `Debiased Sinkhorn divergences `_, which are
affordable yet **positive and definite** approximations of
`Optimal Transport `_
(`Wasserstein `_) distances.
It is hosted on `GitHub `_
and distributed under the permissive `MIT license `_. |br|
|PyPi version| |Downloads|
GeomLoss functions
are available through the custom `PyTorch `_ layers
:class:`SamplesLoss `,
:class:`ImagesLoss ` and
:class:`VolumesLoss `
which allow you to work with weighted **point clouds** (of any dimension),
**density maps** and **volumetric segmentation masks**.
Geometric losses come with three backends each:
- A simple ``tensorized`` implementation, for **small problems** (< 5,000 samples).
- A reference ``online`` implementation, with a **linear** (instead of quadratic)
**memory footprint**, that can be used for finely sampled measures.
- A very fast ``multiscale`` code, which uses an
**octree**-like structure for large-scale problems in dimension <= 3.
A typical sample of code looks like:
.. code-block:: python
import torch
from geomloss import SamplesLoss # See also ImagesLoss, VolumesLoss
# Create some large point clouds in 3D
x = torch.randn(100000, 3, requires_grad=True).cuda()
y = torch.randn(200000, 3).cuda()
# Define a Sinkhorn (~Wasserstein) loss between sampled measures
loss = SamplesLoss(loss="sinkhorn", p=2, blur=.05)
L = loss(x, y) # By default, use constant weights = 1/number of samples
g_x, = torch.autograd.grad(L, [x]) # GeomLoss fully supports autograd!
GeomLoss is a simple interface for cutting-edge Optimal Transport
algorithms. It provides:
* Support for **batchwise** computations.
* **Linear** (instead of quadratic) **memory footprint** for large problems,
relying on the `KeOps library `_
for map-reduce operations on the GPU.
* Fast **kernel truncation** for small bandwidths, using an octree-based structure.
* Log-domain stabilization of the Sinkhorn iterations,
eliminating numeric **overflows** for small values of :math:`\varepsilon`.
* Efficient computation of the **gradients**, which bypasses the naive
backpropagation algorithm.
* Support for `unbalanced `_
Optimal `Transport `_,
with a softening of the marginal constraints
through a maximum **reach** parameter.
* Support for the `ε-scaling heuristic `_
in the Sinkhorn loop, with `kernel truncation `_
in dimensions 1, 2 and 3.
On typical 3D problems, our implementation is **50-100 times faster** than
the standard `SoftAssign/Sinkhorn algorithm `_.
Note, however, that :class:`SamplesLoss ` does *not* implement the
`Fast Multipole `_
or `Fast Gauss `_ transforms.
If you are aware of a well-packaged implementation
of these algorithms on the GPU, please contact me!
The divergences implemented here are
all **symmetric**, **positive definite**
and therefore suitable for measure-fitting applications.
For positive input measures :math:`\alpha` and :math:`\beta`,
our :math:`\text{Loss}` functions are such that
.. math::
\text{Loss}(\alpha,\beta) ~&=~ \text{Loss}(\beta,\alpha), \\
0~=~\text{Loss}(\alpha,\alpha) ~&\leqslant~ \text{Loss}(\alpha,\beta), \\
0~=~\text{Loss}(\alpha,\beta)~&\Longleftrightarrow~ \alpha = \beta.
**GeomLoss** can be used in a wide variety of settings,
from **shape analysis** (LDDMM, optimal transport...)
to **machine learning** (kernel methods, GANs...)
and **image processing**.
Details and examples are provided below:
* :doc:`Maths and algorithms `
* :doc:`PyTorch API `
* `Source code `_
* :doc:`Examples <_auto_examples/index>`
Author and Contributors
-------------------------
Feel free to contact us for any **bug report** or **feature request**:
- `Jean Feydy `_
- `Pierre Roussillon `_ (extensions to brain tractograms and normal cycles)
Licensing, academic use
---------------------------
This library is licensed under the permissive `MIT license `_,
which is fully compatible with both **academic** and **commercial** applications.
If you use this code in a research paper, **please cite**:
::
@inproceedings{feydy2019interpolating,
title={Interpolating between Optimal Transport and MMD using Sinkhorn Divergences},
author={Feydy, Jean and S{\'e}journ{\'e}, Thibault and Vialard, Fran{\c{c}}ois-Xavier and Amari, Shun-ichi and Trouve, Alain and Peyr{\'e}, Gabriel},
booktitle={The 22nd International Conference on Artificial Intelligence and Statistics},
pages={2681--2690},
year={2019}
}
Related projects
------------------
You may be interested by:
- The `KeOps library `_, which provides
**efficient CUDA routines**
for point cloud processing, with full `PyTorch `_ support.
- Rémi Flamary's
`Python Optimal Transport library `_,
which provides a reference implementation of **OT-related methods** for small problems.
- Bernhard Schmitzer's `Optimal Transport toolbox `_,
which provides a reference **multiscale solver** for the OT problem, on the CPU.
Table of contents
-----------------
.. toctree::
:maxdepth: 2
api/install
api/geomloss
api/pytorch-api
_auto_examples/index
.. |PyPi version| image:: https://img.shields.io/pypi/v/geomloss?color=blue
:target: https://pypi.org/project/geomloss/
.. |Downloads| image:: https://pepy.tech/badge/geomloss?color=green
:target: https://pepy.tech/project/geomloss
.. |br| raw:: html