Skip to content

Python API reference

Generated from the docstrings of the public API. For explanations and examples, start with Concepts and the how-to guides.

Losses between point clouds

remblais.SamplesLoss

Bases: Module

Loss between two weighted point clouds, compatible with GeomLoss 0.3.1.

Create the loss once, then call it like a function: loss(x, y) (uniform weights), loss(a, x, b, y) (explicit weights) or loss(l_x, a, x, l_y, b, y) (explicit cluster labels, multiscale backend). Points have shape (N, D), or (B, N, D) for a batch; weights have shape (N,) or (B, N). The result is a scalar, or a (B,) tensor for a batch, differentiable with respect to the points and the weights.

Parameters:

Name Type Description Default
loss

"sinkhorn" (debiased Sinkhorn divergence), "hausdorff", "energy", "gaussian" or "laplacian".

'sinkhorn'
p

exponent of the default cost: ‖x − y‖ for p = 1, ½‖x − y‖² for p = 2.

2
blur

length scale σ. Entropic regularization uses ε = blurᵖ; for kernel losses, it is the width of the kernel.

0.05
reach

None for balanced transport, or a length scale for unbalanced transport (ρ = reachᵖ).

None
diameter

an upper bound on the distance between points, where the ε-scaling starts; estimated from the data when None.

None
scaling

ratio between successive blur values of the ε-scaling, between 0 and 1. Larger is slower and more accurate.

0.5
truncate

multiscale backend: pairs of clusters whose interaction is below exp(−truncate) are skipped; None keeps every pair.

5
cost

a custom cost: a KeOps formula string such as "Norm2(X-Y)", a Python function (on tensors with tensorized, on kernox formulas with online and multiscale), a (formula, dense routine) pair, or a remblais.Cost.

None
kernel

a custom kernel, for loss="hausdorff".

None
cluster_scale

multiscale backend: size of the grid cells; estimated from the data when None.

None
debias

subtract the self-transport terms, so that the loss of a measure with itself is zero.

True
potentials

return the dual potentials (F, G) instead of the value.

False
verbose

print the clustering and the ε-scaling schedule.

False
backend

"auto", "tensorized" (dense PyTorch matrices), "online" (fused kernox reductions) or "multiscale" (clustering and block-sparse kernox reductions, dimension 3 or less).

'auto'
fast_math

specific to remblais. None (default): approximate exp and log in the kernox reductions on NVIDIA GPUs in FP32, as PyKeOps does under GeomLoss, and IEEE arithmetic elsewhere. False: IEEE arithmetic everywhere. True: ask kernox for fast math (no effect in FP64 and on the CPU oracle, refused by the backends that do not offer it).

None

Images and volumes

The function below is exported as remblais.sinkhorn_divergence, the name it has in GeomLoss.

remblais.sinkhorn_images.sinkhorn_divergence(a, b, p=2, blur=None, reach=None, axes=None, scaling=0.5, cost=None, debias=True, potentials=False, verbose=False, **kwargs)

Sinkhorn divergence between densities on a regular grid, multiscale.

Exported as remblais.sinkhorn_divergence. The pixels sit on the grid [0, 1)ᴰ with a step of 1/N.

Parameters:

Name Type Description Default
a

source densities, (B, K, N, N) for images or (B, K, N, N, N) for volumes; N must be a power of 2.

required
b

target densities, same shape as a.

required
p

exponent of the cost: |x − y|²/2 for p = 2, the L1 distance for p = 1.

2
blur

length scale σ, ε = blurᵖ; one pixel (1/N) when None.

None
reach

None for balanced transport, or a length scale for unbalanced transport.

None
scaling

ratio of the ε-scaling, in [0.5, 1).

0.5
debias

subtract the self-transport terms.

True
potentials

return the dual potentials (F, G) instead of the value.

False
verbose

print the pyramid and the ε-scaling schedule.

False

Returns:

Type Description

a (B,) tensor, summed over the K channels, or (F, G).

remblais.ImagesBarycenter(measures, weights, blur=0, p=2, scaling_N=10, backward_iterations=5)

