API和模块

ot:

backend	POT的多库后端
bregman	与熵正则化最优传输相关的Bregman投影求解器
coot	协同最优运输求解器
da	通过最优传输进行领域适应
datasets	简单示例数据集
dr	使用OT进行降维
factored	分解OT求解器（低秩，成本或OT计划）
gaussian	高斯分布的最优运输
gmm	高斯混合的最优传输
gnn	图神经网络中用于最优传输的层和函数。
gromov	与Gromov-Wasserstein问题相关的求解器。
lowrank	低秩OT求解器
lp	原始线性规划OT问题的求解器。
mapping	最优运输地图及其变体
optim	用于正则化OT或其半放松版本的通用求解器。
partial	部分OT求解器
plot	绘制OT矩阵的函数
regpath	正则化路径OT求解器
sliced	切片的OT距离
smooth	平滑和稀疏（KL和L2正则化）以及稀疏约束的最优传输求解器。
stochastic	用于正则化OT的随机求解器。
unbalanced	与不平衡最优运输问题相关的求解器。
utils	各种实用功能
weak	弱最优传输求解器

主要 功能

警告

自动导入的子模块列表如下： ot.lp, ot.bregman, ot.optim ot.utils, ot.datasets, ot.gromov, ot.smooth ot.stochastic, ot.partial, ot.regpath , ot.unbalanced, ot.mapping . 由于额外的依赖关系，以下子模块未被导入： - ot.dr : 依赖于 pymanopt 和 autograd。 - ot.plot : 依赖于 matplotlib

ot.barycenter(A, M, reg, weights=None, method='sinkhorn', numItermax=10000, stopThr=0.0001, verbose=False, log=False, warn=True, **kwargs)

计算分布的熵正则化 Wasserstein 重心 \(\mathbf{A}\)

该函数解决以下优化问题：

\[\mathbf{a} = \mathop{\arg \min}_\mathbf{a} \quad \sum_i W_{reg}(\mathbf{a},\mathbf{a}_i)\]

其中 :

• \(W_{reg}(\cdot,\cdot)\) 是熵正则化的沃瑟斯坦距离（见 ot.bregman.sinkhorn()），如果 method 是 sinkhorn 或 sinkhorn_stabilized 或 sinkhorn_log。

• \(\mathbf{a}_i\) 是矩阵中的训练分布 \(\mathbf{A}\) 的列

• reg 和 \(\mathbf{M}\) 分别是正则化项和 OT 的成本矩阵

用于解决该问题的算法是Sinkhorn-Knopp矩阵缩放算法，如[3]中所提议。

Parameters:

• A (类似数组, 形状 (维度, n_hists)) – n_hists 训练分布 \(\mathbf{a}_i\) 的大小为 dim

• M (类数组, 形状 (维度, 维度)) – OT 的损失矩阵

• reg (float) – 正则化项 > 0

• 方法 (str (可选)) – 求解器使用的方法，可以是‘sinkhorn’、‘sinkhorn_stabilized’或‘sinkhorn_log’

• weights (类数组, 形状 (n_hists,)) – 每个直方图 \(\mathbf{a}_i\) 在单纯形（重心坐标）的权重

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

• warn (bool, 可选) – 如果为True，当算法不收敛时会发出警告。

Returns:

• a ((dim,) 类数组) – Wasserstein 重心

• log (字典) – 仅在参数中log==True时返回日志字典

参考文献

[3]

Benamou, J. D., Carlier, G., Cuturi, M., Nenna, L., & Peyré, G. (2015). 用于正则化运输问题的迭代Bregman投影。 SIAM科学计算期刊, 37(2), A1111-A1138.

ot.barycenter_unbalanced(A, M, reg, reg_m, method='sinkhorn', weights=None, numItermax=1000, stopThr=1e-06, verbose=False, log=False, **kwargs)

计算\(\mathbf{A}\)的熵不平衡瓦瑟斯坦重心。

该函数解决以下优化问题，带有 \(\mathbf{a}\)

\[\mathbf{a} = \mathop{\arg \min}_\mathbf{a} \quad \sum_i W_{u_{reg}}(\mathbf{a},\mathbf{a}_i)\]

其中 :

• \(W_{u_{reg}}(\cdot,\cdot)\) 是不平衡的熵正则化Wasserstein距离（见 ot.unbalanced.sinkhorn_unbalanced()）

• \(\mathbf{a}_i\) 是矩阵 \(\mathbf{A}\) 列中的训练分布

• reg 和 \(\mathbf{M}\) 分别是正则化项和 OT 的成本矩阵

• reg_mis 是边际松弛超参数

用于解决该问题的算法是广义Sinkhorn-Knopp矩阵缩放算法，如[10]中所提出的。

Parameters:

• A (类似数组, 形状 (维度, n_hists)) – n_hists 的训练分布 \(\mathbf{a}_i\)，维度为 dim

• M (类数组, 形状 (维度, 维度)) – OT 的基础度量矩阵。

• reg (float) – 熵正则化项 > 0

• reg_m (float) – 边际放松项 > 0

