torch.masked

介绍

动机

警告

PyTorch API 中的掩码张量处于原型阶段，未来可能会发生变化，也可能不会发生变化。

MaskedTensor 作为 torch.Tensor 的扩展，为用户提供了以下功能：

• 使用任何掩码语义（例如变长张量、nan* 运算符等）

• 区分0和NaN梯度

• 各种稀疏应用（见下面的教程）

“指定”和“未指定”在 PyTorch 中有着悠久的历史，但没有正式的语义，当然也没有一致性；事实上，MaskedTensor 的诞生源于普通 torch.Tensor 类无法妥善解决的一系列问题。因此，MaskedTensor 的主要目标之一是成为 PyTorch 中“指定”和“未指定”值的权威来源，使它们成为一流的公民，而不是事后的想法。 反过来，这应该进一步释放 稀疏性的潜力， 实现更安全、更一致的运算符，并为用户和开发者提供更流畅、更直观的体验。

什么是 MaskedTensor？

MaskedTensor 是一个张量子类，由 1) 一个输入（数据）和 2) 一个掩码组成。掩码告诉我们应该包含或忽略输入中的哪些条目。

举例来说，假设我们想要屏蔽所有等于0的值（用灰色表示）并取最大值：

上方是普通的张量示例，而下方是MaskedTensor，其中所有的0都被屏蔽了。 这显然会根据我们是否有掩码而产生不同的结果，但这种灵活的结构 允许用户在计算过程中系统性地忽略他们希望忽略的任何元素。

我们已经编写了许多现有的教程来帮助用户入门，例如：

• 概述 - 新用户的起点，讨论如何使用MaskedTensors以及它们为什么有用

• 稀疏性 - MaskedTensor 支持稀疏 COO 和 CSR 数据以及掩码张量

• Adagrad 稀疏语义 - 一个实际示例，展示了 MaskedTensor 如何简化稀疏语义和实现

• 高级语义 - 讨论为什么做出某些决定（例如，要求掩码匹配二元/归约操作），与NumPy的MaskedArray的区别，以及归约语义

支持的运算符

一元运算符

一元运算符是只包含单个输入的运算符。 将其应用于MaskedTensors相对简单：如果给定索引处的数据被屏蔽， 我们将应用该运算符，否则我们将继续屏蔽数据。

可用的单目运算符有：

绝对值	计算input中每个元素的绝对值。
绝对值	别名用于 torch.abs()
acos	计算 input 中每个元素的反余弦值。
arccos	别名用于 torch.acos()。
acosh	返回一个新的张量，其中包含 input 元素的反双曲余弦值。
arccosh	别名用于 torch.acosh()。
角度	计算给定输入张量的逐元素角度（以弧度为单位）。
asin	返回一个新的张量，其中包含 input 元素的反正弦值。
arcsin	别名用于 torch.asin()。
asinh	返回一个新的张量，其中包含input元素的反双曲正弦值。
arcsinh	别名 torch.asinh()。
atan	返回一个新的张量，包含 input 元素的反正切值。
arctan	别名用于 torch.atan()。
atanh	返回一个新的张量，其中包含 input 元素的反双曲正切值。
arctanh	别名 torch.atanh()。
bitwise_not	计算给定输入张量的按位取反。
ceil	返回一个新的张量，其中包含 input 元素的向上取整值，即大于或等于每个元素的最小整数。
clamp	将 input 中的所有元素限制在范围 [ min, max ] 内。
clip	别名用于 torch.clamp()。
conj_physical	计算给定输入张量的逐元素共轭。
cos	返回一个新的张量，其中包含input元素的余弦值。
cosh	返回一个新的张量，其中包含 input 元素的双曲余弦值。
deg2rad	返回一个新的张量，其中包含将input中的每个元素从角度转换为弧度的结果。
digamma	别名 torch.special.digamma()。
erf	别名用于 torch.special.erf()。
erfc	别名用于 torch.special.erfc()。
erfinv	别名 torch.special.erfinv()。
exp	返回一个新的张量，其中包含输入张量input元素的指数。
exp2	别名用于 torch.special.exp2()。
expm1	别名 torch.special.expm1()。
fix	别名用于 torch.trunc()
floor	返回一个新的张量，其中包含 input 元素的向下取整值，即每个元素的最大整数，该整数小于或等于该元素。
frac	计算input中每个元素的小数部分。
lgamma	计算伽马函数在输入上的绝对值的自然对数。
log	返回一个新的张量，其中包含input元素的自然对数。
log10	返回一个新的张量，其中包含input元素的以10为底的对数。
log1p	返回一个新的张量，包含（1 + input）的自然对数。
log2	返回一个新的张量，其中包含input元素的以2为底的对数。
logit	别名用于 torch.special.logit()。
i0	别名 torch.special.i0()。
isnan	返回一个包含布尔元素的新张量，表示input中的每个元素是否为NaN。
nan_to_num	替换 NaN、正无穷大和负无穷大值在 input 中分别使用 nan、posinf 和 neginf 指定的值。
neg	返回一个新的张量，其中包含 input 元素的负值。
negative	别名用于 torch.neg()
positive	返回 input。
pow	将input中的每个元素的幂次方与exponent相乘，并返回一个包含结果的张量。
rad2deg	返回一个新的张量，其中包含将input中的每个元素从弧度转换为度数的结果。
倒数	返回一个新的张量，其中包含input元素的倒数
round	将 input 的元素四舍五入到最近的整数。
rsqrt	返回一个新的张量，其中包含input中每个元素的平方根的倒数。
sigmoid	别名用于 torch.special.expit()。
符号	返回一个新的张量，其中包含input元素的符号。
sgn	此函数是 torch.sign() 对复数张量的扩展。
signbit	测试input的每个元素是否设置了符号位。
sin	返回一个新的张量，其中包含 input 元素的正弦值。
sinc	别名 torch.special.sinc()。
sinh	返回一个新的张量，其中包含input元素的双曲正弦值。
sqrt	返回一个新的张量，其中包含input元素的平方根。
平方	返回一个新的张量，其中包含input元素的平方。
tan	返回一个新的张量，其中包含 input 元素的正切值。
tanh	返回一个新的张量，其中包含input元素的双曲正切值。
trunc	返回一个新的张量，其中包含 input 元素的截断整数值。