Wasserstein barycenter of images (debiased Sinkhorn, Janati et al. 2020).

Same parameters and same algorithm as GeomLoss 0.3.1.

Parameters:

Name Type Description Default
measures

(B, K, N, N) densities, N a power of 2.

required
weights

(B, K) barycentric weights, summing to 1.

required
blur

length scale; 0 means one pixel, 1/N.

0
p

exponent of the cost.

2
scaling_N

number of iterations per level of the image pyramid.

10
backward_iterations

number of final iterations that are differentiated when an input requires a gradient.

5

Returns:

Type Description

the (B, 1, N, N) barycenter.

Custom costs and kernels

remblais.keops_string_cost(s)

Cost from a KeOps formula string, with variables X and Y.

The string is parsed by remblais, with the common subset of the KeOps grammar listed in remblais.costs.FUNCTIONS (SqDist, Norm2, SqNorm2, Sum, Square, Sqrt, Exp, Log, IntCst, Pow, Powf, ...), (a|b) and arithmetic, and works with every backend. SamplesLoss(cost="...") calls it for you.

remblais.Cost

Transport cost: a kernox formula (online backends) and a dense matrix (tensorized backend).

formula(x, y) receives two Formula objects (Vi, Vj) and returns a scalar formula; dense(x, y) receives (B, N, D), (B, M, D) or (N, D), (M, D) tensors and returns the cost matrix.

kernel_formula and factor (optional): C = factor · kernel_formula. The online plans then use kernel_formula and the parameter s = factor/ε (one multiplication per pair instead of one per coordinate: symox distributes constants over sums).

remblais.Kernel

Kernel: formula(x, y, s) (kernox), param(blur) → s, and dense(x, y, blur=...).

The ot module

The docstrings of this module come from GeomLoss 0.3.1; their references to geomloss.ot apply to remblais.ot.

remblais.ot.solve(C, *, reg, a=None, b=None, unbalanced=None, unbalanced_type='KL', method='auto', max_iter=None, tol=None)

Solves an optimal transport problem with an explicit cost matrix.

.. warning:: The interface of this solver is still in development and may change in future releases. We welcome any feedback and suggestions for improvement.

We focus on entropy-regularized OT and support both the balanced setting (with strict transport constraints) and the unbalanced setting (with softer constraints on the marginals of the transport plan).

Given a source measure $\alpha$ sampled with $N$ points, a target measure $\beta$ sampled with $M$ points and a $N$-by-$M$ cost matrix $C$, the primal formulation of the problem $\text{OT}_{\varepsilon, \rho}(\alpha, \beta)$ reads:

.. math::

\min_{\pi \in \mathbb{R}_+^{N \times M}} \sum_{i=1}^N \sum_{j=1}^M C_{ij} \pi_{ij}
+ \varepsilon \text{KL}(\pi, \alpha \otimes \beta)
+ \text{D}_\rho(\pi 1_M, \alpha)
+ \text{D}_\rho(\pi^\top 1_N, \beta)~,

where:

  • $\pi$ is the transport plan, a non-negative matrix of shape $(N,M)$.
  • $\varepsilon > 0$ is the regularization strength or temperature.
  • $\text{KL}(\pi, \alpha \otimes \beta)$ is the relative entropy of $\pi$ with respect to the reference product measure $\alpha \otimes \beta$:

.. math::

\text{KL}(\pi, \alpha \otimes \beta) = \sum_{i=1}^N \sum_{j=1}^M \pi_{ij} \log\left( \frac{\pi_{ij}}{\alpha_i \beta_j} \right) - \pi_{ij} + \alpha_i \beta_j~.
  • $\text{D}_\rho$ is a penalty on the marginal constraints, weighted by a positive parameter $\rho$.

  • If $\rho = +\infty$, we are in the balanced setting and $\text{D}_{\rho}$ encodes a hard constraint on the marginals of $\pi$: $\pi 1_M = \alpha$ and $\pi^\top 1_N = \beta$.

  • If $\rho < +\infty$, we are in the unbalanced setting and $\text{D}_\rho$ encodes a softer penalty on the marginal constraints, which allows for partial transport of the source measure $\alpha$ onto the target $\beta$. Currently, we only support the Kullback-Leibler divergence as unbalanced OT penalty, in which case we have:

