Solve the unbalanced optimal transport problem and return the OT plan using L-BFGS-B algorithm.
The function solves the following optimization problem:
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
\(\mathrm{div_m}\) is a divergence, either Kullback-Leibler divergence,
or half-squared \(\ell_2\) divergence, or Total variation
- \(\mathrm{div}\) is a divergence, either Kullback-Leibler divergence,
or half-squared \(\ell_2\) divergence
Note
This function is backend-compatible and will work on arrays
from all compatible backends. First, it converts all arrays into Numpy arrays,
then uses the L-BFGS-B algorithm from scipy.optimize to solve the optimization problem.
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – Unnormalized histogram of dimension dim_b
If b is an empty list or array ([]),
then b is set to uniform distribution.
c (array-like (dim_a, dim_b), optional (default = None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term: nonnegative (including 0) but cannot be infinity.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
If \(\mathrm{reg_{m}}\) is an array, it must be a Numpy array.
reg_div (string, optional) – Divergence used for regularization.
Can take three values: ‘entropy’ (negative entropy), or
‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared) or a tuple
of two calable functions returning the reg term and its derivative.
Note that the callable functions should be able to handle Numpy arrays
and not tesors from the backend
regm_div (string, optional) – Divergence to quantify the difference between the marginals.
Can take three values: ‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared) or ‘tv’ (Total Variation)
G0 (array-like (dim_a, dim_b)) – Initialization of the transport matrix
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
\(\mathrm{div_m}\) is a divergence, either Kullback-Leibler divergence,
or half-squared \(\ell_2\) divergence, or Total variation
- \(\mathrm{div}\) is a divergence, either Kullback-Leibler divergence,
or half-squared \(\ell_2\) divergence
Note
This function is backend-compatible and will work on arrays
from all compatible backends. First, it converts all arrays into Numpy arrays,
then uses the L-BFGS-B algorithm from scipy.optimize to solve the optimization problem.
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – Unnormalized histogram of dimension dim_b
If b is an empty list or array ([]),
then b is set to uniform distribution.
c (array-like (dim_a, dim_b), optional (default = None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term: nonnegative (including 0) but cannot be infinity.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
If \(\mathrm{reg_{m}}\) is an array, it must be a Numpy array.
reg_div (string, optional) – Divergence used for regularization.
Can take three values: ‘entropy’ (negative entropy), or
‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared) or a tuple
of two calable functions returning the reg term and its derivative.
Note that the callable functions should be able to handle Numpy arrays
and not tesors from the backend
regm_div (string, optional) – Divergence to quantify the difference between the marginals.
Can take three values: ‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared) or ‘tv’ (Total Variation)
G0 (array-like (dim_a, dim_b)) – Initialization of the transport matrix
returnCost (string, optional (default = "linear")) – If returnCost = “linear”, then return the linear part of the unbalanced OT loss.
If returnCost = “total”, then return the total unbalanced OT loss.
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target
unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
div is a divergence, either Kullback-Leibler or half-squared \(\ell_2\) divergence
The algorithm used for solving the problem is a maximization-
minimization algorithm as proposed in [41]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – Unnormalized histogram of dimension dim_b
If b is an empty list or array ([]),
then b is set to uniform distribution.
M (array-like (dim_a, dim_b)) – loss matrix
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term: nonnegative but cannot be infinity.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
reg (float, optional (default = 0)) – Regularization term >= 0.
By default, solve the unregularized problem
c (array-like (dim_a, dim_b), optional (default = None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
div (string, optional) – Divergence to quantify the difference between the marginals.
Can take two values: ‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared)
G0 (array-like (dim_a, dim_b)) – Initialization of the transport matrix
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target
unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
\(\mathrm{div}\) is a divergence, either Kullback-Leibler or half-squared \(\ell_2\) divergence
The algorithm used for solving the problem is a maximization-
minimization algorithm as proposed in [41]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – Unnormalized histogram of dimension dim_b
If b is an empty list or array ([]),
then b is set to uniform distribution.
M (array-like (dim_a, dim_b)) – loss matrix
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term: nonnegative but cannot be infinity.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
reg (float, optional (default = 0)) – Entropy regularization term >= 0.
By default, solve the unregularized problem
c (array-like (dim_a, dim_b), optional (default = None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = mathbf{a} mathbf{b}^T\).
div (string, optional) – Divergence to quantify the difference between the marginals.
Can take two values: ‘kl’ (Kullback-Leibler) or ‘l2’ (half-squared)
G0 (array-like (dim_a, dim_b)) – Initialization of the transport matrix
returnCost (string, optional (default = "linear")) – If returnCost = “linear”, then return the linear part of the unbalanced OT loss.
If returnCost = “total”, then return the total unbalanced OT loss.
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
KL is the Kullback-Leibler divergence
The algorithm used for solving the problem is the generalized Sinkhorn-Knopp matrix scaling algorithm as proposed in [10, 25]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – One or multiple unnormalized histograms of dimension dim_b.
If b is an empty list or array ([]),
then b is set to uniform distribution.
If many, compute all the OT costs \((\mathbf{a}, \mathbf{b}_i)_i\)
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
The entropic balanced OT can be recovered using \(\mathrm{reg_{m}}=float("inf")\).
For semi-relaxed case, use either
\(\mathrm{reg_{m}}=(float("inf"), scalar)\) or
\(\mathrm{reg_{m}}=(scalar, float("inf"))\).
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
reg_type (string, optional) – Regularizer term. Can take two values:
+ Negative entropy: ‘entropy’:
\(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\).
This is equivalent (up to a constant) to \(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\).
+ Kullback-Leibler divergence: ‘kl’:
\(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\).
c (array-like (dim_a, dim_b), optional (default=None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
If \(\texttt{reg_type}='entropy'\), then \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\).
warmstart (tuple of arrays, shape (dim_a, dim_b), optional) – Initialization of dual potentials. If provided, the dual potentials should be given
(that is the logarithm of the u, v sinkhorn scaling vectors).
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
KL is the Kullback-Leibler divergence
The algorithm used for solving the problem is the generalized
Sinkhorn-Knopp matrix scaling algorithm as proposed in [10, 25]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – One or multiple unnormalized histograms of dimension dim_b.
If b is an empty list or array ([]),
then b is set to uniform distribution.
If many, compute all the OT costs \((\mathbf{a}, \mathbf{b}_i)_i\)
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
The entropic balanced OT can be recovered using \(\mathrm{reg_{m}}=float("inf")\).
For semi-relaxed case, use either
\(\mathrm{reg_{m}}=(float("inf"), scalar)\) or
\(\mathrm{reg_{m}}=(scalar, float("inf"))\).
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
method (str) – method used for the solver either ‘sinkhorn’, ‘sinkhorn_stabilized’ or
‘sinkhorn_reg_scaling’, see those function for specific parameters
reg_type (string, optional) – Regularizer term. Can take two values:
+ Negative entropy: ‘entropy’:
\(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\).
This is equivalent (up to a constant) to \(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\).
+ Kullback-Leibler divergence: ‘kl’:
\(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\).
c (array-like (dim_a, dim_b), optional (default=None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
If \(\texttt{reg_type}='entropy'\), then \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\).
warmstart (tuple of arrays, shape (dim_a, dim_b), optional) – Initialization of dual potentials. If provided, the dual potentials should be given
(that is the logarithm of the u, v sinkhorn scaling vectors).
tau (float) – threshold for max value in u or v for log scaling
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (>0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
KL is the Kullback-Leibler divergence
The algorithm used for solving the problem is the generalized
Sinkhorn-Knopp matrix scaling algorithm as proposed in [10, 25]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – One or multiple unnormalized histograms of dimension dim_b.
If b is an empty list or array ([]),
then b is set to uniform distribution.
If many, compute all the OT costs \((\mathbf{a}, \mathbf{b}_i)_i\)
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
The entropic balanced OT can be recovered using \(\mathrm{reg_{m}}=float("inf")\).
For semi-relaxed case, use either
\(\mathrm{reg_{m}}=(float("inf"), scalar)\) or
\(\mathrm{reg_{m}}=(scalar, float("inf"))\).
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
method (str) – method used for the solver either ‘sinkhorn’, ‘sinkhorn_stabilized’, ‘sinkhorn_translation_invariant’ or
‘sinkhorn_reg_scaling’, see those function for specific parameters
reg_type (string, optional) – Regularizer term. Can take two values:
+ Negative entropy: ‘entropy’:
\(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\).
This is equivalent (up to a constant) to \(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\).
+ Kullback-Leibler divergence: ‘kl’:
\(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\).
c (array-like (dim_a, dim_b), optional (default=None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
If \(\texttt{reg_type}='entropy'\), then \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\).
warmstart (tuple of arrays, shape (dim_a, dim_b), optional) – Initialization of dual potentials. If provided, the dual potentials should be given
(that is the logarithm of the u, v sinkhorn scaling vectors).
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (>0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
\(\mathbf{c}\) is a reference distribution for the regularization
KL is the Kullback-Leibler divergence
The algorithm used for solving the problem is the generalized
Sinkhorn-Knopp matrix scaling algorithm as proposed in [10, 25]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
If a is an empty list or array ([]),
then a is set to uniform distribution.
b (array-like (dim_b,)) – One or multiple unnormalized histograms of dimension dim_b.
If b is an empty list or array ([]),
then b is set to uniform distribution.
If many, compute all the OT costs \((\mathbf{a}, \mathbf{b}_i)_i\)
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term.
If \(\mathrm{reg_{m}}\) is a scalar or an indexable object of length 1,
then the same \(\mathrm{reg_{m}}\) is applied to both marginal relaxations.
The entropic balanced OT can be recovered using \(\mathrm{reg_{m}}=float("inf")\).
For semi-relaxed case, use either
\(\mathrm{reg_{m}}=(float("inf"), scalar)\) or
\(\mathrm{reg_{m}}=(scalar, float("inf"))\).
If \(\mathrm{reg_{m}}\) is an array,
it must have the same backend as input arrays (a, b, M).
method (str) – method used for the solver either ‘sinkhorn’, ‘sinkhorn_stabilized’, ‘sinkhorn_translation_invariant’ or
‘sinkhorn_reg_scaling’, see those function for specific parameters
reg_type (string, optional) – Regularizer term. Can take two values:
+ Negative entropy: ‘entropy’:
\(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\).
This is equivalent (up to a constant) to \(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\).
+ Kullback-Leibler divergence: ‘kl’:
\(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\).
c (array-like (dim_a, dim_b), optional (default=None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
If \(\texttt{reg_type}='entropy'\), then \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\).
warmstart (tuple of arrays, shape (dim_a, dim_b), optional) – Initialization of dual potentials. If provided, the dual potentials should be given
(that is the logarithm of the u,v sinkhorn scaling vectors).
returnCost (string, optional (default = "linear")) – If returnCost = “linear”, then return the linear part of the unbalanced OT loss.
If returnCost = “total”, then return the total unbalanced OT loss.
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (>0)
verbose (bool, optional) – Print information along iterations
\(\mathbf{M}\) is the (dim_a, dim_b) metric cost matrix
\(\Omega\) is the entropic regularization term,KL divergence
\(\mathbf{a}\) and \(\mathbf{b}\) are source and target unbalanced distributions
KL is the Kullback-Leibler divergence
The algorithm used for solving the problem is the translation invariant Sinkhorn algorithm as proposed in [73]
Parameters:
a (array-like (dim_a,)) – Unnormalized histogram of dimension dim_a
b (array-like (dim_b,) or array-like (dim_b, n_hists)) – One or multiple unnormalized histograms of dimension dim_b
If many, compute all the OT distances (a, b_i)
reg_m (float or indexable object of length 1 or 2) – Marginal relaxation term.
If reg_m is a scalar or an indexable object of length 1,
then the same reg_m is applied to both marginal relaxations.
The entropic balanced OT can be recovered using reg_m=float(“inf”).
For semi-relaxed case, use either
reg_m=(float(“inf”), scalar) or reg_m=(scalar, float(“inf”)).
If reg_m is an array, it must have the same backend as input arrays (a, b, M).
reg_type (string, optional) – Regularizer term. Can take two values:
‘entropy’ (negative entropy)
\(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\), or
‘kl’ (Kullback-Leibler)
\(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\).
c (array-like (dim_a, dim_b), optional (default=None)) – Reference measure for the regularization.
If None, then use \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\).
If \(\texttt{reg_type}='entropy'\), then \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\).
warmstart (tuple of arrays, shape (dim_a, dim_b), optional) – Initialization of dual potentials. If provided, the dual potentials should be given
(that is the logarithm of the u,v sinkhorn scaling vectors).
numItermax (int, optional) – Max number of iterations
stopThr (float, optional) – Stop threshold on error (> 0)
verbose (bool, optional) – Print information along iterations