可用的就地一元运算符包括上述所有除了：

角度	计算给定输入张量的逐元素角度（以弧度为单位）。
positive	返回 input。
signbit	测试input的每个元素是否设置了符号位。
isnan	返回一个包含布尔元素的新张量，表示input中的每个元素是否为NaN。

二元运算符

正如您在教程中可能已经看到的，MaskedTensor 也实现了二元操作，但需要注意的是，两个 MaskedTensor 的掩码必须匹配，否则将引发错误。正如错误中提到的，如果您需要对特定操作符的支持或提出了它们应如何表现的语义建议，请在 GitHub 上提出问题。目前，我们决定采用最保守的实现，以确保用户确切地知道发生了什么，并且对他们的掩码语义决策是有意的。

可用的二元运算符有：

add	将 other 按 alpha 缩放后加到 input 上。
atan2	逐元素的反正切值 $\text{input}_{i} / \text{other}_{i}$，考虑了象限。
arctan2	别名 torch.atan2()。
bitwise_and	计算 input 和 other 的按位与。
bitwise_or	计算 input 和 other 的按位或。
按位异或	计算 input 和 other 的按位异或。
bitwise_left_shift	计算 input 的左算术移位，移位位数为 other。
bitwise_right_shift	计算 input 向右算术移位 other 位。
div	将输入的每个元素 input 除以 other 中对应的元素。
divide	别名用于 torch.div()。
floor_divide
fmod	逐元素应用 C++ 的 std::fmod。
logaddexp	输入的指数和的对数。
logaddexp2	以2为底的输入的指数和的对数。
mul	将 input 乘以 other。
multiply	别名用于 torch.mul()。
nextafter	返回 input 之后朝向 other 的下一个浮点值，逐元素操作。
余数	逐元素计算 Python 的取模运算。
sub	从 input 中减去按 alpha 缩放的 other。
subtract	别名用于 torch.sub()。
true_divide	别名，用于 torch.div() 并带有 rounding_mode=None。
eq	计算元素逐个相等性
ne	计算 $\text{input} \neq \text{other}$ 逐元素。
le	计算 $\text{input} \leq \text{other}$ 逐元素。
ge	计算 $\text{input} \geq \text{other}$ 逐元素。
greater	别名用于 torch.gt()。
greater_equal	别名用于 torch.ge()。
gt	计算 $\text{input} > \text{other}$ 逐元素。
less_equal	别名用于 torch.le()。
lt	计算 $\text{input} < \text{other}$ 逐元素。
less	别名用于 torch.lt()。
最大值	计算 input 和 other 的逐元素最大值。
最小值	计算 input 和 other 的逐元素最小值。
fmax	计算 input 和 other 的逐元素最大值。
fmin	计算 input 和 other 的逐元素最小值。
not_equal	别名用于 torch.ne()。