• weights (array-like, shape (n_hists,) optional) – 每个分布的权重（重心坐标） 如果为 None，将使用均匀权重。

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (> 0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• a (数组类似，形状 (dim,)) – 不平衡的Wasserstein重心

• log (字典) – 仅在参数log==True时返回日志字典

参考文献

[3]

Benamou, J. D., Carlier, G., Cuturi, M., Nenna, L., & Peyré, G. (2015). 用于正则化运输问题的迭代Bregman投影。 SIAM科学计算杂志，37(2)，A1111-A1138。

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 用于不平衡运输问题的缩放算法。arXiv 预印本 arXiv:1607.05816.

ot.binary_search_circle(u_values, v_values, u_weights=None, v_weights=None, p=1, Lm=10, Lp=10, tm=-1, tp=1, eps=1e-06, require_sort=True, log=False)

使用在[44]中提出的二分搜索算法计算圆上的Wasserstein距离。样本需要在\(S^1\cong [0,1[\)中。如果它们在\(\mathbb{R}\)上，将取模1的值。如果值在\(S^1\subset\mathbb{R}^2\)上，需要先使用例如atan2函数找到坐标。

\[W_p^p(u,v) = \inf_{\theta\in\mathbb{R}}\int_0^1 |F_u^{-1}(q) - (F_v-\theta)^{-1}(q)|^p\ \mathrm{d}q\]

其中：

• \(F_u\) 和 \(F_v\) 分别是 \(u\) 和 \(v\) 的累积分布函数

对于值 \(x=(x_1,x_2)\in S^1\)，需要首先获取它们的坐标，方法是

\[u = \frac{\pi + \mathrm{atan2}(-x_2,-x_1)}{2\pi}\]

使用例如 ot.utils.get_coordinate_circle(x)

该函数在后台运行，但不支持tensorflow和jax。

Parameters:

• u_values (ndarray, shape (n, ...)) – 源域中的样本（坐标在 [0,1[）

• v_values (ndarray, shape (n, ...)) – 目标领域中的样本（坐标在 [0,1[ 上）

• u_weights (ndarray, shape (n, ...), optional) – 源领域中的样本权重

• v_weights (ndarray, shape (n, ...), 可选) – 目标域中的样本权重

• p (float, 可选 (默认=1)) – 用于计算Wasserstein距离的功率p

• Lm (int, 可选) – 下界 dC

• Lp (int, 可选) – 上限 dC

• tm (float, 可选) – 下限 theta

• tp (float, 可选) – 上界 theta

• eps (float, 可选) – 停止条件

• require_sort (bool, 可选) – 如果为 True，则对值进行排序。

• log (bool, 可选) – 如果为 True，还返回最优的 theta

Returns:

• loss (float) – 与最优运输相关的成本

• log (dict, optional) – 仅在参数中log==True时返回的日志字典

示例

>>> u = np.array([[0.2,0.5,0.8]])%1
>>> v = np.array([[0.4,0.5,0.7]])%1
>>> binary_search_circle(u.T, v.T, p=1)
array([0.1])

参考文献

[44]

Delon, Julie, Julien Salomon, 和 Andrei Sobolevski. “针对圆形上的Monge成本的快速运输优化。” SIAM应用数学杂志 70.7 (2010): 2239-2258.

ot.dist(x1, x2=None, metric='sqeuclidean', p=2, w=None)

计算样本之间的距离在 \(\mathbf{x_1}\) 和 \(\mathbf{x_2}\)

注意

此函数与后端兼容，并且适用于所有兼容后端的数组。

Parameters:

• x1 (类数组, 形状 (n1,d)) – 具有n1个样本，大小为d的矩阵

• x2 (类数组, 形状 (n2,d), 可选) – 大小为d的n2个样本的矩阵 (如果为None，则\(\mathbf{x_2} = \mathbf{x_1}\))

• metric (str | 可调用, 可选) – ‘sqeuclidean’ 或 ‘euclidean’ 在所有后端上。在 numpy 中，该函数还接受来自 scipy.spatial.distance.cdist 函数的：‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘kulczynski1’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’.

• p (float, 可选) – Minkowski 和加权 Minkowski 度量的 p-norm。默认值为 2。

• w (类数组, 1阶) – 加权指标的权重。

Returns:

M – 使用给定度量计算的距离矩阵

Return type:

类似数组，形状 (n1, n2)

ot.emd(a, b, M, numItermax=100000, log=False, center_dual=True, numThreads=1, check_marginals=True)

解决地球搬运工距离问题并返回OT矩阵

\[ \begin{align}\begin{aligned}\gamma = \mathop{\arg \min}_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F\\\text{s.t.} \ \gamma \mathbf{1} = \mathbf{a}\\ \gamma^T \mathbf{1} = \mathbf{b}\\ \gamma \geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是度量成本矩阵

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是样本权重

警告

请注意，\(\mathbf{M}\) 矩阵在numpy中需要是C顺序的 numpy.array，格式为float64。如果不是这种格式，将会被转换。

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

该函数将把计算得到的运输计划转换为提供的输入的数据类型，优先级如下：\(\mathbf{a}\)，然后是\(\mathbf{b}\)，最后是\(\mathbf{M}\)，如果没有提供边际。转换为整数张量可能会导致精度损失。如果不希望出现这种行为，请确保提供浮点输入。

注意

如果向量 \(\mathbf{a}\) 和 \(\mathbf{b}\) 的和不相等，将会引发错误。

采用了在 [1] 中提议的算法。

Parameters:

• a ((ns,) 数组类似, 浮点数) – 源直方图（如果空列表，则均匀权重）

• b ((nt,) 数组类似, 浮点数) – 目标直方图（如果空列表，均匀权重）

• M（(ns,nt) 类似数组, 浮动）– 损失矩阵（以float64类型的numpy c-顺序数组）

• numItermax (int, 可选 (默认=100000)) – 在优化算法未收敛的情况下，停止优化前的最大迭代次数。

• log (bool, 可选 (默认=False)) – 如果为真，返回一个包含成本和对偶变量的字典。否则仅返回最优运输矩阵。

• center_dual (布尔值, 可选 (默认=True)) – 如果为True，则使用函数 ot.lp.center_ot_dual()对对偶势能进行中心化。

• numThreads (int 或 "max", 可选 (默认=1, 即不使用OpenMP)) – 如果使用OpenMP编译，则选择并行化的线程数。“max”选择可能的最高数量。

• check_marginals (bool, optional (default=True)) – 如果为 True，将检查边际质量是否相等。如果为 False，跳过检查。

Returns:

• gamma (类似数组，形状为 (ns, nt)) – 给定参数的最优运输矩阵

• log (字典，可选) – 如果输入日志为真，将返回一个包含成本、对偶变量和退出状态的字典

示例

简单的例子，显而易见的解决方案。函数 emd 接受列表并自动转换为 numpy 数组

>>> import ot
>>> a=[.5,.5]
>>> b=[.5,.5]
>>> M=[[0.,1.],[1.,0.]]
>>> ot.emd(a, b, M)
array([[0.5, 0. ],
       [0. , 0.5]])

参考文献

[1]

Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011, 12月). 使用拉格朗日质量传输的位移插值。 发表于《ACM图形学汇刊》（TOG）（第30卷，第6期，第158页）。ACM。

另请参见

ot.bregman.sinkhorn

熵正则化最优传输

ot.optim.cg

通用正则化OT

ot.emd2(a, b, M, processes=1, numItermax=100000, log=False, return_matrix=False, center_dual=True, numThreads=1, check_marginals=True)

解决地球搬运工距离问题并返回损失

\[ \begin{align}\begin{aligned}\min_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F\\s.t. \ \gamma \mathbf{1} = \mathbf{a}\\ \gamma^T \mathbf{1} = \mathbf{b}\\ \gamma \geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是度量成本矩阵

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是样本权重

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

该函数将计算的运输计划和运输损失转换为提供的输入的数据类型，优先级如下：\(\mathbf{a}\)，然后 \(\mathbf{b}\)，最后在未提供边际值的情况下为 \(\mathbf{M}\)。转换为整数张量可能会导致精度的丢失。如果不希望出现这种情况，请确保提供浮点输入。

注意

如果向量 \(\mathbf{a}\) 和 \(\mathbf{b}\) 的和不相等，将会引发错误。

采用了在 [1] 中提议的算法。

Parameters:

• a ((ns,) 数组类型, 浮动64) – 源直方图（如果是空列表则均匀权重）

• b ((nt,) 数组样式, 浮动64) – 目标直方图（如果空列表，则为均匀权重）

• M ((ns,nt) 数组类似, float64) – 损失矩阵（用于类型为float64的numpy c-order数组）

• 进程 (int, 可选 (默认为1)) – 用于多重emd计算的进程数量（已弃用）

• numItermax (int, 可选 (默认=100000)) – 在优化算法未收敛的情况下，停止优化前的最大迭代次数。

• log (boolean, optional (default=False)) – 如果为 True，返回包含双重变量的字典。否则，仅返回最优运输成本。

• return_matrix (boolean, 可选 (默认=False)) – 如果为真，则返回日志中的最佳运输矩阵。

• center_dual (布尔值, 可选的 (默认=True)) – 如果为True，则使用函数 ot.lp.center_ot_dual() 来中心化对偶势能。

• numThreads (int 或 "max", 可选 (默认=1, 即不使用OpenMP)) – 如果使用OpenMP编译，则选择并行化的线程数。“max”选择可能的最高数量。

• check_marginals (bool, optional (default=True)) – 如果为 True，将检查边际质量是否相等。如果为 False，跳过检查。

Returns:

• W (float, array-like) – 给定参数的最优运输损失

• log (dict) – 如果输入日志为真，则包含对偶变量和退出状态的字典

示例

简单的例子，显而易见的解决方案。函数 emd 接受列表并自动转换为 numpy 数组

>>> import ot
>>> a=[.5,.5]
>>> b=[.5,.5]
>>> M=[[0.,1.],[1.,0.]]
>>> ot.emd2(a,b,M)
0.0

参考文献

[1]

Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011年12月). 使用拉格朗日质量传输的位移插值. 在ACM图形学汇刊(TOG) (第30卷, 第6期, 第158页). ACM.

另请参见

ot.bregman.sinkhorn

熵正则化最优传输

ot.optim.cg

通用正则化OT

ot.emd2_1d(x_a, x_b, a=None, b=None, metric='sqeuclidean', p=1.0, dense=True, log=False)

解决一维测量之间的地球搬运工距离问题并返回损失

\[ \begin{align}\begin{aligned}\gamma = arg\min_\gamma \sum_i \sum_j \gamma_{ij} d(x_a[i], x_b[j])\\s.t. \gamma 1 = a, \gamma^T 1= b, \gamma\geq 0\end{aligned}\end{align} \]

其中 :

• d 是该度量

• \(x_a\) 和 \(x_b\) 是样本

• a 和 b 是样本权重

该实现仅支持形式为 \(d(x, y) = |x - y|^p\) 的度量。

使用在 [1]_ 中详细描述的算法

Parameters:

• x_a (ndarray 的 float64, 形状 (ns,) 或 (ns, 1)) – 源 dirac 位置（在实数线上）

• x_b (ndarray 的 float64, 形状 (nt,) 或 (ns, 1)) – 目标狄拉克位置（在实线上）

• a (ndarray 类型 float64, 形状 (ns,), 可选) – 源直方图（默认是均匀权重）

• b (ndarray 的 float64, 形状 (nt,), 可选) – 目标直方图（默认是均匀权重）

• 度量 (str, 可选 (默认='sqeuclidean')) – 要使用的度量。仅适用于字符串 ‘sqeuclidean’, ‘minkowski’, ‘cityblock’ 或 ‘euclidean’.

• p (float, 可选 (默认为1.0)) – 如果 metric=’minkowski’，则应用的 p-norm

• dense (布尔值, 可选的 (默认=True)) – 如果为真，返回 \(\gamma\) 作为形状为 (ns, nt) 的密集 ndarray。否则，返回使用 scipy 的 coo_matrix 格式的稀疏表示。仅在 log 设置为 True 时使用。由于实现细节，当 dense 设置为 False 时，此函数运行速度更快。

• log (boolean, optional (default=False)) – 如果为True，返回一个包含运输矩阵的字典。否则仅返回损失。

Returns:

• loss (float) – 与最优运输相关的成本

• log (dict) – 如果输入日志为True，则包含给定参数的最优运输矩阵的字典

示例

简单的例子，解决方案明显。函数 emd2_1d 接受列表并执行自动转换为 numpy 数组

>>> import ot
>>> a=[.5, .5]
>>> b=[.5, .5]
>>> x_a = [2., 0.]
>>> x_b = [0., 3.]
>>> ot.emd2_1d(x_a, x_b, a, b)
0.5
>>> ot.emd2_1d(x_a, x_b)
0.5

参考文献

[1]

Peyré, G., & Cuturi, M. (2017). “计算最优运输”, 2018.

另请参见

ot.lp.emd2

多维分布的EMD

ot.lp.emd_1d

一维分布的EMD（返回运输矩阵而不是成本）

ot.emd_1d(x_a, x_b, a=None, b=None, metric='sqeuclidean', p=1.0, dense=True, log=False, check_marginals=True)

解决一维测量之间的地球搬运者距离问题并返回OT矩阵

\[ \begin{align}\begin{aligned}\gamma = arg\min_\gamma \sum_i \sum_j \gamma_{ij} d(x_a[i], x_b[j])\\s.t. \gamma 1 = a, \gamma^T 1= b, \gamma\geq 0\end{aligned}\end{align} \]

其中 :

• d 是该度量

• \(x_a\) 和 \(x_b\) 是样本

• a 和 b 是样本权重

该实现仅支持形式为 \(d(x, y) = |x - y|^p\) 的度量。

使用在 [1]_ 中详细描述的算法

Parameters:

• x_a (ndarray 类型 float64, 形状 (ns,) 或 (ns, 1)) – 源 dirac 位置（在实线上的位置）

• x_b (ndarray 的 float64, 形状 (nt,) 或 (ns, 1)) – 目标 Dirac 位置（在实际数线上）

• a (ndarray 类型 float64, 形状 (ns,), 可选) – 源直方图（默认是均匀权重）

• b (ndarray 的 float64, 形状 (nt,), 可选) – 目标直方图（默认是均匀权重）

• 度量 (str, 可选 (默认='sqeuclidean')) – 要使用的度量。仅适用于字符串 ‘sqeuclidean’, ‘minkowski’, ‘cityblock’ 或 ‘euclidean’.

• p (float, 可选 (默认为1.0)) – 如果 metric=’minkowski’，则应用的 p-norm

• dense (布尔值, 可选的 (默认=True)) – 如果为True，返回 \(\gamma\) 作为形状为 (ns, nt) 的密集 ndarray。否则返回使用 scipy 的 coo_matrix 格式的稀疏表示。由于实现细节，当使用 ‘sqeuclidean’、‘minkowski’、‘cityblock’ 或 ‘euclidean’ 指标时，此函数运行更快。

• log (布尔值, 可选 (默认=False)) – 如果为True，将返回一个包含成本的字典。否则仅返回最优运输矩阵。

• check_marginals (bool, optional (default=True)) – 如果为 True，将检查边际质量是否相等。如果为 False，跳过检查。

Returns:

• gamma (ndarray, shape (ns, nt)) – 给定参数的最优运输矩阵

• log (dict) – 如果输入的 log 为 True，则包含成本的字典

示例

简单的示例，显而易见的解决方案。函数 emd_1d 接受列表并进行自动转换为 numpy 数组

>>> import ot
>>> a=[.5, .5]
>>> b=[.5, .5]
>>> x_a = [2., 0.]
>>> x_b = [0., 3.]
>>> ot.emd_1d(x_a, x_b, a, b)
array([[0. , 0.5],
       [0.5, 0. ]])
>>> ot.emd_1d(x_a, x_b)
array([[0. , 0.5],
       [0.5, 0. ]])

参考文献

[1]

Peyré, G., & Cuturi, M. (2017). “计算最优运输”, 2018.

另请参见

ot.lp.emd

多维分布的EMD

ot.lp.emd2_1d

一维分布的EMD（返回成本而不是运输矩阵）

ot.factored_optimal_transport(Xa, Xb, a=None, b=None, reg=0.0, r=100, X0=None, stopThr=1e-07, numItermax=100, verbose=False, log=False, **kwargs)

解决分解的OT问题并返回OT计划和中间分配

此函数解决以下OT问题 [40]_

\[\mathop{\arg \min}_\mu \quad W_2^2(\mu_a,\mu)+ W_2^2(\mu,\mu_b)\]

其中 :

• \(\mu_a\) 和 \(\mu_b\) 是经验分布。

• \(\mu\) 是一个具有 r 个样本的经验分布

并返回两个OT计划之间

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

使用条件梯度算法来解决在 [39]中提出的问题。

Parameters:

• Xa ((ns,d) 数组类型, 浮点数) – 源样本

• Xb ((nt,d) 数组类型, 浮点数) – 目标样本

• a ((ns,) 数组类似, 浮点数) – 源直方图（如果空列表，则均匀权重）

• b ((nt,) 类数组, 浮点数) – 目标直方图（如果为空列表则为均匀权重）

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 相对变化的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• Ga (数组类型，形状为 (ns, r)) – 源与中间分布之间的最优运输矩阵

• Gb (数组类型，形状为 (r, nt)) – 中间与目标分布之间的最优运输矩阵

• X (数组类型，形状为 (r, d)) – 中间分布的支持

• log (字典，可选) – 如果输入日志为真，则返回包含成本和对偶变量及退出状态的字典

参考文献

[40]

Forrow, A., Hütter, J. C., Nitzan, M., Rigollet, P., Schiebinger, G., & Weed, J. (2019年4月). 通过分解耦合进行统计最优传输. 在第22届国际人工智能与统计会议上 (pp. 2454-2465). PMLR.

另请参见

ot.bregman.sinkhorn

熵正则化最优传输

ot.optim.cg

通用正则化OT

ot.fused_gromov_wasserstein(M, C1, C2, p=None, q=None, loss_fun='square_loss', symmetric=None, alpha=0.5, armijo=False, G0=None, log=False, max_iter=10000.0, tol_rel=1e-09, tol_abs=1e-09, **kwargs)

返回融合的 Gromov-Wasserstein 传输，介于 \((\mathbf{C_1}, \mathbf{Y_1}, \mathbf{p})\) 和 \((\mathbf{C_2}, \mathbf{Y_2}, \mathbf{q})\) 之间，具有节点特征矩阵 \(\mathbf{Y_1}\) 和 \(\mathbf{Y_2}\) 之间的成对距离矩阵 \(\mathbf{M}\) (见 [24])。

该函数使用条件梯度法解决以下优化问题：

\[ \begin{align}\begin{aligned}\mathbf{T}^* \in\mathop{\arg\min}_\mathbf{T} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} \mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} &= \mathbf{p}\\ \mathbf{T}^T \mathbf{1} &= \mathbf{q}\\ \mathbf{T} &\geq 0\end{aligned}\end{align} \]

其中：

• \(\mathbf{M}\): 特征跨域的度量成本矩阵

• \(\mathbf{C_1}\): 源空间中的度量成本矩阵

• \(\mathbf{C_2}\): 目标空间中的度量成本矩阵

• \(\mathbf{p}\): 源空间中的分布

• \(\mathbf{q}\): 目标空间中的分布

• L: 损失函数，用于考虑相似性矩阵和特征矩阵之间的不匹配

• \(\alpha\): 权衡参数

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

共轭梯度求解器中的所有计算均使用numpy进行，以限制内存开销。

注意

此函数将把计算出的运输计划转换为提供的输入\(\mathbf{M}\)的数据类型。转换为整数张量可能会导致精度损失。如果不想要这种行为，请确保提供浮点输入。

Parameters:

• M (类似数组, 形状 (ns, nt)) – 各域中特征之间的度量成本矩阵

• C1 (类似数组, 形状 (ns, ns)) – 表示源空间中结构的度量成本矩阵

• C2 (数组类型, 形状 (nt, nt)) – 在目标空间中代表结构的度量成本矩阵

• p (类数组, 形状 (ns,), 可选) – 源空间中的分布。如果默认为 None，则采用均匀分布。

• q (数组类型, 形状 (nt,), 可选) – 目标空间中的分布。如果保持默认值 None，将采用均匀分布。

• loss_fun (str, 可选) – 用于求解器的损失函数

• 对称 (布尔值, 可选) – C1 和 C2 是否被假设为对称。如果保持默认的 None 值，将进行对称性测试。否则，如果设置为 True（或 False），则 C1 和 C2 将被假设为对称（或不对称）。

• alpha (浮动, 可选) – 权衡参数 (0 < alpha < 1)

• armijo (bool, 可选) – 如果为真，则通过armijo研究找到线搜索的步长。否则使用封闭形式。如果存在收敛问题，请使用假。

• G0 (类似数组, 形状 (ns,nt), 可选) – 如果为 None，求解器的初始运输计划为 pq^T。否则 G0 必须满足边际约束，并将作为求解器的初始运输。

• log (bool, 可选) – 如果为真，则记录日志

• max_iter (int, 可选) – 最大迭代次数

• tol_rel (float, 可选) – 相对误差的停止阈值 (>0)

• tol_abs (float, 可选) – 绝对误差停止阈值 (>0)

• **kwargs (dict) – 参数可以直接传递给 ot.optim.cg 求解器

Returns:

• T（类似数组，形状（ns，nt））– 给定参数的最佳运输矩阵。

• log（dict）– 仅在参数中log==True时返回日志字典。

参考文献

[24]

Vayer Titouan, Chapel Laetitia, Flamary Rémi, Tavenard Romain 和 Courty Nicolas “结构化数据的最优传输及其在图上的应用”，国际机器学习大会 (ICML)。 2019.

[47]

Chowdhury, S., & Mémoli, F. (2019). 网络之间的Gromov–Wasserstein距离与稳定网络不变量。 信息与推理：IMA期刊, 8(4), 757-787.

ot.fused_gromov_wasserstein2(M, C1, C2, p=None, q=None, loss_fun='square_loss', symmetric=None, alpha=0.5, armijo=False, G0=None, log=False, max_iter=10000.0, tol_rel=1e-09, tol_abs=1e-09, **kwargs)

返回 \((\mathbf{C_1}, \mathbf{Y_1}, \mathbf{p})\) 和 \((\mathbf{C_2}, \mathbf{Y_2}, \mathbf{q})\) 之间的融合 Gromov-Wasserstein 距离，节点特征矩阵 \(\mathbf{Y_1}\) 和 \(\mathbf{Y_2}\) 之间的成对距离矩阵 \(\mathbf{M}\) （见 [24]）。

该函数使用条件梯度法解决以下优化问题：

\[ \begin{align}\begin{aligned}\mathbf{FGW} = \mathop{\min}_\mathbf{T} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} \mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} &= \mathbf{p}\\ \mathbf{T}^T \mathbf{1} &= \mathbf{q}\\ \mathbf{T} &\geq 0\end{aligned}\end{align} \]

其中：

• \(\mathbf{M}\): 特征跨域的度量成本矩阵

• \(\mathbf{C_1}\): 源空间中的度量成本矩阵

• \(\mathbf{C_2}\): 目标空间中的度量成本矩阵

• \(\mathbf{p}\): 源空间中的分布

• \(\mathbf{q}\): 目标空间中的分布

• L: 损失函数，用于考虑相似性矩阵和特征矩阵之间的不匹配

• \(\alpha\): 权衡参数

注意，当使用后端时，这个损失函数对于矩阵 (C1, C2, M) 和权重 (p, q) 是可微的，针对二次损失使用来自 [38]_ 的梯度。

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

共轭梯度求解器中的所有计算均使用numpy进行，以限制内存开销。

注意

此函数将把计算出的运输计划转换为提供的输入\(\mathbf{M}\)的数据类型。转换为整数张量可能会导致精度损失。如果不想要这种行为，请确保提供浮点输入。

Parameters:

• M (类似数组, 形状 (ns, nt)) – 各域中特征之间的度量成本矩阵

• C1 (类数组, 形状 (ns, ns)) – 表示源空间结构的度量成本矩阵。

• C2 (类数组, 形状 (nt, nt)) – 代表目标空间中结构的指标成本矩阵。

• p (类数组, 形状 (ns,), 可选) – 源空间中的分布。如果默认为 None，则采用均匀分布。

• q (数组类型, 形状 (nt,), 可选) – 目标空间中的分布。如果保持默认值 None，将采用均匀分布。

• loss_fun (str, 可选) – 求解器使用的损失函数。

• 对称 (布尔值, 可选) – C1 和 C2 是否被假设为对称。如果保持默认的 None 值，将进行对称性测试。否则，如果设置为 True（或 False），则 C1 和 C2 将被假设为对称（或不对称）。

• alpha (浮动, 可选) – 权衡参数 (0 < alpha < 1)

• armijo (bool, 可选) – 如果为True，则通过armijo研究找到线搜索的步长。否则使用封闭形式。如果存在收敛问题，请使用False。

• G0 (类似数组, 形状 (ns,nt), 可选) – 如果为 None，求解器的初始运输计划为 pq^T。否则 G0 必须满足边际约束，并将作为求解器的初始运输。

• log (bool, 可选) – 如果为真，则记录日志。

• max_iter (int, 可选) – 最大迭代次数

• tol_rel (float, 可选) – 相对误差的停止阈值 (>0)

• tol_abs (float, 可选) – 绝对误差停止阈值 (>0)

• **kwargs (dict) – 参数可以直接传递给 ot.optim.cg 求解器。

Returns:

• fgw-distance (float) – 给定参数的融合Gromov-Wasserstein距离。

• log (dict) – 仅当参数中log==True时返回日志字典。

参考文献

[24]

Vayer Titouan, Chapel Laetitia, Flamary Rémi, Tavenard Romain 和 Courty Nicolas “针对结构化数据的最优传输及其在图上的应用” 国际机器学习会议 (ICML)。2019.

[38]

C. Vincent-Cuaz, T. Vayer, R. Flamary, M. Corneli, N. Courty, 在线图字典学习, 国际机器学习会议 (ICML), 2021.

[47]

Chowdhury, S., & Mémoli, F. (2019). 网络之间的Gromov–Wasserstein距离与稳定网络不变量。 信息与推理：IMA期刊, 8(4), 757-787.

ot.gromov_barycenters(N, Cs, ps=None, p=None, lambdas=None, loss_fun='square_loss', symmetric=True, armijo=False, max_iter=1000, tol=1e-09, stop_criterion='barycenter', warmstartT=False, verbose=False, log=False, init_C=None, random_state=None, **kwargs)

返回 S 测量相似性矩阵的 Gromov-Wasserstein 重心 \((\mathbf{C}_s)_{1 \leq s \leq S}\)

该函数解决以下带块坐标下降法的优化问题：

\[\mathbf{C}^* = \mathop{\arg \min}_{\mathbf{C}\in \mathbb{R}^{N \times N}} \quad \sum_s \lambda_s \mathrm{GW}(\mathbf{C}, \mathbf{C}_s, \mathbf{p}, \mathbf{p}_s)\]

其中：

• \(\mathbf{C}_s\): 指标成本矩阵

• \(\mathbf{p}_s\): 分布

Parameters:

• N (int) – 目标重心的大小

• Cs (列表 的 S 类似数组，形状为 (ns, ns)) – 评估成本矩阵

• ps (列表 的 S 类数组，形状为 (ns,), 可选) – 在S空间中的样本权重。如果设置为默认值 None，则采用均匀分布。

• p (类数组对象, 形状 (N,), 可选) – 目标重心中的权重。 如果将其设置为默认值 None，则采用均匀分布。

• lambdas (list of float, 可选) – S 空间的权重列表。 如果留空默认值为 None，则采用均匀权重。

• loss_fun (可调用, 可选) – 基于特定损失函数的张量-矩阵乘法函数

• 对称的 (布尔值, 可选的.) – 结构是否被假设为对称。默认值为 True。如果设置为 True（或 False），C1 和 C2 将被假设为对称（或不对称）。

• armijo (bool, 可选) – 如果为True，则通过armijo研究找到线搜索的步长。否则使用封闭形式。如果存在收敛问题，请使用False。

• max_iter (int, 可选) – 最大迭代次数

• tol (float, 可选) – 停止相对误差的阈值 (>0)

• stop_criterion (str, 可选。默认值为'barycenter'。) – 停止标准取值为 [‘barycenter’, ‘loss’]。如果设置为‘barycenter’，则使用估计的重心的绝对范数变化。否则如果设置为‘loss’，则使用损失的相对变化。

• warmstartT (bool, 可选) – 是否在后续的融合Gromov-Wasserstein传输问题中执行传输计划的热启动。

• verbose (bool, optional) – 在迭代过程中打印信息。

• log (bool, 可选) – 如果为真，则记录日志。

• init_C (bool | array-like, shape(N,N)) – 用户提供的\(\mathbf{C}\)矩阵的随机初始值。

• random_state (int 或 RandomState 实例, 可选) – 固定种子以保证可重复性

Returns:

• C (类数组，形状 (N, N)) – 在重心空间中的相似性矩阵（任意置换）

• log (dict) – 仅在 log=True 时返回。它包含以下键：

  • \(\mathbf{T}\): (N, ns) 传输矩阵的列表

  • \(\mathbf{p}\): (N,) 重心权重

  • 用于收敛评估的值。

参考文献

[12]

加布里埃尔·佩耶雷，马尔科·库图里和贾斯廷·所罗门， “核和距离矩阵的Gromov-Wasserstein平均。” 国际机器学习会议（ICML）。 2016年。

ot.gromov_wasserstein(C1, C2, p=None, q=None, loss_fun='square_loss', symmetric=None, log=False, armijo=False, G0=None, max_iter=10000.0, tol_rel=1e-09, tol_abs=1e-09, **kwargs)

返回 \((\mathbf{C_1}, \mathbf{p})\) 和 \((\mathbf{C_2}, \mathbf{q})\) 之间的 Gromov-Wasserstein 传输。

该函数使用条件梯度法解决以下优化问题：

\[ \begin{align}\begin{aligned}\mathbf{T}^* \in \mathop{\arg \min}_\mathbf{T} \quad \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} \mathbf{T}_{k,l}\\s.t. \ \mathbf{\gamma} \mathbf{1} &= \mathbf{p}\\ \mathbf{\gamma}^T \mathbf{1} &= \mathbf{q}\\ \mathbf{\gamma} &\geq 0\end{aligned}\end{align} \]

其中：

• \(\mathbf{C_1}\): 源空间中的度量成本矩阵。

• \(\mathbf{C_2}\): 目标空间中的度量成本矩阵。

• \(\mathbf{p}\): 源空间中的分布。

• \(\mathbf{q}\): 目标空间中的分布。

• L: 用于考虑相似度矩阵之间不匹配的损失函数。

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

共轭梯度求解器中的所有计算均使用numpy进行，以限制内存开销。

注意

此函数将把计算出的运输计划转换为提供的输入数据类型 \(\mathbf{C}_1\)。转换为整数张量可能会导致精度损失。如果不希望出现这种行为，请确保提供浮点输入。

Parameters:

• C1 (类数组, 形状 (ns, ns)) – 源空间中的度量成本矩阵。

• C2 (类似数组, 形状 (nt, nt)) – 目标空间中的度量成本矩阵。

• p (类数组, 形状 (ns,), 可选) – 源空间中的分布。如果默认为 None，则采用均匀分布。

• q (数组类型, 形状 (nt,), 可选) – 目标空间中的分布。如果保持默认值 None，将采用均匀分布。

• loss_fun (str, 可选) – 求解器使用的损失函数，可以是‘square_loss’或‘kl_loss’。

• 对称 (布尔值, 可选) – C1 和 C2 是否被假设为对称。如果保持默认的 None 值，将进行对称性测试。否则，如果设置为 True（或 False），则 C1 和 C2 将被假设为对称（或不对称）。

• verbose (bool, optional) – 在迭代过程中打印信息。

• log (bool, 可选) – 如果为真，则记录日志。

• armijo (bool, 可选) – 如果为 True，线性搜索的步长通过 armijo 搜索找到。否则使用封闭形式。如果存在收敛问题，请使用 False。

• G0 (数组类型, 形状 (ns,nt), 可选) – 如果为 None，则求解器的初始运输计划为 pq^T。否则 G0 必须满足边际约束，将作为求解器的初始运输使用。

• max_iter (int, 可选) – 最大迭代次数。

• tol_rel (float, 可选) – 相对误差的停止阈值 (>0)。

• tol_abs (float, 可选) – 绝对误差的停止阈值 (>0)。

• **kwargs (dict) – 参数可以直接传递给 ot.optim.cg 求解器。

Returns:

• T (类似数组，形状 (ns, nt)) –

  最小化两个空间之间的耦合：

  \(\sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} \mathbf{T}_{k,l}\)

• log (dict) – 收敛信息和损失。

参考文献

[12]

加布里埃尔·佩耶雷，马尔科·库图里和贾斯廷·所罗门， “核和距离矩阵的Gromov-Wasserstein平均。” 国际机器学习会议（ICML）。 2016年。

[13]

Mémoli, Facundo. Gromov–Wasserstein 距离与对象匹配的度量方法。《计算数学基础》 11.4 (2011): 417-487.

[47]

Chowdhury, S., & Mémoli, F. (2019). 网络之间的Gromov–Wasserstein距离与稳定网络不变量。 信息与推理：IMA期刊, 8(4), 757-787.

ot.gromov_wasserstein2(C1, C2, p=None, q=None, loss_fun='square_loss', symmetric=None, log=False, armijo=False, G0=None, max_iter=10000.0, tol_rel=1e-09, tol_abs=1e-09, **kwargs)

返回 Gromov-Wasserstein 损失 \(\mathbf{GW}\) 之间 \((\mathbf{C_1}, \mathbf{p})\) 和 \((\mathbf{C_2}, \mathbf{q})\)。 要恢复在 [13] 中定义的 Gromov-Wasserstein 距离，计算 \(d_{GW} = \frac{1}{2} \sqrt{\mathbf{GW}}\)。

该函数使用条件梯度法解决以下优化问题：

\[ \begin{align}\begin{aligned}\mathbf{GW} = \min_\mathbf{T} \quad \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} \mathbf{T}_{k,l}\\s.t. \ \mathbf{\gamma} \mathbf{1} &= \mathbf{p}\\ \mathbf{\gamma}^T \mathbf{1} &= \mathbf{q}\\ \mathbf{\gamma} &\geq 0\end{aligned}\end{align} \]

