API和模块
ot:
POT的多库后端 |
|
与熵正则化最优传输相关的Bregman投影求解器 |
|
协同最优运输求解器 |
|
通过最优传输进行领域适应 |
|
简单示例数据集 |
|
使用OT进行降维 |
|
分解OT求解器（低秩，成本或OT计划） |
|
高斯分布的最优运输 |
|
高斯混合的最优传输 |
|
图神经网络中用于最优传输的层和函数。 |
|
与Gromov-Wasserstein问题相关的求解器。 |
|
低秩OT求解器 |
|
原始线性规划OT问题的求解器。 |
|
最优运输地图及其变体 |
|
用于正则化OT或其半放松版本的通用求解器。 |
|
部分OT求解器 |
|
绘制OT矩阵的函数 |
|
正则化路径OT求解器 |
|
切片的OT距离 |
|
平滑和稀疏（KL和L2正则化）以及稀疏约束的最优传输求解器。 |
|
用于正则化OT的随机求解器。 |
|
与不平衡最优运输问题相关的求解器。 |
|
各种实用功能 |
|
弱最优传输求解器 |
主要 ot 功能
警告
自动导入的子模块列表如下：
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时返回日志字典
参考文献
- 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 (类数组 (维度, 历史数量)) – 历史数量 训练分布 \(\mathbf{a}_i\) 的维度 维度
M (类似数组 (维度, 维度)) – OT 的基础度量矩阵。
reg (float) – 熵正则化项 > 0
reg_m (float) – 边际放松项 > 0
权重 (类数组 (n_hists,) 可选) – 每个分布的权重（重心坐标）如果为 None，则使用均匀权重。
numItermax (int, 可选) – 最大迭代次数
stopThr (float, 可选) – 错误的停止阈值 (> 0)
verbose (bool, 可选) – 在迭代过程中打印信息
log (bool, 可选) – 如果为真，则记录日志
- Returns:
a ((dim,) 类数组) – 不平衡Wasserstein重心
log (字典) – 仅当参数log==True时返回日志字典
参考文献
- 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])
参考文献
- 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)) – 如果为真，则使用函数
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]])
参考文献
另请参见
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
参考文献
另请参见
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 = \text{arg}\min_\gamma \sum_i \sum_j \gamma_{ij} d(x_a[i], x_b[j])\\\text{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 ((ns,) 或 (ns, 1) ndarray, float64) – 源 Dirac 位置（在实线上的位置）
x_b ((nt,) 或 (ns, 1) ndarray, float64) – 目标 Dirac 位置（在实数线上）
a ((ns,) ndarray, float64, 可选) – 源直方图（默认为均匀权重）
b ((nt,) ndarray, float64, 可选) – 目标直方图（默认为均匀权重）
metric (str, 可选 (默认='sqeuclidean')) – 要使用的度量。仅适用于以下字符串之一 ‘sqeuclidean’, ‘minkowski’, ‘cityblock’, 或 ‘euclidean’.
p (float, 可选 (默认为1.0)) – 如果 metric=’minkowski’，则应用的 p-norm
dense (boolean, optional (default=True)) – 如果为 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
参考文献
另请参见
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 ((ns,) 或 (ns, 1) ndarray, float64) – 源 Dirac 位置（在实线上的位置）
x_b ((nt,) 或 (ns, 1) ndarray, float64) – 目标 Dirac 位置（在实数线上）
a ((ns,) ndarray, float64, 可选) – 源直方图（默认为均匀权重）
b ((nt,) ndarray, float64, 可选) – 目标直方图（默认为均匀权重）
度量 (str, 可选 (默认='sqeuclidean')) – 要使用的度量。仅适用于字符串 ‘sqeuclidean’, ‘minkowski’, ‘cityblock’ 或 ‘euclidean’.
p (float, 可选 (默认为1.0)) – 如果 metric=’minkowski’，则应用的 p-norm
dense (boolean, 可选 (默认=True)) – 如果为True，则返回形状为 (ns, nt) 的密集 ndarray，值为 math:gamma。否则返回使用 scipy 的 coo_matrix 格式的稀疏表示。由于实现细节，当使用 ‘sqeuclidean’、‘minkowski’、‘cityblock’ 或 ‘euclidean’ 距离度量时，此函数运行得更快。
log (布尔值, 可选 (默认=False)) – 如果为True，将返回一个包含成本的字典。否则仅返回最优运输矩阵。
check_marginals (bool, optional (default=True)) – 如果为 True，将检查边际质量是否相等。如果为 False，跳过检查。
- Returns:
gamma ((ns, nt) ndarray) – 给定参数的最优运输矩阵
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. ]])
参考文献
另请参见
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:
- Returns:
Ga (数组类型，形状为 (ns, r)) – 源与中间分布之间的最优运输矩阵
Gb (数组类型，形状为 (r, nt)) – 中间与目标分布之间的最优运输矩阵
X (数组类型，形状为 (r, d)) – 中间分布的支持
log (字典，可选) – 如果输入日志为真，则返回包含成本和对偶变量及退出状态的字典
参考文献
另请参见
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 (float, 可选) – 权衡参数 (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时返回日志字典。
参考文献
- 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时返回日志字典。
参考文献
- 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,) 重心权重
用于收敛评估的值。
参考文献
- 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) – 收敛信息和损失。
参考文献
- 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) – 收敛信息和耦合矩阵
参考文献
- 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 的和）。
- math:
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字典
参考文献
- 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字典
参考文献
- 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
参考文献
- 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:
示例
>>> x0 = np.array([[0], [0.2], [0.4]]) >>> semidiscrete_wasserstein2_unif_circle(x0) array([0.02111111])
参考文献
- 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()依赖于迭代正则化值（并使用热启动）有时会导致更好的解决方案。请注意，贪婪版本的 sinkhornot.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]])
参考文献
另请参见
ot.lp.emd未正则化的OT
ot.optim.cg通用正则化OT
ot.bregman.sinkhorn_knopp经典Sinkhorn [2]
ot.bregman.sinkhorn_stabilizedot.bregman.sinkhorn_epsilon_scaling
- 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()依靠迭代正则化的值（并使用热启动）有时会导致更好的解决方案。请注意，贪婪版本的 sinkhornot.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{M}\) 的Sinkhorn，如果 \(\mathbf{b}\) 是一个矩阵（返回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
参考文献
另请参见
ot.lp.emd未正则化的OT
ot.optim.cg通用正则化OT
ot.bregman.sinkhorn_knopp经典Sinkhorn [2]
ot.bregman.greenkhornGreenkhorn [21]
ot.bregman.sinkhorn_stabilized
- 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 时返回日志字典
参考文献
另请参见
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]中所提到的。
- 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 (float 或 可索引对象 的 长度为 1 或 2) – 边际松弛项。 如果 \(\mathrm{reg_{m}}\) 是标量或长度为 1 的可索引对象， 则相同的 \(\mathrm{reg_{m}}\) 适用于两个边际松弛。 可以使用 \(\mathrm{reg_{m}}=float("inf")\) 恢复熵平衡 OT。 对于半松弛情况，可以使用 \(\mathrm{reg_{m}}=(float("inf"), scalar)\) 或 \(\mathrm{reg_{m}}=(scalar, 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 –
- gamma(dim_a, dim_b) array-like
给定参数的最优运输矩阵
- logdict
仅在log为True时返回的日志字典
else –
- ot_distance(n_hists,) array-like
\(\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]])
参考文献
另请参见
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]中所提到的。
- 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}\) 与每个直方图 \(\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
参考文献
另请参见
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
参考文献
- 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) – 仅在参数中 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
参考文献
- 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:
- 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
参考文献:
- 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 (array_like, shape (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 (array_like, shape (dim_a, dim_b), optional) – 迭代方法的OT计划初始化，默认值为None
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 损失
有关更多信息，请参见
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')
参考文献
- 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 (array_like, shape (dim_a, dim_a)) – 源域中的成本矩阵
Cb (类似数组, 形状 (dim_b, dim_b)) – 目标域中的成本矩阵
M (array_like, shape (dim_a, dim_b), optional) – 用于融合的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 (array_like, shape (dim_a, dim_b), optional) – 迭代方法的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
参考文献
- 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 时，默认为 Falsebatch_size (int, 可选) – 懒惰求解器的批处理大小，默认为 None （每个求解器的默认值）
方法 (str, 可选) – 解决问题的方法，这可以用来选择不平衡问题的求解器（见
ot.solve），或选择特定的大规模求解器。n_threads (int, 可选) – 用于精确OT求解器的OMP线程数，默认为1
max_iter (int, 可选) – 最大迭代次数，默认为 None（每个求解器的默认值）
plan_init (array_like, shape (dim_a, dim_b), optional) – 迭代方法的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})\\其中 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})\\其中 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
参考文献
- 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:
浮点数/类似数组，形状 (…)
参考文献
- 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:
示例
>>> 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])
参考文献
- 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 (字典，可选) – 如果输入日志为真，将返回一个包含成本、对偶变量和退出状态的字典
参考文献
另请参见
ot.bregman.sinkhorn熵正则化最优传输
ot.optim.cg通用正则化OT