可用的就地二元运算符包括上述所有除了：

logaddexp	输入的指数和的对数。
logaddexp2	以2为底的输入的指数和的对数。
equal	True 如果两个张量具有相同的大小和元素，False 否则。
fmin	计算 input 和 other 的逐元素最小值。
最小值	计算 input 和 other 的逐元素最小值。
fmax	计算 input 和 other 的逐元素最大值。

归约

以下是可用的缩减操作（支持自动微分）。更多信息，请参阅 概述教程， 其中详细介绍了一些缩减操作的示例，而 高级语义教程 则进一步深入讨论了我们如何确定某些缩减语义。

sum	返回input张量中所有元素的总和。
均值	返回input张量中所有元素的平均值。
amin	返回在给定维度dim中，input张量每个切片的最低值。
amax	返回在给定维度dim中，input张量每个切片的的最大值。
argmin	返回展平张量或沿某个维度最小值的索引
argmax	返回input张量中所有元素的最大值的索引。
prod	返回input张量中所有元素的乘积。
all	测试input中的所有元素是否都评估为True。
norm	返回给定张量的矩阵范数或向量范数。
var	计算由 dim 指定的维度的方差。
std	计算由 dim 指定的维度的标准差。

查看和选择函数

我们还包括了许多视图和选择函数；直观地说，这些操作符将同时应用于数据和掩码，然后将结果包装在MaskedTensor中。举个简单的例子，考虑select()：

>>> data = torch.arange(12, dtype=torch.float).reshape(3, 4)
>>> data
tensor([[ 0.,  1.,  2.,  3.],
        [ 4.,  5.,  6.,  7.],
        [ 8.,  9., 10., 11.]])
>>> mask = torch.tensor([[True, False, False, True], [False, True, False, False], [True, True, True, True]])
>>> mt = masked_tensor(data, mask)
>>> data.select(0, 1)
tensor([4., 5., 6., 7.])
>>> mask.select(0, 1)
tensor([False,  True, False, False])
>>> mt.select(0, 1)
MaskedTensor(
  [      --,   5.0000,       --,       --]
)

目前支持以下操作：

atleast_1d	返回每个输入张量的零维度的1维视图。
broadcast_tensors	根据广播语义广播给定的张量。
broadcast_to	将 input 广播到形状 shape。
cat	在给定的维度上连接给定的 seq 张量序列。
chunk	尝试将张量分割成指定数量的块。
column_stack	通过水平堆叠tensors中的张量来创建一个新的张量。
dsplit	将input（一个具有三个或更多维度的张量）根据indices_or_sections沿深度方向分割成多个张量。
flatten	将 input 通过重塑为一维张量来展平。
hsplit	将input（一个具有一个或多个维度的张量）根据indices_or_sections水平分割成多个张量。
hstack	按顺序水平（列方向）堆叠张量。
kron	计算克罗内克积，记为 $\otimes$，由 input 和 other 组成。
meshgrid	创建由attr:tensors中的一维输入指定的坐标网格。
narrow	返回一个新的张量，它是 input 张量的缩小版本。
ravel	返回一个连续的展平张量。
选择	沿着选定的维度在给定的索引处对input张量进行切片。
split	将张量分割成多个块。
t	期望 input 为 <= 2-D 张量，并转置维度 0 和 1。
转置	返回一个张量的转置版本，该张量是 input 的转置。
vsplit	将input（一个具有两个或更多维度的张量）根据indices_or_sections垂直分割成多个张量。
vstack	按顺序垂直（行方向）堆叠张量。
Tensor.expand	返回一个新的视图，其中 self 张量的单一维度扩展为更大的尺寸。
Tensor.expand_as	将此张量扩展为与 other 相同的大小。
Tensor.reshape	返回一个与self具有相同数据和元素数量的张量，但具有指定的形状。
Tensor.reshape_as	返回此张量，其形状与 other 相同。
Tensor.view	返回一个与 self 张量具有相同数据但形状不同的新张量。