其中：

• \(\mathbf{C_1}\): 源空间中的度量成本矩阵

• \(\mathbf{C_2}\): 目标空间中的度量成本矩阵

• \(\mathbf{p}\): 源空间中的分布

• \(\mathbf{q}\): 目标空间中的分布

• L: 用于考虑相似性矩阵之间不匹配的损失函数

请注意，当使用后端时，该损失函数对矩阵 (C1, C2) 和权重 (p, q) 是可微的，用于二次损失，使用来自 [38]_ 的梯度。

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

注意

共轭梯度求解器中的所有计算均使用numpy进行，以限制内存开销。

注意

此函数将把计算出的运输计划转换为提供的输入数据类型 \(\mathbf{C}_1\)。转换为整数张量可能会导致精度损失。如果不希望出现这种行为，请确保提供浮点输入。

Parameters:

• C1 (类似数组, 形状 (ns, ns)) – 源空间中的度量成本矩阵

• C2 (类似数组, 形状 (nt, nt)) – 目标空间中的度量成本矩阵

• p (类数组, 形状 (ns,), 可选) – 源空间中的分布。如果默认为 None，则采用均匀分布。

• q (数组类型, 形状 (nt,), 可选) – 目标空间中的分布。如果保持默认值 None，将采用均匀分布。

• loss_fun (str) – 解算器使用的损失函数，可以是‘square_loss’或‘kl_loss’

• 对称 (布尔值, 可选) – C1 和 C2 是否被假设为对称。如果保持默认的 None 值，将进行对称性测试。否则，如果设置为 True（或 False），则 C1 和 C2 将被假设为对称（或不对称）。

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

• armijo (bool, 可选) – 如果为真，则通过armijo研究找到线搜索的步长。否则使用封闭形式。如果存在收敛问题，请使用假。

• G0 (类似数组, 形状 (ns,nt), 可选) – 如果为 None，求解器的初始运输计划为 pq^T。否则 G0 必须满足边际约束，并将作为求解器的初始运输。

• max_iter (int, 可选) – 最大迭代次数

• tol_rel (float, 可选) – 相对误差的停止阈值 (>0)

• tol_abs (float, 可选) – 绝对误差停止阈值 (>0)

• **kwargs (dict) – 参数可以直接传递给 ot.optim.cg 求解器

Returns:

• gw_dist (float) – Gromov-Wasserstein 距离

• log (dict) – 收敛信息和耦合矩阵

参考文献

[12]

加布里埃尔·佩耶雷，马尔科·库图里和贾斯廷·所罗门， “核和距离矩阵的Gromov-Wasserstein平均。” 国际机器学习会议（ICML）。 2016年。

[13]

Mémoli, Facundo. Gromov–Wasserstein 距离与对象匹配的度量方法。《计算数学基础》 11.4 (2011): 417-487.

[38]

C. Vincent-Cuaz, T. Vayer, R. Flamary, M. Corneli, N. Courty, 在线图字典学习, 国际机器学习会议 (ICML), 2021.

[47]

Chowdhury, S., & Mémoli, F. (2019). 网络之间的Gromov–Wasserstein距离与稳定网络不变量。 信息与推理：IMA期刊, 8(4), 757-787.

ot.lowrank_gromov_wasserstein_samples(X_s, X_t, a=None, b=None, reg=0, rank=None, alpha=1e-10, gamma_init='rescale', rescale_cost=True, cost_factorized_Xs=None, cost_factorized_Xt=None, stopThr=0.0001, numItermax=1000, stopThr_dykstra=0.001, numItermax_dykstra=10000, seed_init=49, warn=True, warn_dykstra=False, log=False)

在耦合和成本矩阵上解决低非负秩约束下的熵正则化Gromov-Wasserstein运输问题。

平方欧几里得距离矩阵被认为是目标和源分布。

该函数解决以下优化问题：

\[\mathop{\min_{(Q,R,g) \in \mathcal{C(a,b,r)}}} \mathcal{Q}_{A,B}(Q\mathrm{diag}(1/g)R^T) - \epsilon \cdot H((Q,R,g))\]

其中 :

• \(A\) 是源领域的（dim_a, dim_a）平方成对成本矩阵。

• \(B\) 是目标域的 (dim_a, dim_a) 平方成对成本矩阵。

• \(\mathcal{Q}_{A,B}\) 是 Gromov Wasserstein 计划的二次目标函数。

• \(Q\) 和 R 是 Gromov-Wasserstein 计划的低秩矩阵分解。

• \(g\) 是 Gromov-Wasserstein 计划的低秩分解的权重向量。

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源权重和目标权重（直方图，均为 1 的和）。

• \(r\) 是 Gromov-Wasserstein 规划的秩。

• \(\mathcal{C(a,b,r)}\) 是OT问题的低秩耦合。

• \(H((Q,R,g))\) 是对每个项计算的三个各自熵的值。

Parameters:

• X_s (数组类型, 形状 (n_samples_a, dim_Xs)) – 源域中的样本

• X_t (类数组型, 形状 (n_samples_b, dim_Xt)) – 目标域中的样本

• a (数组类似, 形状 (n_samples_a,), 可选) – 源域中的样本权重 如果让它使用默认值 None，将采用均匀分布。

• b (数组类型, 形状 (n_samples_b,), 可选) – 目标域中的样本权重 如果保持默认值 None，则采用均匀分布。

• reg (float, 可选) – 正则化项 >=0

• rank (int, 可选。默认值为 None。 (>0)) – OT 计划的非负等级。如果为 None，则考虑 min(ns, nt)。

• alpha (int, 可选，默认值为 1e-10。 (>0 且 <1/r)) – 权重向量 g 的下限。