.. math::

\text{D}_\rho(\pi 1_M, \alpha) = \rho \cdot \text{KL}(\pi 1_M, \alpha)~,~ \\
\text{D}_\rho(\pi^\top 1_N, \beta) = \rho \cdot \text{KL}(\pi^\top 1_N, \beta)~.

Parameters:

Name Type Description Default
C

Cost matrix: $C_{ij}$ denotes the cost of transporting a unit of mass from point $x_i$ in the source measure $\alpha$ to point $y_j$ in the target measure $\beta$.

required
reg

Regularization strength or temperature $\varepsilon$. It should be understood as a fuzziness parameter that is applied to the cost matrix: $\varepsilon = \max_{i,j} C_{ij} - \min_{i,j} C_{ij}$ corresponds to a very fuzzy problem, and leads to an optimal transport plan that is close to the product measure $\alpha \otimes \beta$. On the other hand, $\varepsilon \rightarrow 0$ corresponds to the original cost matrix, without any fuzziness, and leads to a sparse optimal transport plan. In practice, we recommend using a value of $\varepsilon$ that is small compared to the scale of the cost matrix, but not too small to avoid numerical issues. A good default value is $\varepsilon = 0.001 \cdot (\max_{i,j} C_{ij} - \min_{i,j} C_{ij})$.

required
a

First marginal: $\alpha_i$ denotes the mass associated to point $x_i$ in the source measure $\alpha$. If not provided, we assume that $a$ is the uniform distribution on $N$ points, i.e. $\alpha_i = 1/N$ for all $i$.

None
b

Second marginal: $\beta_j$ denotes the mass associated to point $y_j$ in the target measure $\beta$. If not provided, we assume that $b$ is the uniform distribution on $M$ points, i.e. $\beta_j = 1/M$ for all $j$.

None
unbalanced

Scaling factor $\rho$ for the unbalanced OT penalty on the marginal constraints. If unbalanced is :mod:None, we solve the balanced OT problem and look for a full transport of the source marginal $\alpha$ onto the target $\beta$. If unbalanced is a positive :mod:float $\rho > 0$, we solve an unbalanced OT problem where the marginal constraints are relaxed and penalized with a soft penalty parameterized by $\rho$.

None
unbalanced_type UnbalancedType

Type of unbalanced OT penalty to use when unbalanced is not :mod:None. Currently, we only support the Kullback-Leibler divergence "KL", also known as the relative entropy.

'KL'
method SupportedMethods

Optimization method to use. Currently, we only support the symmetrized Sinkhorn algorithm with annealing, which is activated by the keyword "auto".

'auto'
max_iter

Maximum number of iterations for the optimization algorithm. If :mod:None, the algorithm runs until convergence.

None
tol

Tolerance for convergence. If :mod:None, we use a default tolerance based on the regularization strength $\varepsilon$ and the scale of the cost matrix $C$.

None

Returns:

Type Description
OTResultMatrix

An object containing the optimal transport plan, the dual potentials and other related quantities as attributes.

Examples:

.. testcode::

from geomloss import ot

# Solve a balanced, 2x3 OT problem with entropic regularization:
solution = ot.solve(
    C=[[0., 1., 4.],
       [2., 1., 0.]],
    a=[2, 2],
    b=[1, 1, 2],
    reg=0.001,
    max_iter=100,
)
print(solution.plan)

.. testoutput::

[[1. 1. 0.]
 [0. 0. 2.]]

.. testcode::

print(f"{solution.value:.3f}")

.. testoutput::

0.997

remblais.ot.solve_batch(C, *, reg, a=None, b=None, unbalanced=None, unbalanced_type='KL', method='auto', max_iter=None, tol=None)

Batched version of :func:~geomloss.ot.solve, which can solve multiple OT problems in parallel.

