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'
|
|
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
|
|
diameter
|
an upper bound on the distance between points, where the
ε-scaling starts; estimated from the data when |
None
|
|
scaling
|
ratio between successive blur values of the ε-scaling, between 0 and 1. Larger is slower and more accurate. |
0.5
|
|
truncate
|
|
5
|
|
cost
|
a custom cost: a KeOps formula string such as
|
None
|
|
kernel
|
a custom kernel, for |
None
|
|
cluster_scale
|
|
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'
|
|
fast_math
|
specific to remblais. |
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 |
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
|
|
reach
|
|
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
|
|
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
|
|
unbalanced_type
|
UnbalancedType
|
Type of unbalanced OT penalty to use when unbalanced is not :mod: |
'KL'
|
method
|
SupportedMethods
|
Optimization method to use. Currently, we only support the symmetrized Sinkhorn algorithm
with annealing, which is activated by the keyword |
'auto'
|
max_iter
|
Maximum number of iterations for the optimization algorithm.
If :mod: |
None
|
|
tol
|
Tolerance for convergence.
If :mod: |
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. Currently, we only support |
'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 |
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)withtof 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 / epsdoes not recompile when ε changes); shapeis(*B, N, M)for a scalar formula,(*B, N, M, D)otherwise;- reductions
sum,logsumexp,min,maxoverdim= the i axis (−3 + ...) or j, returning(*B, N, D)(or(*B, M, D));K @ v(v dense (M, V));K.Tswaps 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.