• rescale_cost (bool, 可选。默认为 False) – 重新缩放平方欧几里得成本矩阵的低秩分解

• seed_init (int, 可选。默认值为 49。 (>0)) – 用于低秩耦合的“随机”初始化的随机状态

• gamma_init (str, 可选。默认值为 "rescale"。) – gamma 的初始化策略。‘rescale’，或 ‘theory’ Gamma 是一个常数，用于缩放镜像下降优化方案的收敛标准，该方案用于计算低秩耦合 (Q, R 和 g)

• numItermax (int, 可选。默认为 1000。) – 低秩 GW 的最大迭代次数

• stopThr (float, 可选。默认值是 1e-4。) – 低秩GW的误差停止阈值 (>0) 误差是针对每个低秩耦合 (Q, R 和 g) 计算的Kullback散度的总和，并使用gamma进行缩放。

• numItermax_dykstra (int, 可选。默认为2000。) – Dykstra算法的最大迭代次数

• stopThr_dykstra (float, 可选。默认值为 1e-7。) – Dykstra 中的错误停止阈值 (>0)

• cost_factorized_Xs (tuple, 可选。默认是 None) – 包含源成本矩阵的两个预计算低秩分解 (A1, A2) 的元组。两个矩阵的形状应为 (n_samples_a, dim_Xs + 2)。如果为 None，低秩成本矩阵将作为平方欧几里得成本矩阵计算。

• cost_factorized_Xt (tuple, 可选。默认值为 None) – 包含目标成本矩阵的两个预计算低秩分解 (B1, B2) 的元组。两个矩阵的形状应为 (n_samples_b, dim_Xt + 2)。如果为 None，将计算低秩成本矩阵作为 sqeuclidean 成本矩阵。

• warn (bool, optional) – 如果为 True，当低秩 GW 算法未收敛时，会引发警告。

• warn_dykstra (bool, 可选) – 如果为 True，在 Dykstra 算法未收敛时会引发警告。

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• Q (类数组，形状 (n_samples_a, r)) – OT计划的第一低秩矩阵分解

• R (类数组，形状 (n_samples_b, r)) – OT计划的第二低秩矩阵分解

• g (类数组，形状 (r, )) – OT的低秩分解的权重向量

• log (字典 (lazy_plan, value 和 value_linear)) – 仅当参数中的log==True时返回log字典

参考文献

[67]

Scetbon, M., Peyré, G. & Cuturi, M. (2022). “线性时间的Gromov-Wasserstein距离，使用低秩耦合和成本”。 在国际机器学习大会（ICML），2022。

ot.lowrank_sinkhorn(X_s, X_t, a=None, b=None, reg=0, rank=None, alpha=1e-10, rescale_cost=True, init='random', reg_init=0.1, seed_init=49, gamma_init='rescale', numItermax=2000, stopThr=1e-07, warn=True, log=False)

在耦合的低非负秩约束下解决熵正则化最优传输问题。

该函数解决以下优化问题：

\[\mathop{\inf_{(\mathbf{Q},\mathbf{R},\mathbf{g}) \in \mathcal{C}(\mathbf{a},\mathbf{b},r)}} \langle \mathbf{C}, \mathbf{Q}\mathrm{diag}(1/\mathbf{g})\mathbf{R}^\top \rangle - \mathrm{reg} \cdot H((\mathbf{Q}, \mathbf{R}, \mathbf{g}))\]

其中 :

• \(\mathbf{C}\) 是 (dim_a, dim_b) 计量成本矩阵

• \(H((\mathbf{Q}, \mathbf{R}, \mathbf{g}))\) 是分别对每个项评估的三个相应熵的值。

• \(\mathbf{Q}\) 和 \(\mathbf{R}\) 是OT计划的低秩矩阵分解

• \(\mathbf{g}\) 是OT计划的低秩分解的权重向量

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源权重和目标权重（直方图，两者之和为1）

• \(r\) 是 OT 计划的等级

• \(\mathcal{C}(\mathbf{a}, \mathbf{b}, r)\) 是OT问题的低秩耦合

Parameters:

• X_s (类数组, 形状 (n_samples_a, 维度)) – 源域中的样本

• X_t (类似数组, 形状 (n_samples_b, 维度)) – 目标域中的样本

• a (类数组, 形状 (n_samples_a,)) – 源域中的样本权重

• b (数组类型, 形状 (n_samples_b,)) – 目标领域中的样本权重

• reg (float, 可选) – 正则化项 >0

• rank (int, 可选。默认值为 None。 (>0)) – OT 计划的非负等级。如果为 None，则考虑 min(ns, nt)。

• alpha (int, 可选，默认值为 1e-10。 (>0 且 <1/r)) – 权重向量 g 的下限。

• rescale_cost (bool, 可选。默认为 False) – 重新缩放平方欧几里得成本矩阵的低秩分解

• init (str, 可选。默认值为'random'。) – 低秩耦合的初始化策略。‘random’，‘deterministic’或‘kmeans’

• reg_init (float, 可选。默认值为 1e-1。 (>0)) – 用于‘kmeans’初始化的正则化项。如果为 None，则考虑为 1。

• seed_init (int, 可选。默认值为49。 (>0)) – 用于“随机”或“kmeans”初始化策略的随机状态。

• gamma_init (str, 可选。默认值为 "rescale"。) – gamma 的初始化策略。‘rescale’，或 ‘theory’ Gamma 是一个常数，用于缩放镜像下降优化方案的收敛标准，该方案用于计算低秩耦合 (Q, R 和 g)

• numItermax (int, 可选。默认值为2000。) – Dykstra算法的最大迭代次数

• stopThr (float, 可选。默认值为 1e-7。) – Dykstra中的错误停止阈值 (>0)

• warn (bool, 可选) – 如果为True，当算法不收敛时会发出警告。

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• Q (类数组，形状 (n_samples_a, r)) – OT计划的第一低秩矩阵分解

• R (类数组，形状 (n_samples_b, r)) – OT计划的第二低秩矩阵分解

• g (类数组，形状 (r, )) – OT的低秩分解的权重向量

• log (字典 (lazy_plan, value 和 value_linear)) – 仅当参数中的log==True时返回log字典

参考文献

[65]

Scetbon, M., Cuturi, M., & Peyré, G. (2021). “低秩Sinkhorn分解”。在国际机器学习会议。

ot.max_sliced_wasserstein_distance(X_s, X_t, a=None, b=None, n_projections=50, p=2, projections=None, seed=None, log=False)

计算最大p切片Wasserstein距离的蒙特卡洛近似