.. warning:: The interface of this solver is still in development and may change in future releases. We welcome any feedback and suggestions for improvement.

Parameters:

Name Type Description Default
C

Batch of $B$ cost matrices: $C_{ij}^{(b)}$ denotes the cost of transporting a unit of mass from point $x_i$ in the source measure $\alpha^{(b)}$ to point $y_j$ in the target measure $\beta^{(b)}$ for the $b$-th OT problem in the batch.

required
a

Batch of $B$ first marginals: $\alpha_i^{(b)}$ denotes the mass associated to point $x_i$ in the source measure $\alpha^{(b)}$ for the $b$-th OT problem in the batch. If not provided, we assume that $a$ is the uniform distribution on $N$ points for each problem in the batch, i.e. $\alpha_i^{(b)} = 1/N$ for all $i$ and $b$.

None
b

Batch of $B$ second marginals: $\beta_j^{(b)}$ denotes the mass associated to point $y_j$ in the target measure $\beta^{(b)}$ for the $b$-th OT problem in the batch. If not provided, we assume that $b$ is the uniform distribution on $M$ points for each problem in the batch, i.e. $\beta_j^{(b)} = 1/M$ for all $j$ and $b$.

None
Notes

Other parameters are identical to those of :func:~geomloss.ot.solve. They are applied uniformly to all problems in the batch.

Returns:

Type Description
OTResultMatrix

An object containing the optimal transport plans, the dual potentials and other related quantities for each problem in the batch as attributes.

Examples:

.. testcode::

from geomloss import ot
# Solve a batch of 2 balanced, 2x3 OT problems with entropic regularization:
solution = ot.solve_batch(
    C=[[[0., 1., 4.],
        [2., 1., 0.]],
       [[0., 2., 3.],
        [1., 0., 1.]]],
    a=[[2, 2],
       [1, 3]],
    b=[[1, 1, 2],
       [2, 1, 1]],
    reg=0.001,
    max_iter=1000,
)
print(solution.plan)

.. testoutput::

[[[1.    1.    0.   ]
  [0.    0.    2.   ]]

 [[1.005 0.    0.   ]
  [0.988 1.003 1.003]]]

.. testcode::

print(f"{solution.value}")

.. testoutput::

[0.997 1.995]

remblais.ot.solve_sample(X_a, X_b, a=None, b=None, cost='sqeuclidean', debias=False, reg=None, unbalanced=None, unbalanced_type='KL', method='auto', max_iter=None, tol=None, blur=None, reach=None)

Solves an optimal transport problem between point clouds.

.. warning:: The interface of this solver is still in development and may change in future releases. We welcome any feedback and suggestions for improvement.

Using the notations of the documentation of :func:~geomloss.ot.solve, this function focuses on the case where the values of the cost matrix $C_{ij} = C(x_i, y_j)$ are not provided as input, but are instead computed on the fly from the coordinates of the samples $x_i$ (stored in the array X_a) and $y_j$ (stored in the array X_b). This is the most common setting in geometric applications, where the cost is typically a power of the Euclidean distance between the points.

Parameters:

Name Type Description Default
X_a

Coordinates of the $N$ samples $x_1, \dots, x_N$ of the source measure $\alpha$.

required
X_b

Coordinates of the $M$ samples $y_1, \dots, y_M$ of the target measure $\beta$.

required
cost

Cost function, either specified as a string (e.g. "sqeuclidean") or as a Python callable that takes as input two arrays of coordinates and returns the cost matrix.

Currently, we only support "sqeuclidean" as a string shortcut for the squared Euclidean distance.

'sqeuclidean'
debias

Whether to compute the debiased Sinkhorn divergence, which returns an unbiased estimate of the unregularized OT cost without shrinking artifacts (the so-called "entropic bias"). This is desirable when the value of the optimal transport problem is used as a loss function.

False
blur