\[\mathcal{Max-SWD}_p(\mu, \nu) = \underset{\theta _in \mathcal{U}(\mathbb{S}^{d-1})}{\max} [\mathcal{W}_p^p(\theta_\# \mu, \theta_\# \nu)]^{\frac{1}{p}}\]

其中 :

• \(\theta_\# \mu\) 代表投影的推送 \(\mathbb{R}^d \ni X \mapsto \langle \theta, X \rangle\)

Parameters:

• X_s (ndarray, shape (n_samples_a, dim)) – 源领域中的样本

• X_t (ndarray, shape (n_samples_b, dim)) – 目标域中的样本

• a (ndarray, shape (n_samples_a,), optional) – 源域中的样本权重

• b (ndarray, shape (n_samples_b,), optional) – 目标域中的样本权重

• n_projections (int, 可选) – 用于蒙特卡洛近似的投影数量

• p (float, optional =) – 用于计算切片Wasserstein的幂p

• 投影 (形状 (维度, 投影数), 可选) – 投影矩阵（在这种情况下不使用投影数和种子）

• seed (int 或 RandomState 或 None, 可选) – 用于随机数生成器的种子

• log (bool, 可选) – 如果为 True，sliced_wasserstein_distance 会返回使用的投影及其相关的 EMD。

Returns:

• cost (float) – 切片的Wasserstein成本

• log (dict, optional) – 仅在参数log==True时返回日志字典

示例

>>> n_samples_a = 20
>>> X = np.random.normal(0., 1., (n_samples_a, 5))
>>> sliced_wasserstein_distance(X, X, seed=0)  
0.0

参考文献

[35]

Deshpande, I., Hu, Y. T., Sun, R., Pyrros, A., Siddiqui, N., Koyejo, S., … & Schwing, A. G. (2019). 最大切片沃瑟斯坦距离及其在GAN中的应用。发表于IEEE/CVF计算机视觉与模式识别会议论文集（第10648-10656页）。

ot.semidiscrete_wasserstein2_unif_circle(u_values, u_weights=None)

计算样本与均匀分布之间的闭式形式的2-Wasserstein距离，位于 \(S^1\) 样本需要在 \(S^1\cong [0,1[\)。如果它们在 \(\mathbb{R}\) 中， 则取模1的值。 如果值位于 \(S^1\subset\mathbb{R}^2\)，则需要首先使用例如 atan2 函数找到坐标。

\[W_2^2(\mu_n, \nu) = \sum_{i=1}^n \alpha_i x_i^2 - \left(\sum_{i=1}^n \alpha_i x_i\right)^2 + \sum_{i=1}^n \alpha_i x_i \left(1-\alpha_i-2\sum_{k=1}^{i-1}\alpha_k\right) + \frac{1}{12}\]

其中：

• \(\nu=\mathrm{Unif}(S^1)\) 和 \(\mu_n = \sum_{i=1}^n \alpha_i \delta_{x_i}\)

对于值 \(x=(x_1,x_2)\in S^1\)，需要首先获取它们的坐标，方法是

\[u = \frac{\pi + \mathrm{atan2}(-x_2,-x_1)}{2\pi},\]

使用例如 ot.utils.get_coordinate_circle(x)

Parameters:

• u_values (ndarray, shape (n, ...)) – 样本

• u_weights (ndarray, shape (n, ...), optional) – 源领域中的样本权重

Returns:

loss – 与最佳运输相关的成本

Return type:

float

示例

>>> x0 = np.array([[0], [0.2], [0.4]])
>>> semidiscrete_wasserstein2_unif_circle(x0)
array([0.02111111])

参考文献

[46]

Bonet, C., Berg, P., Courty, N., Septier, F., Drumetz, L., & Pham, M. T. (2023). 球面切片-沃瑟斯坦。国际学习表征会议。

ot.sinkhorn(a, b, M, reg, method='sinkhorn', numItermax=1000, stopThr=1e-09, verbose=False, log=False, warn=True, warmstart=None, **kwargs)

求解熵正则化最优运输问题并返回OT矩阵

该函数解决以下优化问题：

\[ \begin{align}\begin{aligned}\gamma = \mathop{\arg \min}_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F + \mathrm{reg}\cdot\Omega(\gamma)\\\text{s.t.} \ \gamma \mathbf{1} &= \mathbf{a}\\ \gamma^T \mathbf{1} &= \mathbf{b}\\ \gamma &\geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是 (dim_a, dim_b) 费用矩阵

• \(\Omega\) 是熵正则化项 \(\Omega(\gamma)=\sum_{i,j} \gamma_{i,j}\log(\gamma_{i,j})\)

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源权重和目标权重 （直方图，两个都加起来为1）

注意

此函数与后端兼容，并且适用于所有兼容后端的数组。

用于解决问题的算法是Sinkhorn-Knopp矩阵缩放算法，如[2]中所提议的

选择一个Sinkhorn求解器

默认情况下，当使用的正则化参数不太小的时候，默认的 sinkhorn 求解器应该已经足够。如果你需要使用较小的正则化来获得更清晰的 OT 矩阵，你应该使用 ot.bregman.sinkhorn_stabilized() 求解器，以避免数值错误。最后这个求解器在实践中可能非常慢，甚至可能在有限时间内无法收敛到一个合理的 OT 矩阵。这就是为什么 ot.bregman.sinkhorn_epsilon_scaling() 依赖于迭代正则化值（并使用热启动）有时会导致更好的解决方案。请注意，贪婪版本的 sinkhorn ot.bregman.greenkhorn() 也可以带来加速，而 sinkhorn 的筛选版本 ot.bregman.screenkhorn() 旨在提供 Sinkhorn 问题的快速近似。对于 GPU 的使用和小迭代次数的梯度计算，我们强烈推荐 ot.bregman.sinkhorn_log() 求解器，因为它不需要检查数值问题。

Parameters:

• a (类似数组, 形状 (dim_a,)) – 源域中的样本权重

• b (类数组, 形状 (dim_b,) 或 ndarray, 形状 (dim_b, n_hists)) – 目标域中的样本，如果\(\mathbf{b}\)是一个矩阵，则计算带有多个目标和固定\(\mathbf{M}\)的Sinkhorn（返回OT损失 + 对数中的双变量）

• M (类似数组, 形状 (dim_a, dim_b)) – 损失矩阵

• reg (float) – 正则化项 >0

• 方法 (str) – 求解器使用的方法，可能是‘sinkhorn’，‘sinkhorn_log’，‘greenkhorn’，‘sinkhorn_stabilized’ 或 ‘sinkhorn_epsilon_scaling’，具体参数请参见这些函数

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

• warn (bool, 可选) – 如果为True，当算法不收敛时会发出警告。

• warmstart (元组 的 数组, 形状 (dim_a, dim_b), 可选) – 对偶潜力的初始化。如果提供，应该给出对偶潜力 （即 u,v Sinkhorn 缩放向量的对数）

Returns:

• gamma (array-like, shape (dim_a, dim_b)) – 给定参数的最佳交通矩阵

• log (dict) – 仅在参数中 log==True 时返回日志字典

示例

>>> import ot
>>> a=[.5, .5]
>>> b=[.5, .5]
>>> M=[[0., 1.], [1., 0.]]
>>> ot.sinkhorn(a, b, M, 1)
array([[0.36552929, 0.13447071],
       [0.13447071, 0.36552929]])

参考文献

[2]

M. Cuturi, Sinkhorn 距离：快速计算最优传输，神经信息处理系统进展（NIPS）26, 2013

[9]

Schmitzer, B. (2016). 稳定的稀疏缩放算法 用于熵正则化运输问题。arXiv 预印本 arXiv:1610.06519。

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 缩放算法用于不平衡交通问题。 arXiv 预印本 arXiv:1607.05816.

[34]

Feydy, J., Séjourné, T., Vialard, F. X., Amari, S. I., Trouvé, A., & Peyré, G. (2019年4月). 使用Sinkhorn散度在最优传输和MMD之间进行插值。在第22届国际人工智能与统计会议(pp. 2681-2690). PMLR.

另请参见

ot.lp.emd

未正则化的OT

ot.optim.cg

通用正则化OT

ot.bregman.sinkhorn_knopp

经典Sinkhorn [2]

ot.bregman.sinkhorn_stabilized

稳定的Sinkhorn [9] [10]

ot.bregman.sinkhorn_epsilon_scaling

Sinkhorn与epsilon缩放 [9] [10]

ot.sinkhorn2(a, b, M, reg, method='sinkhorn', numItermax=1000, stopThr=1e-09, verbose=False, log=False, warn=False, warmstart=None, **kwargs)

解决熵正则化最优传输问题并返回损失

该函数解决以下优化问题：

\[ \begin{align}\begin{aligned}W = \min_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F + \mathrm{reg}\cdot\Omega(\gamma)\\s.t. \ \gamma \mathbf{1} &= \mathbf{a}\\ \gamma^T \mathbf{1} &= \mathbf{b}\\ \gamma &\geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是 (dim_a, dim_b) 费用矩阵

• \(\Omega\) 是熵正则化项 \(\Omega(\gamma)=\sum_{i,j} \gamma_{i,j}\log(\gamma_{i,j})\)

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源权重和目标权重 （直方图，两个都加起来为1）

并返回 \(\langle \gamma^*, \mathbf{M} \rangle_F\) （不包括熵贡献）。

注意

此函数与后端兼容，并且适用于所有兼容后端的数组。

用于解决问题的算法是Sinkhorn-Knopp矩阵缩放算法，如[2]中所提议的

选择一个Sinkhorn求解器

默认情况下，当使用的正则化参数不是太小的时候，默认的 sinkhorn 求解器应该是足够的。如果您需要使用较小的正则化来获得更清晰的 OT 矩阵，您应该使用 ot.bregman.sinkhorn_log() 求解器，这将避免数值错误。最后这个求解器在实践中可能非常慢，甚至可能根本无法在有限的时间内收敛到合理的 OT 矩阵。这就是为什么 ot.bregman.sinkhorn_epsilon_scaling() 依靠迭代正则化的值（并使用热启动）有时会导致更好的解决方案。请注意，贪婪版本的 sinkhorn ot.bregman.greenkhorn() 也可以带来加速，而 sinkhorn 的筛选版本 ot.bregman.screenkhorn() 旨在提供 Sinkhorn 问题的快速近似。对于使用 GPU 和小迭代次数的梯度计算，我们强烈推荐 ot.bregman.sinkhorn_log() 求解器，它无需检查数值问题。

Parameters:

• a (类似数组, 形状 (dim_a,)) – 源域中的样本权重

• b (类数组, 形状 (dim_b,) 或 ndarray, 形状 (dim_b, n_hists)) – 目标域中的样本，如果\(\mathbf{b}\)是一个矩阵，则计算带有多个目标和固定\(\mathbf{M}\)的Sinkhorn（返回OT损失 + 对数中的双变量）

• M (类似数组, 形状 (dim_a, dim_b)) – 损失矩阵

• reg (float) – 正则化项 >0

• 方法 (str) – 求解器使用的方法，可以是‘sinkhorn’，’sinkhorn_log’，‘sinkhorn_stabilized’，有关具体参数，请参见这些函数

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

• warn (bool, 可选) – 如果为True，当算法不收敛时会发出警告。

• warmstart (元组 的 数组, 形状 (dim_a, dim_b), 可选) – 对偶潜力的初始化。如果提供，应该给出对偶潜力 （即 u,v Sinkhorn 缩放向量的对数）

Returns:

• W ((n_hists) 浮点数/数组类型) – 给定参数的最优运输损失

• log (字典) – 仅在参数中log==True时返回日志字典

示例

>>> import ot
>>> a=[.5, .5]
>>> b=[.5, .5]
>>> M=[[0., 1.], [1., 0.]]
>>> ot.sinkhorn2(a, b, M, 1)
0.26894142136999516

参考文献

[2]

M. Cuturi, Sinkhorn 距离：优化运输的快速计算，神经信息处理系统进展 (NIPS) 26, 2013

[9]

Schmitzer, B. (2016). 稳定稀疏缩放算法用于熵正则化运输问题。 arXiv预印本 arXiv:1610.06519。

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 缩放算法用于不平衡交通问题。 arXiv 预印本 arXiv:1607.05816.

[21]

Altschuler J., Weed J., Rigollet P. : 通过Sinkhorn迭代的最优传输近线性时间近似算法，神经信息处理系统进展 (NIPS) 31, 2017

[34]

Feydy, J., Séjourné, T., Vialard, F. X., Amari, S. I., Trouvé, A., & Peyré, G. (2019年4月). 通过Sinkhorn散度在最优运输和MMD之间进行插值。在第22届国际人工智能与统计会议（第2681-2690页）。PMLR。

另请参见

ot.lp.emd

未正则化的OT

ot.optim.cg

通用正则化OT

ot.bregman.sinkhorn_knopp

经典Sinkhorn [2]

ot.bregman.greenkhorn

Greenkhorn [21]

ot.bregman.sinkhorn_stabilized

稳定的Sinkhorn [9] [10]

ot.sinkhorn_lpl1_mm(a, labels_a, b, M, reg, eta=0.1, numItermax=10, numInnerItermax=200, stopInnerThr=1e-09, verbose=False, log=False)

解决具有非凸组lasso正则化的熵正则化最优传输问题

该函数解决以下优化问题：

\[ \begin{align}\begin{aligned}\gamma = \mathop{\arg \min}_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F + \mathrm{reg} \cdot \Omega_e(\gamma) + \eta \ \Omega_g(\gamma)\\s.t. \ \gamma \mathbf{1} = \mathbf{a}\\ \gamma^T \mathbf{1} = \mathbf{b}\\ \gamma \geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是 (ns, nt) 计量成本矩阵

• \(\Omega_e\) 是熵正则化项 \(\Omega_e (\gamma)=\sum_{i,j} \gamma_{i,j}\log(\gamma_{i,j})\)

• \(\Omega_g\) 是组lasso正则化项 \(\Omega_g(\gamma)=\sum_{i,c} \|\gamma_{i,\mathcal{I}_c}\|^{1/2}_1\) 其中 \(\mathcal{I}_c\) 是源域中来自类 c 的样本索引。

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源权重和目标权重（总和为1）

用于解决问题的算法是广义条件梯度，如[5, 7]中提出的。

Parameters:

• a (类数组 (ns,)) – 源域中的样本权重

• labels_a (类似数组 (ns,)) – 源域中样本的标签

• b (类数组 (nt,)) – 目标领域中的样本权重

• M (数组-like (ns,nt)) – 损失矩阵

• reg (float) – 熵正则化的正则化项 >0

• eta (float, 可选) – 组套索正则化的正则化项 >0

• numItermax (int, 可选) – 最大迭代次数

• numInnerItermax (int, 可选) – 最大迭代次数（内部Sinkhorn求解器）

• stopInnerThr (float, 可选) – 错误的停止阈值（内部Sinkhorn求解器） (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• gamma ((ns, nt) 类数组) – 给定参数的最优运输矩阵

• log (字典) – 仅当参数中的 log==True 时返回日志字典

参考文献

[5]

N. Courty; R. Flamary; D. Tuia; A. Rakotomamonjy, “用于领域适应的最优传输，”发表于IEEE 模式分析与机器智能学报， 第PP卷，第99期，页码1-1

[7]

Rakotomamonjy, A., Flamary, R., & Courty, N. (2015). 广义条件梯度：收敛分析及应用。arXiv 预印本 arXiv:1510.06567。

另请参见

ot.lp.emd

未正则化的OT

ot.bregman.sinkhorn

熵正则化最优传输

ot.optim.cg

通用正则化OT

ot.sinkhorn_unbalanced(a, b, M, reg, reg_m, method='sinkhorn', reg_type='kl', c=None, warmstart=None, numItermax=1000, stopThr=1e-06, verbose=False, log=False, **kwargs)

求解不平衡的熵正则化最优传输问题并返回OT计划

该函数解决以下优化问题：

\[ \begin{align}\begin{aligned}W = \arg \min_\gamma \ \langle \gamma, \mathbf{M} \rangle_F + \mathrm{reg} \cdot \mathrm{KL}(\gamma, \mathbf{c}) + \mathrm{reg_{m1}} \cdot \mathrm{KL}(\gamma \mathbf{1}, \mathbf{a}) + \mathrm{reg_{m2}} \cdot \mathrm{KL}(\gamma^T \mathbf{1}, \mathbf{b})\\s.t. \gamma \geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是 (dim_a, dim_b) 费用矩阵

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源和目标不平衡分布

• \(\mathbf{c}\) 是正则化的参考分布

• KL是Kullback-Leibler散度

用于解决该问题的算法是广义Sinkhorn-Knopp矩阵缩放算法，如[10, 25]中所提到的。

警告

从版本0.9.5开始，默认值已更改为 reg_type=’kl’ 而不是 reg_type=’entropy’。这使得该函数与文献和其他求解器更加一致。如果您想使用熵正则化，请明确设置 reg_type=’entropy’。

Parameters:

• a (类数组, 形状 (dim_a,)) – 未归一化的维度 dim_a 的直方图 如果 a 是空列表或数组 ([])， 那么 a 被设置为均匀分布。

• b (类数组, 形状 (dim_b,)) – 一个或多个未归一化的维度 dim_b 的直方图。 如果 b 是一个空列表或数组 ([])， 则 b 被设置为均匀分布。 如果有多个，则计算所有 OT 成本 \((\mathbf{a}, \mathbf{b}_i)_i\)

• M (类似数组, 形状 (dim_a, dim_b)) – 损失矩阵

• reg (float) – 熵正则化项 > 0

• reg_m (浮点数 或 可索引对象，长度为 1 或 2) – 边际放松项。 如果 \(\mathrm{reg_{m}}\) 是一个标量或长度为 1 的可索引对象， 则相同的 \(\mathrm{reg_{m}}\) 应用于两个边际放松。 可以使用 \(\mathrm{reg_{m}}=float("inf")\) 来恢复熵平衡的 OT。 对于半放松情况，可以使用以下任一方法： \(\mathrm{reg_{m}}=(float("inf"), 标量)\) 或 \(\mathrm{reg_{m}}=(标量, float("inf"))\)。 如果 \(\mathrm{reg_{m}}\) 是一个数组， 它必须与输入数组 (a, b, M) 具有相同的后端。

• 方法 (str) – 求解器使用的方法，可为‘sinkhorn’，‘sinkhorn_stabilized’，‘sinkhorn_translation_invariant’或‘sinkhorn_reg_scaling’，具体参数请参见这些函数

• reg_type (string, optional) –

  正则化项。可以取两个值：

  • 负熵: ‘entropy’: \(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\). 这等价于（上差一个常数）\(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\)。

  • Kullback-Leibler散度（默认）：‘kl’: \(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\)。

• c (类数组, 形状 (dim_a, dim_b), 可选 (默认=None)) – 正则化的参考度量。 如果为 None，则使用 \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\)。 如果 \(\texttt{reg_type}=\)’entropy’，则 \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\)。

• warmstart (tuple 的 数组, 形状 (dim_a, dim_b), 可选) – 双重潜在值的初始化。如果提供，应该给出双重潜在值 （即 u, v Sinkhorn 缩放向量的对数）。

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果 True 记录 log

Returns:

• if n_hists == 1 –

  • gammaarray-like, shape(dim_a, dim_b)

    给定参数的最佳运输矩阵

  • logdict

    仅当 log 为 True 时返回日志字典

• else –

  • ot_distancearray-like, shape (n_hists,)

    \(\mathbf{a}\) 与每个直方图 \(\mathbf{b}_i\) 之间的OT距离

  • logdict

    仅当 log 为 True 时返回日志字典

示例

>>> import ot
>>> import numpy as np
>>> a=[.5, .5]
>>> b=[.5, .5]
>>> M=[[0., 1.], [1., 0.]]
>>> np.round(ot.sinkhorn_unbalanced(a, b, M, 1, 1), 7)
array([[0.3220536, 0.1184769],
       [0.1184769, 0.3220536]])

参考文献

[2]

M. Cuturi, Sinkhorn 距离：快速计算最优运输，神经信息处理系统进展 (NIPS) 26, 2013

[9]

Schmitzer, B. (2016). 稳定稀疏缩放算法用于熵正则化运输问题。arXiv 预印本 arXiv:1610.06519.

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 用于不平衡运输问题的扩展算法。arXiv预印本 arXiv:1607.05816。

[25]

Frogner C., Zhang C., Mobahi H., Araya-Polo M., Poggio T. : 使用Wasserstein损失进行学习，神经信息处理系统进展 (NIPS) 2015

[73]

Séjourné, T., Vialard, F. X., & Peyré, G. (2022). 更快的非平衡最优运输：平移不变的Sinkhorn和1维Frank-Wolfe。 在国际人工智能与统计会议上 (pp. 4995-5021). PMLR.

另请参见

ot.unbalanced.sinkhorn_knopp_unbalanced

非平衡经典Sinkhorn [10]

ot.unbalanced.sinkhorn_stabilized_unbalanced

不平衡稳定化Sinkhorn [9, 10]

ot.unbalanced.sinkhorn_reg_scaling_unbalanced

带有 epsilon 缩放的非平衡 Sinkhorn [9, 10]

ot.unbalanced.sinkhorn_unbalanced_translation_invariant

翻译不变的非平衡Sinkhorn [73]

ot.sinkhorn_unbalanced2(a, b, M, reg, reg_m, method='sinkhorn', reg_type='kl', c=None, warmstart=None, returnCost='linear', numItermax=1000, stopThr=1e-06, verbose=False, log=False, **kwargs)

解决熵正则化不平衡最优运输问题并返回成本

该函数解决以下优化问题：

\[ \begin{align}\begin{aligned}\min_\gamma \quad \langle \gamma, \mathbf{M} \rangle_F + \mathrm{reg} \cdot \mathrm{KL}(\gamma, \mathbf{c}) + \mathrm{reg_{m1}} \cdot \mathrm{KL}(\gamma \mathbf{1}, \mathbf{a}) + \mathrm{reg_{m2}} \cdot \mathrm{KL}(\gamma^T \mathbf{1}, \mathbf{b})\\s.t. \gamma\geq 0\end{aligned}\end{align} \]

其中 :

• \(\mathbf{M}\) 是 (dim_a, dim_b) 费用矩阵

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是源和目标不平衡分布

• \(\mathbf{c}\) 是正则化的参考分布

• KL是Kullback-Leibler散度

用于解决该问题的算法是广义Sinkhorn-Knopp矩阵缩放算法，如[10, 25]中所提到的。

警告

从版本0.9.5开始，默认值已更改为 reg_type=’kl’ 而不是 reg_type=’entropy’。这使得该函数与文献和其他求解器更加一致。如果您想使用熵正则化，请明确设置 reg_type=’entropy’。

Parameters:

• a (类数组, 形状 (dim_a,)) – 未归一化的维度 dim_a 的直方图 如果 a 是空列表或数组 ([])，那么 a 被设置为均匀分布。

• b (类似数组, 形状 (dim_b,)) – 一个或多个未归一化的维度 dim_b 的直方图。 如果 b 是一个空列表或数组 ([])， 那么 b 被设定为均匀分布。 如果有多个，计算所有的 OT 成本 \((\mathbf{a}, \mathbf{b}_i)_i\)

• M (类似数组, 形状 (dim_a, dim_b)) – 损失矩阵

• reg (float) – 熵正则化项 > 0

• reg_m (浮点数 或 可索引对象，长度为 1 或 2) – 边际放松项。 如果 \(\mathrm{reg_{m}}\) 是一个标量或长度为 1 的可索引对象， 则相同的 \(\mathrm{reg_{m}}\) 应用于两个边际放松。 可以使用 \(\mathrm{reg_{m}}=float("inf")\) 来恢复熵平衡的 OT。 对于半放松情况，可以使用以下任一方法： \(\mathrm{reg_{m}}=(float("inf"), 标量)\) 或 \(\mathrm{reg_{m}}=(标量, float("inf"))\)。 如果 \(\mathrm{reg_{m}}\) 是一个数组， 它必须与输入数组 (a, b, M) 具有相同的后端。

• 方法 (str) – 求解器使用的方法，可为‘sinkhorn’，‘sinkhorn_stabilized’，‘sinkhorn_translation_invariant’或‘sinkhorn_reg_scaling’，具体参数请参见这些函数

• reg_type (string, optional) –

  正则化项。可以取两种值：

  • 负熵：‘entropy’： \(\Omega(\gamma) = \sum_{i,j} \gamma_{i,j} \log(\gamma_{i,j}) - \sum_{i,j} \gamma_{i,j}\)。 这等价于（至一个常数）\(\Omega(\gamma) = \text{KL}(\gamma, 1_{dim_a} 1_{dim_b}^T)\)。

  • Kullback-Leibler散度：‘kl’： \(\Omega(\gamma) = \text{KL}(\gamma, \mathbf{a} \mathbf{b}^T)\)。

• c (类似数组, 形状 (dim_a, dim_b), 可选 (默认=None)) – 用于正则化的参考度量。 如果为 None，则使用 \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\)。 如果 \(\texttt{reg_type}=\)’entropy’，则 \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\)。

• warmstart (元组 of 数组, 形状 (dim_a, dim_b), 可选) – 对偶势的初始化。如果提供，应该给出对偶势 （即u,v sinkhorn缩放向量的对数）。

• returnCost (string, optional (default = "linear")) – 如果 returnCost = “linear”，则返回不平衡OT损失的线性部分。 如果 returnCost = “total”，则返回总的不平衡OT损失。

• numItermax (int, 可选) – 最大迭代次数

• stopThr (float, 可选) – 错误的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果 True 记录 log

Returns:

• ot_cost (数组类型，形状 (n_hists,)) – \(\mathbf{a}\) 与每个 histogram \(\mathbf{b}_i\) 之间的 OT 成本

• log (字典) – 只有当 log 为 True 时才返回的日志字典

示例

>>> import ot
>>> import numpy as np
>>> a=[.5, .10]
>>> b=[.5, .5]
>>> M=[[0., 1.],[1., 0.]]
>>> np.round(ot.unbalanced.sinkhorn_unbalanced2(a, b, M, 1., 1.), 8)
0.19600125

参考文献

[2]

M. Cuturi, Sinkhorn 距离：快速计算最优运输，神经信息处理系统进展 (NIPS) 26, 2013

[9]

Schmitzer, B. (2016). 稳定稀疏缩放算法用于熵正则化运输问题。arXiv 预印本 arXiv:1610.06519.

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 用于不平衡运输问题的扩展算法。arXiv预印本 arXiv:1607.05816。

[25]

Frogner C., Zhang C., Mobahi H., Araya-Polo M., Poggio T. : 使用Wasserstein损失进行学习，神经信息处理系统进展 (NIPS) 2015

[73]

Séjourné, T., Vialard, F. X., & Peyré, G. (2022). 更快的非平衡最优运输：平移不变的Sinkhorn和1维Frank-Wolfe。 在国际人工智能与统计会议上 (pp. 4995-5021). PMLR.

另请参见

ot.unbalanced.sinkhorn_knopp

非平衡经典Sinkhorn [10]

ot.unbalanced.sinkhorn_stabilized

不平衡稳定化Sinkhorn [9, 10]

ot.unbalanced.sinkhorn_reg_scaling

带有 epsilon 缩放的非平衡 Sinkhorn [9, 10]

ot.unbalanced.sinkhorn_unbalanced_translation_invariant

翻译不变的非平衡Sinkhorn [73]

ot.sliced_wasserstein_distance(X_s, X_t, a=None, b=None, n_projections=50, p=2, projections=None, seed=None, log=False)

计算p切片Wasserstein距离的蒙特卡罗近似值

\[\mathcal{SWD}_p(\mu, \nu) = \underset{\theta \sim \mathcal{U}(\mathbb{S}^{d-1})}{\mathbb{E}}\left(\mathcal{W}_p^p(\theta_\# \mu, \theta_\# \nu)\right)^{\frac{1}{p}}\]

其中 :

• \(\theta_\# \mu\) 表示投影 \(X \in \mathbb{R}^d \mapsto \langle \theta, X \rangle\) 的推前。

Parameters:

• X_s (ndarray, shape (n_samples_a, dim)) – 源领域中的样本

• X_t (ndarray, shape (n_samples_b, dim)) – 目标域中的样本

• a (ndarray, shape (n_samples_a,), optional) – 源域中的样本权重

• b (ndarray, shape (n_samples_b,), optional) – 目标域中的样本权重

• n_projections (int, 可选) – 用于蒙特卡洛近似的投影数量

• p (float, optional =) – 用于计算切片Wasserstein的幂p

• 投影 (形状 (维度, 投影数), 可选) – 投影矩阵（在这种情况下不使用投影数和种子）

• seed (int 或 RandomState 或 None, 可选) – 用于随机数生成器的种子

• log (bool, 可选) – 如果为 True，sliced_wasserstein_distance 会返回使用的投影及其相关的 EMD。

Returns:

• cost (float) – 切片的Wasserstein成本

• log (dict, optional) – 仅在参数log==True时返回日志字典

示例

>>> n_samples_a = 20
>>> X = np.random.normal(0., 1., (n_samples_a, 5))
>>> sliced_wasserstein_distance(X, X, seed=0)  
0.0

参考文献

[31]

Bonneel, Nicolas, 等. “切片和拉东华斯坦质心。” 数学成像与视觉杂志 51.1 (2015): 22-45

ot.sliced_wasserstein_sphere(X_s, X_t, a=None, b=None, n_projections=50, p=2, projections=None, seed=None, log=False)

计算球面切片-Wasserstein 差异。

\[SSW_p(\mu,\nu) = \left(\int_{\mathbb{V}_{d,2}} W_p^p(P^U_\#\mu, P^U_\#\nu)\ \mathrm{d}\sigma(U)\right)^{\frac{1}{p}}\]

其中：

• \(P^U_\# \mu\) 表示投影的推前 \(\forall x\in S^{d-1},\ P^U(x) = \frac{U^Tx}{\|U^Tx\|_2}\)

该函数在后台运行，但不支持tensorflow和jax。

Parameters:

• X_s (ndarray, shape (n_samples_a, dim)) – 源领域中的样本

• X_t (ndarray, shape (n_samples_b, dim)) – 目标领域中的样本

• a (ndarray, shape (n_samples_a,), optional) – 源域中的样本权重

• b (ndarray, shape (n_samples_b,), optional) – 目标域中的样本权重

• n_projections (int, 可选) – 用于蒙特卡洛近似的投影数量

• p (float, 可选的 (默认=2)) – 用于计算球面切片Wasserstein的功率p

• 投影 (形状 (投影数量, 维度, 2), 可选) – 投影矩阵（在这种情况下，不使用投影数量和种子）

• seed (int 或 RandomState 或 None, 可选) – 用于随机数生成器的种子

• log (bool, 可选) – 如果为 True，sliced_wasserstein_sphere 将返回使用的投影及其相关的 EMD。

Returns:

• cost (float) – 球面切片瓦瑟斯坦成本

• log (dict, optional) – 仅当parameters中的log==True时返回日志字典

示例

>>> n_samples_a = 20
>>> X = np.random.normal(0., 1., (n_samples_a, 5))
>>> X = X / np.sqrt(np.sum(X**2, -1, keepdims=True))
>>> sliced_wasserstein_sphere(X, X, seed=0)  
0.0

参考文献

[46]

Bonet, C., Berg, P., Courty, N., Septier, F., Drumetz, L., & Pham, M. T. (2023). 球面切片-沃瑟斯坦。国际学习表征会议。

ot.sliced_wasserstein_sphere_unif(X_s, a=None, n_projections=50, seed=None, log=False)

计算相对于均匀分布的2-球面切片瓦瑟斯坦距离。

\[SSW_2(\mu_n, \nu)\]

在哪里

• \(\mu_n=\sum_{i=1}^n \alpha_i \delta_{x_i}\)

• \(\nu=\mathrm{Unif}(S^1)\)

Parameters:

• X_s (ndarray, shape (n_samples_a, dim)) – 源领域中的样本

• a (ndarray, shape (n_samples_a,), optional) – 源域中的样本权重

• n_projections (int, 可选) – 用于蒙特卡洛近似的投影数量

• seed (int 或 RandomState 或 None, 可选) – 用于随机数生成器的种子

• log (bool, 可选) – 如果为 True，sliced_wasserstein_distance 会返回使用的投影及其相关的 EMD。

Returns:

• cost (float) – 球面切片瓦瑟斯坦成本

• log (dict, optional) – 仅当parameters中的log==True时返回日志字典

示例

>>> np.random.seed(42)
>>> x0 = np.random.randn(500,3)
>>> x0 = x0 / np.sqrt(np.sum(x0**2, -1, keepdims=True))
>>> ssw = sliced_wasserstein_sphere_unif(x0, seed=42)
>>> np.allclose(sliced_wasserstein_sphere_unif(x0, seed=42), 0.01734, atol=1e-3)
True

参考文献:

[46]

Bonet, C., Berg, P., Courty, N., Septier, F., Drumetz, L., & Pham, M. T. (2023). 球面切片-沃瑟斯坦。国际学习表征会议。

ot.solve(M, a=None, b=None, reg=None, c=None, reg_type='KL', unbalanced=None, unbalanced_type='KL', method=None, n_threads=1, max_iter=None, plan_init=None, potentials_init=None, tol=None, verbose=False, grad='autodiff')

解决离散最优运输问题并返回 OTResult 对象

该函数解决以下一般最优运输问题

\[\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_r R(\mathbf{T}) + \lambda_1 U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_2 U(\mathbf{T}^T\mathbf{1},\mathbf{b})\]

正则化使用 reg (\(\lambda_r\)) 和 reg_type 进行选择。默认情况下 reg=None，并且没有正则化。可以通过 unbalanced (\((\lambda_1, \lambda_2)\)) 和 unbalanced_type 选择不平衡的边际惩罚。默认情况下 unbalanced=None，并且该函数解决精确的最优运输问题（遵循边际）。

Parameters:

• M (类数组, 形状 (dim_a, dim_b)) – 损失矩阵

• a (类数组, 形状 (dim_a,), 可选) – 源域中的样本权重（默认是均匀分布）

• b (类数组, 形状 (dim_b,), 可选) – 源域中的样本权重（默认均匀分布）

• reg (float, 可选) – 正则化权重 \(\lambda_r\), 默认值为 None（无正则化，精确 OT）

• c (类数组, 形状 (dim_a, dim_b), 可选 (默认=None)) – 正则化的参考度量。 如果为 None，则使用 \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\)。 如果 \(\texttt{reg_type}=\)’entropy’，则 \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\)。

• reg_type (str, 可选) – 正则化的类型 \(R\) 可以是 “KL”, “L2”, “entropy”，默认是 “KL”。可以为通用求解器提供一个函数的元组（参见 cg）。这仅在 reg!=None 时使用。

• unbalanced (浮点数 或 可索引对象，长度为 1 或 2) – 边际松弛项。 如果它是一个标量或长度为 1 的可索引对象， 则对两个边际松弛应用相同的松弛。 可以使用 \(unbalanced=float("inf")\) 恢复平衡的 OT。 对于半松弛情况，可以使用 \(unbalanced=(float("inf"), scalar)\) 或 \(unbalanced=(scalar, float("inf"))\)。 如果 unbalanced 是一个数组， 它必须具有与输入数组 (a, b, M) 相同的后端。

• unbalanced_type (str, 可选) – 不平衡惩罚函数的类型 \(U\) 可以是 “KL”, “L2”, “TV”, 默认为 “KL”。

• 方法 (字符串, 可选) – 当有多种算法可用时解决问题的方法，默认值为None，表示自动选择。

• n_threads (int, 可选) – 用于精确OT求解器的OMP线程数，默认为1

• max_iter (int, 可选) – 最大迭代次数，默认为 None（每个解算器中的默认值）

• plan_init (类数组, 形状 (dim_a, dim_b), 可选) – 用于迭代方法的OT计划初始化，默认值为None

• potentials_init ((array-like(dim_a,),array-like(dim_b,)), optional) – 迭代方法的OT对偶势的初始化，默认为None

• tol (_type_, optional) – 解决方案精度的容差，默认值为 None（每个求解器中的默认值）

• verbose (bool, 可选) – 在求解器中打印信息，默认值为 False

• grad (str, 可选) – 梯度计算类型，使用‘autodiff’，‘envelope’或‘last_step’，仅适用于 Sinkhorn 解算器。默认情况下，‘autodiff’ 提供相对于所有 输出的梯度 (plan, value, value_linear)，但具有重要的内存开销。 ‘envelope’ 仅为 value 提供梯度，其他输出被 分离。当只需要值时，这对节省内存非常有用。‘last_step’ 仅提供 Sinkhorn 解算器最后一次迭代的梯度，但同时提供 OT 计划和目标值的梯度。 ‘detach’ 不计算 Sinkhorn 解算器的梯度。

Returns:

res – 优化问题的结果。信息可以通过以下方式获得：

• res.plan : OT 计划 \(\mathbf{T}\)

• res.potentials : OT 对偶势

• res.value : 优化问题的最优值

• res.value_linear : 具有最优 OT 计划的线性 OT 损失

有关更多信息，请参见 OTResult。

Return type:

OTResult()

备注

以下方法可用于解决OT问题：

• 经典的精确OT问题 [1] (默认参数) :

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve(M, a, b)

• 熵正则化的OT [2] (当 reg!=None):

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F + \lambda R(\mathbf{T})\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

# default is ``"KL"`` regularization (``reg_type="KL"``)
res = ot.solve(M, a, b, reg=1.0)
# or for original Sinkhorn paper formulation [2]
res = ot.solve(M, a, b, reg=1.0, reg_type='entropy')

# Use envelope theorem differentiation for memory saving
res = ot.solve(M, a, b, reg=1.0, grad='envelope') # M, a, b are torch tensors
res.value.backward() # only the value is differentiable

请注意，默认情况下，Sinkhorn求解器使用自动微分来计算值和计划的梯度。这可以通过grad参数进行更改。envelope模式仅计算值的梯度，而其他输出则被分离。这在仅需要值的梯度时对于节省内存非常有用。

• 二次规整化OT [17]（当 reg!=None 和 reg_type="L2" 时）：

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F + \lambda R(\mathbf{T})\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve(M,a,b,reg=1.0,reg_type='L2')

• 不平衡OT [41] （当 unbalanced!=None）：

\[\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_1 U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_2 U(\mathbf{T}^T\mathbf{1},\mathbf{b})\]

可以用以下代码解决：

# default is ``"KL"``
res = ot.solve(M,a,b,unbalanced=1.0)
# quadratic unbalanced OT
res = ot.solve(M,a,b,unbalanced=1.0,unbalanced_type='L2')
# TV = partial OT
res = ot.solve(M,a,b,unbalanced=1.0,unbalanced_type='TV')

• 正则化不平衡正则化OT [34] （当 unbalanced!=None 和 reg!=None）：

\[\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_r R(\mathbf{T}) + \lambda_1 U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_2 U(\mathbf{T}^T\mathbf{1},\mathbf{b})\]

可以用以下代码解决：

# default is ``"KL"`` for both
res = ot.solve(M,a,b,reg=1.0,unbalanced=1.0)
# quadratic unbalanced OT with KL regularization
res = ot.solve(M,a,b,reg=1.0,unbalanced=1.0,unbalanced_type='L2')
# both quadratic
res = ot.solve(M,a,b,reg=1.0, reg_type='L2',unbalanced=1.0,unbalanced_type='L2')

参考文献

[1]

Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011年12月). 使用拉格朗日质量传输的位移插值. 在ACM图形学汇刊(TOG) (第30卷, 第6期, 第158页). ACM.

[2]

M. Cuturi, Sinkhorn 距离：快速计算最优传输，神经信息处理系统进展（NIPS）26, 2013

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 缩放算法用于不平衡交通问题。 arXiv 预印本 arXiv:1607.05816.

[17]

Blondel, M., Seguy, V., & Rolet, A. (2018). 平滑与稀疏的最优传输。第二十一届国际人工智能与统计会议（AISTATS）论文集。

[34]

Feydy, J., Séjourné, T., Vialard, F. X., Amari, S. I., Trouvé, A., & Peyré, G. (2019年4月). 使用Sinkhorn散度在最优传输和MMD之间进行插值。在第22届国际人工智能与统计会议(pp. 2681-2690). PMLR.

[41]

Chapel, L., Flamary, R., Wu, H., Févotte, C., 和 Gasso, G. (2021). 通过非负惩罚线性回归进行不平衡最优传输。NeurIPS。

ot.solve_gromov(Ca, Cb, M=None, a=None, b=None, loss='L2', symmetric=None, alpha=0.5, reg=None, reg_type='entropy', unbalanced=None, unbalanced_type='KL', n_threads=1, method=None, max_iter=None, plan_init=None, tol=None, verbose=False)

解决离散（融合）Gromov-Wasserstein并返回 OTResult 对象

该函数解决以下优化问题：

\[\min_{\mathbf{T}\geq 0} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j} + \lambda_r R(\mathbf{T}) + \lambda_u U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_u U(\mathbf{T}^T\mathbf{1},\mathbf{b})\]

正则化是通过reg (\(\lambda_r\)) 和reg_type来选择的。默认情况下reg=None，并且没有正则化。可以通过unbalanced (\(\lambda_u\)) 和unbalanced_type选择不平衡边际惩罚。默认情况下unbalanced=None，该函数解决严格的最优运输问题（尊重边际）。

Parameters:

• Ca (数组类似, 形状 (dim_a, dim_a)) – 源域中的成本矩阵

• Cb (类似数组, 形状 (dim_b, dim_b)) – 目标域中的成本矩阵

• M (数组型, 形状 (dim_a, dim_b), 可选) – Fused Gromov-Wasserstein 的线性成本矩阵（默认值为 None）。

• a (类数组, 形状 (dim_a,), 可选) – 源域中的样本权重（默认是均匀分布）

• b (类数组, 形状 (dim_b,), 可选) – 源域中的样本权重（默认均匀分布）

• loss (str, 可选) – 损失函数的类型，可以是 "L2" 或 "KL"，默认为 "L2"

• 对称 (布尔值, 可选) – 使用对称版本的Gromov-Wasserstein问题，默认值为None 测试矩阵是否对称或True/False以避免测试。

• reg (float, 可选) – 正则化权重 \(\lambda_r\), 默认值为 None（无正则化，精确 OT）

• reg_type (str, 可选) – 正则化类型 \(R\)，默认为“entropy”（仅在 reg!=None 时使用）

• alpha (float, 可选) – 在融合Gromov-Wasserstein问题中，加权二次项（alpha*Gromov）和线性项（(1-alpha)*Wass）。在Gromov问题中不使用（当M未提供时）。默认情况下 alpha=None 对应于 alpha=1 用于Gromov问题（M==None）和 alpha=0.5 用于融合Gromov-Wasserstein问题（M!=None）

• 不平衡 (浮点数, 可选) – 不平衡惩罚权重 \(\lambda_u\), 默认值为 None (平衡 OT), 尚未实现

• unbalanced_type (str, 可选) – 不平衡惩罚函数的类型 \(U\) 可以是 “KL”, “semirelaxed”, “partial”，默认是 “KL”，但请注意目前尚未实现。

• n_threads (int, 可选) – 用于精确OT求解器的OMP线程数，默认为1

• 方法 (字符串, 可选) – 当有多种算法可用时解决问题的方法，默认值为None，表示自动选择。

• max_iter (int, 可选) – 最大迭代次数，默认为 None（每个求解器的默认值）

• plan_init (类数组, 形状 (dim_a, dim_b), 可选) – 用于迭代方法的OT计划初始化，默认值为None

• tol (float, 可选) – 解的精度容差，默认值为 None（每个求解器的默认值）

• verbose (bool, 可选) – 在求解器中打印信息，默认值为 False

Returns:

res – 优化问题的结果。信息可以通过以下方式获取：

• res.plan : OT 计划 \(\mathbf{T}\)

• res.potentials : OT 对偶潜力

• res.value : 优化问题的最优值

• res.value_linear : 使用最优 OT 计划的线性 OT 损失

• res.value_quad : 使用最优 OT 计划的二次 (GW) 部分的 OT 损失

详情请参见 OTResult。

Return type:

OTResult()

备注

以下方法可用于解决Gromov-Wasserstein问题：

• 经典的 Gromov-Wasserstein (GW) 问题 [3] (默认参数):

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j}\mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_gromov(Ca, Cb) # uniform weights
res = ot.solve_gromov(Ca, Cb, a=a, b=b) # given weights
res = ot.solve_gromov(Ca, Cb, loss='KL') # KL loss

plan = res.plan # GW plan
value = res.value # GW value

• 融合的Gromov-Wasserstein (FGW) 问题 [24] (当 M!=None):

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j}\mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_gromov(Ca, Cb, M) # uniform weights, alpha=0.5 (default)
res = ot.solve_gromov(Ca, Cb, M, a=a, b=b, alpha=0.1) # given weights and alpha

plan = res.plan # FGW plan
loss_linear_term = res.value_linear # Wasserstein part of the loss
loss_quad_term = res.value_quad # Gromov part of the loss
loss = res.value # FGW value

• 正则化（融合）Gromov-Wasserstein (GW) 问题 [12]（当 reg!=None）：

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j}\mathbf{T}_{k,l} + \lambda_r R(\mathbf{T})\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_gromov(Ca, Cb, reg=1.0) # GW entropy regularization (default)
res = ot.solve_gromov(Ca, Cb, M, a=a, b=b, reg=10, alpha=0.1) # FGW with entropy

plan = res.plan # FGW plan
loss_linear_term = res.value_linear # Wasserstein part of the loss
loss_quad_term = res.value_quad # Gromov part of the loss
loss = res.value # FGW value (including regularization)

• 半放松（融合）Gromov-Wasserstein (GW) [48] （当 unbalanced='semirelaxed'）：

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j}\mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T} \geq 0\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_gromov(Ca, Cb, unbalanced='semirelaxed') # semirelaxed GW
res = ot.solve_gromov(Ca, Cb, unbalanced='semirelaxed', reg=1) # entropic semirelaxed GW
res = ot.solve_gromov(Ca, Cb, M, unbalanced='semirelaxed', alpha=0.1) # semirelaxed FGW

plan = res.plan # FGW plan
right_marginal = res.marginal_b # right marginal of the plan

• 部分（融合）Gromov-Wasserstein（GW）问题 [29]（当 unbalanced='partial'）：

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad (1 - \alpha) \langle \mathbf{T}, \mathbf{M} \rangle_F + \alpha \sum_{i,j,k,l} L(\mathbf{C_1}_{i,k}, \mathbf{C_2}_{j,l}) \mathbf{T}_{i,j}\mathbf{T}_{k,l}\\s.t. \ \mathbf{T} \mathbf{1} \leq \mathbf{a}\\ \mathbf{T}^T \mathbf{1} \leq \mathbf{b}\\ \mathbf{T} \geq 0\\ \mathbf{1}^T\mathbf{T}\mathbf{1} = m\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_gromov(Ca, Cb, unbalanced_type='partial', unbalanced=0.8) # partial GW with m=0.8
res = ot.solve_gromov(Ca, Cb, M, unbalanced_type='partial', unbalanced=0.8, alpha=0.5) # partial FGW with m=0.8

参考文献

[3]

Mémoli, F. (2011). Gromov–Wasserstein 距离与物体匹配的度量方法。计算数学基础，11(4)，417-487。

[12]

加布里埃尔·佩雷、马尔科·库图里和贾斯廷·所罗门 (2016)， 核和距离矩阵的格罗莫夫-瓦瑟斯坦平均 国际机器学习会议 (ICML)。

[24]

Vayer, T., Chapel, L., Flamary, R., Tavenard, R. 和 Courty, N. (2019). 针对具有图形应用的结构化数据的最优运输 第36届国际机器学习会议论文集 (ICML).

[48]

Cédric Vincent-Cuaz, Rémi Flamary, Marco Corneli, Titouan Vayer, Nicolas Courty (2022). 半放松的Gromov-Wasserstein散度及其在图上的应用。国际表征学习会议（ICLR），2022。

[29]

Chapel, L., Alaya, M., Gasso, G. (2020). 部分最优传输及其在正无标学习中的应用, 神经信息处理系统进展 (NeurIPS), 2020.

ot.solve_sample(X_a, X_b, a=None, b=None, metric='sqeuclidean', reg=None, c=None, reg_type='KL', unbalanced=None, unbalanced_type='KL', lazy=False, batch_size=None, method=None, n_threads=1, max_iter=None, plan_init=None, rank=100, scaling=0.95, potentials_init=None, X_init=None, tol=None, verbose=False, grad='autodiff')

使用源域和目标域中的样本解决离散最优运输问题。

该函数解决以下一般最优运输问题

\[\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_r R(\mathbf{T}) + \lambda_u U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_u U(\mathbf{T}^T\mathbf{1},\mathbf{b})\]

其中成本矩阵 \(\mathbf{M}\) 是通过源域和目标域中的样本计算得出的，以便 \(M_{i,j} = d(x_i,y_j)\) 其中\(d\) 是度量（默认情况下是平方欧几里得距离）。

正则化是通过 reg (\(\lambda_r\)) 和 reg_type 选择的。默认情况下 reg=None，没有正则化。可以通过 unbalanced (\(\lambda_u\)) 和 unbalanced_type 选择不平衡边际惩罚。默认情况下 unbalanced=None，该函数解决了精确的最优传输问题（符合边际分布）。

Parameters:

• X_s (类数组, 形状 (n_samples_a, 维度)) – 源域中的样本

• X_t (类似数组, 形状 (n_samples_b, 维度)) – 目标域中的样本

• a (类数组, 形状 (dim_a,), 可选) – 源域中的样本权重（默认是均匀分布）

• b (类数组, 形状 (dim_b,), 可选) – 源域中的样本权重（默认均匀分布）

• reg (float, 可选) – 正则化权重 \(\lambda_r\), 默认值为 None（无正则化，精确 OT）

• c (类似数组, 形状 (dim_a, dim_b), 可选 (默认=None)) – 用于正则化的参考度量。 如果为 None，则使用 \(\mathbf{c} = \mathbf{a} \mathbf{b}^T\)。 如果 \(\texttt{reg_type}=\)’entropy’，则 \(\mathbf{c} = 1_{dim_a} 1_{dim_b}^T\)。

• reg_type (str, 可选) – 正则化类型 \(R\) 可以是 “KL”, “L2”, “entropy”, 默认是 “KL”

• unbalanced (浮点数 或 可索引对象，长度为 1 或 2) – 边际松弛项。 如果它是一个标量或长度为 1 的可索引对象， 则对两个边际松弛应用相同的松弛。 可以使用 \(unbalanced=float("inf")\) 恢复平衡的 OT。 对于半松弛情况，可以使用 \(unbalanced=(float("inf"), scalar)\) 或 \(unbalanced=(scalar, float("inf"))\)。 如果 unbalanced 是一个数组， 它必须具有与输入数组 (a, b, M) 相同的后端。

• unbalanced_type (str, 可选) – 不平衡惩罚函数类型 \(U\) ，可以是“KL”、“L2”、“TV”，默认是“KL”

• lazy (bool, 可选) – 返回 OTResultlazy 对象以减少内存消耗，当为 True 时，默认为 False

• batch_size (int, 可选) – 懒惰求解器的批处理大小，默认为 None （每个求解器的默认值）

• 方法 (str, 可选) – 解决问题的方法，这可以用来选择不平衡问题的求解器（见 ot.solve），或选择特定的大规模求解器。

• n_threads (int, 可选) – 用于精确OT求解器的OMP线程数，默认为1

• max_iter (int, 可选) – 最大迭代次数，默认为 None（每个求解器的默认值）

• plan_init (类数组, 形状 (dim_a, dim_b), 可选) – 用于迭代方法的OT计划初始化，默认值为None

• rank (int, 可选) – 懒惰求解器的 OT 矩阵的秩（method=’factored’），默认值为 100

• 缩放 (浮点数, 可选) – 用于epsilon缩放懒惰求解器的缩放因子（method=’geomloss’），默认值为0.95

• potentials_init ((array-like(dim_a,),array-like(dim_b,)), optional) – OT 对偶潜力的初始化，用于迭代方法，默认值为 None

• tol (_type_, optional) – 解决方案精度的容差，默认值为 None（每个求解器中的默认值）

• verbose (bool, 可选) – 在求解器中打印信息，默认值为 False

• grad (str, optional) – 梯度计算的类型，可以是‘autodiff’或‘envelope’，仅用于Sinkhorn求解器。默认情况下，‘autodiff’提供相对于所有输出的梯度（plan, value, value_linear），但会有重要的内存开销。‘envelope’仅提供value的梯度，其他输出会被分离。这对于只需要值时节省内存非常有用。

Returns:

res – 优化问题的结果。可以通过以下方式获取信息：

• res.plan : OT 计划 \(\mathbf{T}\)

• res.potentials : OT 对偶势

• res.value : 优化问题的最优值

• res.value_linear : 具有最优 OT 计划的线性 OT 损失

• res.lazy_plan : 懒惰 OT 计划 (当 lazy=True 或懒惰方法时)

请参见 OTResult 获取更多信息。

Return type:

OTResult()

备注

以下方法可用于解决OT问题：

• 经典的精确OT问题 [1] (默认参数) :

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0, M_{i,j} = d(x_i,y_j)\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_sample(xa, xb, a, b)

# for uniform weights
res = ot.solve_sample(xa, xb)

• 熵正则化的OT [2] (当 reg!=None):

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F + \lambda R(\mathbf{T})\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0, M_{i,j} = d(x_i,y_j)\end{aligned}\end{align} \]

可以用以下代码解决：

# default is ``"KL"`` regularization (``reg_type="KL"``)
res = ot.solve_sample(xa, xb, a, b, reg=1.0)
# or for original Sinkhorn paper formulation [2]
res = ot.solve_sample(xa, xb, a, b, reg=1.0, reg_type='entropy')

# lazy solver of memory complexity O(n)
res = ot.solve_sample(xa, xb, a, b, reg=1.0, lazy=True, batch_size=100)
# lazy OT plan
lazy_plan = res.lazy_plan

# Use envelope theorem differentiation for memory saving
res = ot.solve_sample(xa, xb, a, b, reg=1.0, grad='envelope')
res.value.backward() # only the value is differentiable

请注意，默认情况下，Sinkhorn求解器使用自动微分来计算值和计划的梯度。这可以通过grad参数进行更改。envelope模式仅计算值的梯度，而其他输出则被分离。这在仅需要值的梯度时对于节省内存非常有用。

我们还有一个非常高效的求解器，使用编译的CPU/CUDA代码，基于geomloss/PyKeOps，可以使用以下代码：

# automatic solver
res = ot.solve_sample(xa, xb, a, b, reg=1.0, method='geomloss')

# force O(n) memory efficient solver
res = ot.solve_sample(xa, xb, a, b, reg=1.0, method='geomloss_online')

# force pre-computed cost matrix
res = ot.solve_sample(xa, xb, a, b, reg=1.0, method='geomloss_tensorized')

# use multiscale solver
res = ot.solve_sample(xa, xb, a, b, reg=1.0, method='geomloss_multiscale')

# One can play with speed (small scaling factor) and precision (scaling close to 1)
res = ot.solve_sample(xa, xb, a, b, reg=1.0, method='geomloss', scaling=0.5)

• 二次规整化OT [17]（当 reg!=None 和 reg_type="L2" 时）：

\[ \begin{align}\begin{aligned}\min_\mathbf{T} \quad \langle \mathbf{T}, \mathbf{M} \rangle_F + \lambda R(\mathbf{T})\\s.t. \ \mathbf{T} \mathbf{1} = \mathbf{a}\\ \mathbf{T}^T \mathbf{1} = \mathbf{b}\\ \mathbf{T} \geq 0, M_{i,j} = d(x_i,y_j)\end{aligned}\end{align} \]

可以用以下代码解决：

res = ot.solve_sample(xa, xb, a, b, reg=1.0, reg_type='L2')

• 不平衡OT [41] （当 unbalanced!=None）：

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_u U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_u U(\mathbf{T}^T\mathbf{1},\mathbf{b})\\\text{其中} \ M_{i,j} = d(x_i,y_j)\end{aligned}\end{align} \]

可以用以下代码解决：

# default is ``"KL"``
res = ot.solve_sample(xa, xb, a, b, unbalanced=1.0)
# quadratic unbalanced OT
res = ot.solve_sample(xa, xb, a, b, unbalanced=1.0,unbalanced_type='L2')
# TV = partial OT
res = ot.solve_sample(xa, xb, a, b, unbalanced=1.0,unbalanced_type='TV')

• 正则化不平衡正则化OT [34] （当 unbalanced!=None 和 reg!=None）：

\[ \begin{align}\begin{aligned}\min_{\mathbf{T}\geq 0} \quad \sum_{i,j} T_{i,j}M_{i,j} + \lambda_r R(\mathbf{T}) + \lambda_u U(\mathbf{T}\mathbf{1},\mathbf{a}) + \lambda_u U(\mathbf{T}^T\mathbf{1},\mathbf{b})\\\text{其中} \ M_{i,j} = d(x_i,y_j)\end{aligned}\end{align} \]

可以用以下代码解决：

# default is ``"KL"`` for both
res = ot.solve_sample(xa, xb, a, b, reg=1.0, unbalanced=1.0)
# quadratic unbalanced OT with KL regularization
res = ot.solve_sample(xa, xb, a, b, reg=1.0, unbalanced=1.0,unbalanced_type='L2')
# both quadratic
res = ot.solve_sample(xa, xb, a, b, reg=1.0, reg_type='L2',
unbalanced=1.0, unbalanced_type='L2')

• 分解OT [2] （当 method='factored'）：

该方法解决以下OT问题 [40]_

\[\mathop{\arg \min}_\mu \quad W_2^2(\mu_a,\mu)+ W_2^2(\mu,\mu_b)\]

其中 $mu$ 是一个均匀加权经验分布， \(\mu_a\) 和 \(\mu_b\) 是与源域和目标域中的样本相关的经验测量，而 \(W_2\) 是 Wasserstein 距离。此问题使用确切的 OT 求解器解决，当 reg=None 时，使用 Sinkhorn 求解器解决当 reg!=None。该解决方案提供了两个运输计划，可以用于恢复两个分布之间的低秩 OT 计划。

res = ot.solve_sample(xa, xb, method='factored', rank=10)

# recover the lazy low rank plan
factored_solution_lazy = res.lazy_plan

# recover the full low rank plan
factored_solution = factored_solution_lazy[:]

• 高斯布雷斯特-瓦瑟斯坦 [2] (当 method='gaussian'):

该方法计算从经验分布估计的两个高斯分布之间的高斯Bures-Wasserstein距离

\[\mathcal{W}(\mu_s, \mu_t)_2^2= \left\lVert \mathbf{m}_s - \mathbf{m}_t \right\rVert^2 + \mathcal{B}(\Sigma_s, \Sigma_t)^{2}\]

其中 :

\[\mathbf{B}(\Sigma_s, \Sigma_t)^{2} = \text{Tr}\left(\Sigma_s + \Sigma_t - 2 \sqrt{\Sigma_s^{1/2}\Sigma_t\Sigma_s^{1/2}} \right)\]

协方差和均值是从数据中估计的。

res = ot.solve_sample(xa, xb, method='gaussian')

# recover the squared Gaussian Bures-Wasserstein distance
BW_dist = res.value

• Wasserstein 1d [1]（当 method='1D'）：

该方法计算从经验分布估计的两个一维分布之间的Wasserstein距离。对于多变量数据，各维度的距离独立计算。

res = ot.solve_sample(xa, xb, method='1D')

# recover the squared Wasserstein distances
W_dists = res.value

参考文献

[1]

Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011年12月). 使用拉格朗日质量传输的位移插值. 在ACM图形学汇刊(TOG) (第30卷, 第6期, 第158页). ACM.

[2]

M. Cuturi, Sinkhorn 距离：快速计算最优传输，神经信息处理系统进展（NIPS）26, 2013

[10]

Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016). 缩放算法用于不平衡交通问题。 arXiv 预印本 arXiv:1607.05816.

[17]

Blondel, M., Seguy, V., & Rolet, A. (2018). 平滑与稀疏的最优传输。第二十一届国际人工智能与统计会议（AISTATS）论文集。

[34]

Feydy, J., Séjourné, T., Vialard, F. X., Amari, S. I., Trouvé, A., & Peyré, G. (2019年4月). 使用Sinkhorn散度在最优传输和MMD之间进行插值。在第22届国际人工智能与统计会议(pp. 2681-2690). PMLR.

[40]

Forrow, A., Hütter, J. C., Nitzan, M., Rigollet, P., Schiebinger, G., & Weed, J. (2019年4月). 通过分解耦合进行统计最优传输. 在第22届国际人工智能与统计会议上 (pp. 2454-2465). PMLR.

[41]

Chapel, L., Flamary, R., Wu, H., Févotte, C., 和 Gasso, G. (2021). 通过非负惩罚线性回归进行不平衡最优传输。NeurIPS。

[65]

Scetbon, M., Cuturi, M., & Peyré, G. (2021). 低秩Sinkhorn因式分解。发表于国际机器学习会议。

ot.tic()

Matlab tic()函数的Python实现

ot.toc(message='Elapsed time : {} s')

Matlab toc() 函数的 Python 实现

ot.toq()

Python实现的Julia toc()函数

ot.unif(n, type_as=None)

返回长度为 n 的均匀直方图（单纯形）。

Parameters:

• n (int) – 直方图中的箱子数量

• type_as (array-like) – 与预期输出相同类型的数组 (numpy/pytorch/jax)

Returns:

h – 长度为 n 的直方图，使得 \(\forall i, \mathbf{h}_i = \frac{1}{n}\)

Return type:

类似数组，形状 (n,)

ot.wasserstein_1d(u_values, v_values, u_weights=None, v_weights=None, p=1, require_sort=True)

计算两个（批处理的）经验分布之间的1维OT损失[15]

它正式地是p-Wasserstein距离的p次方。我们通过首先构建各个分位数函数，然后对它们进行积分，以向量化的方式进行。

当后端与numpy不同，并且需要对样本位置或权重进行梯度计算时，应优先使用此函数而不是 emd_1d。

Parameters:

• u_values (数组类型, 形状 (n, ...)) – 第一个经验分布的位置

• v_values (类数组, 形状 (m, ...)) – 第二个经验分布的位置

• u_weights (类似数组, 形状 (n, ...), 可选) – 第一组经验分布的权重，如果为 None，则使用均匀权重

• v_weights (array-like, 形状 (m, ...), 可选) – 第二个经验分布的权重，如果为 None 则使用均匀权重

• p (int, 可选) – 使用的基础度量的阶数，应该至少为 1（见 [2, 第 2 章]，默认为 1

• require_sort (bool, optional) – 对分布原子的位置信息进行排序，如果为 False，我们将认为它们在传递给函数之前已经被排序，默认值为 True

Returns:

cost – 批量化的EMD

Return type:

浮点数/类似数组，形状 (…)

参考文献

[15]

Peyré, G., & Cuturi, M. (2018). 计算最优运输.

ot.wasserstein_circle(u_values, v_values, u_weights=None, v_weights=None, p=1, Lm=10, Lp=10, tm=-1, tp=1, eps=1e-06, require_sort=True)

使用[45]计算圆上的Wasserstein距离，当p=1时使用，其他情况下使用[44]提出的二分查找算法。样本需要在\(S^1\cong [0,1[\)中。如果它们在\(\mathbb{R}\)上，则取模1的值。如果值在\(S^1\subset\mathbb{R}^2\)上，则需要首先使用例如atan2函数找到坐标。

返回的总损失：

\[OT_{loss} = \inf_{\theta\in\mathbb{R}}\int_0^1 |cdf_u^{-1}(q) - (cdf_v-\theta)^{-1}(q)|^p\ \mathrm{d}q\]

对于 p=1, [45]

\[W_1(u,v) = \int_0^1 |F_u(t)-F_v(t)-LevMed(F_u-F_v)|\ \mathrm{d}t\]

对于值 \(x=(x_1,x_2)\in S^1\)，需要首先获取它们的坐标，方法是

\[u = \frac{\pi + \mathrm{atan2}(-x_2,-x_1)}{2\pi}\]

使用例如 ot.utils.get_coordinate_circle(x)

该函数在后台运行，但不支持tensorflow和jax。

Parameters:

• u_values (ndarray, shape (n, ...)) – 源域中的样本（坐标在 [0,1[）

• v_values (ndarray, shape (n, ...)) – 目标领域中的样本（坐标在 [0,1[ 上）

• u_weights (ndarray, shape (n, ...), optional) – 源领域中的样本权重

• v_weights (ndarray, shape (n, ...), 可选) – 目标域中的样本权重

• p (float, 可选 (默认=1)) – 用于计算Wasserstein距离的功率p

• Lm (int, 可选) – 下界 dC。对于 p>1。

• Lp (int, 可选) – 上限 dC。对于 p>1。

• tm (float, 可选) – 下界theta。对于 p>1。

• tp (float, 可选) – 上界 theta。对于 p>1。

• eps (float, 可选) – 停止条件。对于 p>1。

• require_sort (bool, 可选) – 如果为 True，则对值进行排序。

Returns:

loss – 与最佳运输相关的成本

Return type:

float

示例

>>> u = np.array([[0.2,0.5,0.8]])%1
>>> v = np.array([[0.4,0.5,0.7]])%1
>>> wasserstein_circle(u.T, v.T)
array([0.1])

参考文献

[44]

Hundrieser, Shayan, Marcel Klatt, 和 Axel Munk. “圆形最优运输的统计.” 创新应用的方向统计: 纪念佛罗伦斯·南丁格尔二百周年. 新加坡: 施普林格自然新加坡, 2022. 57-82.

[45]

Delon, Julie, Julien Salomon, 和 Andrei Sobolevski. “针对圆形上的Monge成本的快速运输优化。” SIAM应用数学杂志 70.7 (2010): 2239-2258.

ot.weak_optimal_transport(Xa, Xb, a=None, b=None, verbose=False, log=False, G0=None, **kwargs)

解决两个经验分布之间的弱最优运输问题

\[ \begin{align}\begin{aligned}\gamma = \mathop{\arg \min}_\gamma \quad \sum_i \mathbf{a}_i \left(\mathbf{X^a}_i - \frac{1}{\mathbf{a}_i} \sum_j \gamma_{ij} \mathbf{X^b}_j \right)^2\\s.t. \ \gamma \mathbf{1} = \mathbf{a}\\ \gamma^T \mathbf{1} = \mathbf{b}\\ \gamma \geq 0\end{aligned}\end{align} \]

其中 :

• \(X^a\) 和 \(X^b\) 是样本矩阵。

• \(\mathbf{a}\) 和 \(\mathbf{b}\) 是样本权重

注意

此函数与后端兼容，可用于所有兼容后端的数组。但该算法使用C++ CPU后端，这可能导致在GPU数组上产生复制开销。

使用条件梯度算法来解决在 [39] 中提出的问题。

Parameters:

• Xa ((ns,d) 数组类型, 浮点数) – 源样本

• Xb ((nt,d) 数组类型, 浮点数) – 目标样本

• a ((ns,) 数组类似, 浮点数) – 源直方图（如果空列表，则均匀权重）

• b ((nt,) 类数组, 浮点数) – 目标直方图（如果为空列表则为均匀权重）

• G0 ((ns,nt) 数组类似, 浮动) – 初始猜测（默认是独立的联合密度）

• numItermax (int, 可选) – 最大迭代次数

• numItermaxEmd (int, 可选) – emd的最大迭代次数

• stopThr (float, 可选) – 相对变化的停止阈值 (>0)

• stopThr2 (float, 可选的) – 绝对变化的停止阈值 (>0)

• verbose (bool, 可选) – 在迭代过程中打印信息

• log (bool, 可选) – 如果为真，则记录日志

Returns:

• gamma (类似数组，形状为 (ns, nt)) – 给定参数的最优运输矩阵

• log (字典，可选) – 如果输入日志为真，将返回一个包含成本、对偶变量和退出状态的字典

参考文献

[39]

Gozlan, N., Roberto, C., Samson, P. M., & Tetali, P. (2017). 关于一般运输成本的Kantorovich对偶性及其应用。 《函数分析杂志》, 273(11), 3327-3405.

另请参见

ot.bregman.sinkhorn

熵正则化最优传输

ot.optim.cg

通用正则化OT