Redundant parameter that specifies the regularization strength as $\texttt{reg} = \varepsilon = 2 * \texttt{blur}^2$, when the cost is the squared Euclidean distance. This is a more intuitive parameter for geometric applications, since it corresponds to the "blurring radius" $\sigma$ of the kernel $k(x,y) = e^{-|x-y|^2 / 2 \sigma^2} = e^{-|x-y|^2 / \varepsilon}$. This parameter should not be used together with reg, which is a more general regularization parameter that can be used with any cost and any regularization type.

None
reach

Redundant parameter that specifies the unbalanced OT penalty strength as $\texttt{unbalanced} = \rho = 2 * \texttt{reach}^2$, when the cost is the squared Euclidean distance.

None
Notes

Other parameters are identical to those of :func:~geomloss.ot.solve and control the regularization strength, the unbalanced OT penalty type and strength, the optimization method and parameters, etc. See the documentation of :func:~geomloss.ot.solve for more details.

Examples:

.. testcode::

from geomloss import ot

solution = ot.solve_sample(
    X_a=[[0, 0], [0, 2]],
    X_b=[[2, 1], [2, 2]],
    reg=0.001,
    max_iter=100,
)
print(solution.plan)

.. testoutput::

[[0.5 0. ]
 [0.  0.5]]

.. testcode::

print(f"{solution.value:.3f}")

.. testoutput::

4.501

remblais.ot.OTResult

Abstract class for optimal transport results.

An OT solver returns an object that inherits from OTResult (e.g. SinkhornOTResult) and implements the relevant methods (e.g. "plan" and "lazy_plan" but not "sparse_plan", etc.). log is a dictionary containing potential information about the solver

remblais.ot.OTResultMatrix

Bases: OTResult

Stores the result of an optimal transport problem computed using an explicit cost matrix.

Users may access the optimal transport plan, the dual potentials and other related quantities as attributes of this class. Under the hood, these attributes are computed lazily and cached for efficiency. In the documentation below, $B$ denotes the batch size while $N$ and $M$ denote the number of samples in the source and target measures, respectively.

remblais.ot.OTResultSample

Bases: OTResult

Stores the result of an optimal transport problem computed using point positions.

Users may access the optimal transport plan, the dual potentials and other related quantities as attributes of this class. Under the hood, these attributes are computed lazily and cached for efficiency. In the documentation below, $N$ and $M$ denote the number of samples in the source and target measures, respectively.

remblais.ot.LinearOperator

Linear operator that can be applied to arrays, without being explicitly instantiated as a matrix.

.. automethod:: matmul

shape property

For compatibility with e.g. SciPy's LinearOperator class.

T property

Alias for :meth:transpose .

transpose()

Returns the transposed linear operator.

from_dense(dense_matrix, *, input_shape, output_shape) classmethod

Returns a :class:LinearOperator that behaves like the given dense matrix.

from_lazy_tensor(lazy_tensor, *, input_shape, output_shape) classmethod

Returns a :class:LinearOperator that behaves like the given KeOps :class:LazyTensor.

rescale(*, input_scaling, output_scaling)

Returns a new :class:LinearOperator that behaves like the original one, but with rescaled inputs and outputs.

LazyTensor

remblais.lazy

Minimal LazyTensor on kernox (a subset of pykeops.torch.LazyTensor).

It serves the remblais.ot API (a port of geomloss.ot), written for KeOps, and GeomLoss-style custom kernels. KeOps conventions:

  • LazyTensor(t) with t of shape (*B, N, 1, D): an i variable; (*B, 1, M, D): a j variable; (*B, 1, 1, D): a parameter;
  • a Python number becomes a parameter of the plan (its value is not part of the compilation key: C / eps does not recompile when ε changes);
  • shape is (*B, N, M) for a scalar formula, (*B, N, M, D) otherwise;
  • reductions sum, logsumexp, min, max over dim = the i axis (−3 + ...) or j, returning (*B, N, D) (or (*B, M, D)); K @ v (v dense (M, V)); K.T swaps i and j.

NumPy inputs are accepted (computed with Torch on the CPU, NumPy output). Gradients: those of kernox (torch.autograd) with respect to the leaf tensors.