torch.masked

介绍

赋予动机

警告

掩码张量的 PyTorch API 处于原型阶段，将来可能会也可能不会更改。

MaskedTensor 作为扩展，使用户能够：

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

• 区分 0 和 NaN 梯度

• 各种稀疏应用程序（请参阅下面的教程）

“Specified” 和 “unspecified” 在 PyTorch 中有着悠久的历史，没有正式的语义，当然也没有 一致性;事实上，MaskedTensor 诞生于 vanilla 类无法正确解决的一系列问题。因此，MaskedTensor 的主要目标是成为 在 PyTorch 中表示“指定”和“未指定”值，它们是一等公民，而不是事后的想法。 反过来，这应该会进一步释放稀疏的潜力， 使操作员更安全、更一致，并提供更流畅、更直观的体验 对用户和开发人员来说都是如此。

什么是 MaskedTensor？

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

举个例子，假设我们想屏蔽掉所有等于 0 的值（由灰色表示） 并取最大值：

顶部是 vanilla 张量示例，而底部是 MaskedTensor，其中所有 0 都被屏蔽掉了。 这显然会产生不同的结果，具体取决于我们是否有掩码，但这种灵活的结构 允许用户在计算过程中系统地忽略他们想要的任何元素。

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

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

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

• Adagrad 稀疏语义 - MaskedTensor 如何简化稀疏语义和实现的实际示例

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

支持的运算符

一元运算符

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

可用的一元运算符包括：

ABS 抗体	计算 中每个元素的绝对值。input
绝对	别名
ACOS	计算 中每个元素的反余弦值。input
arccos	的别名 .
阿科什	返回一个具有 的元素的反双曲余弦的新张量。input
阿克科什	的别名 .
角度	计算给定张量的元素角度（以弧度为单位）。input
ASIN （英文）	返回一个新张量，其中包含 的元素的反正弦值。input
arcsin	的别名 .
阿辛	返回一个新张量，其中包含 的元素的反双曲正弦值。input
阿辛	的别名 .
阿坦	返回一个具有 元素的反正切值的新张量。input
arctan （反正）	的别名 .
阿坦	返回一个具有 的元素的反双曲正切的新张量。input
阿克坦	的别名 .
bitwise_not	计算给定输入张量的按位 NOT。
CEIL	返回一个新的张量，其中元素的 ceil 为 ，大于或等于每个元素的最小整数。input
钳	将所有元素限制在 [ ， ] 范围内。input
夹	的别名 .
conj_physical	计算给定张量的元素共轭。input
因为	返回一个新张量，其元素的余弦值为 。input
嘲	返回一个具有 元素的双曲余弦值的新张量。input
deg2rad	返回一个新的张量，其中包含从以度为单位的角度转换为弧度的每个元素。input
迪伽马	的别名 .
ERF	的别名 .
ERFC	的别名 .
埃尔芬夫	的别名 .
exp （英文）	返回一个新张量，其 input tensor 的元素是指数。input
exp2	的别名 .
expm1	的别名 .
修复	别名
地板	返回一个新张量，其中元素的下限为 ，是小于或等于每个元素的最大整数。input
压裂	计算 中每个元素的小数部分。input
lgamma	计算 上 的 gamma 函数绝对值的自然对数。input
日志	返回一个具有 元素的自然对数的新张量。input
对数 10	返回一个新的张量，其对数为 的 以 的 10 为底的元素。input
对数 1p	返回自然对数为 （1 + ） 的新张量。input
日志 2	返回一个新的张量，其对数为 以 的 2 为底的元素。input
罗吉特	的别名 .
i0	的别名 .
伊斯南	返回一个新的张量，其中包含布尔元素，表示 的每个元素是否为 NaN。input
nan_to_num	将 、 中的正无穷大和负无穷大值分别替换为 、 和 中指定的值。NaNinputnanposinfneginf
负	返回一个元素为 负数的新张量。input
阴性	别名
阳性	返回。input
战俘	获取 with 中每个元素的幂，并返回包含结果的张量。inputexponent
rad2度	返回一个新的张量，其中每个元素都从以弧度为单位的角度转换为度数。input
倒数	返回一个新张量，其中包含 的元素的倒数input
圆	将 的元素舍入到最接近的整数。input
RSQRT	返回一个新的张量，其中包含 的每个元素的平方根的倒数。input
乙状结肠	的别名 .
标志	返回一个带有 元素符号的新张量。input
新加坡	此函数是 torch.sign（） 对复杂张量的扩展。
signbit	测试每个元素是否设置了其符号位。input
罪	返回一个新张量，其中包含 的元素的正弦值。input
辛	的别名 .
辛	返回一个具有 元素的双曲正弦值的新张量。input
SQRT	返回一个具有 元素的平方根的新张量。input
广场	返回一个新张量，其元素为 的平方。input
鞣	返回一个新张量，其元素的正切值为 。input
丹	返回一个具有 元素的双曲正切的新张量。input
trunc	返回一个新的张量，其中包含 的元素的截断整数值。input

可用的就地一元运算符是上述所有运算符，但以下情况除外：

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

二元运算符

正如您可能在本教程中看到的那样，还实现了二进制运算，但需要注意 两个 MaskedTensor 中的掩码必须匹配，否则将引发错误。如错误中所述，如果您 需要对特定运算符的支持，或者已经提出了它们应该如何行为的语义，请打开 GitHub 上的问题。目前，我们决定采用最保守的实现方式，以确保用户 确切地知道发生了什么，并且有意识地使用掩码语义来做出决策。MaskedTensor

可用的二元运算符有：

加	将 、缩放比例为 的 添加到 。otheralphainput
阿坦2	元素反正切$\text{input}_{i} / \text{other}_{i}$考虑到象限。
反 2	的别名 .
bitwise_and	计算 和 的按位 AND 。inputother
bitwise_or	计算 和 的按位 OR 。inputother
bitwise_xor	计算 和 的按位 XOR 。inputother
bitwise_left_shift	计算 by bits 的左算术移位。inputother
bitwise_right_shift	计算按位的正确算术移位。inputother
迪夫	将输入的每个元素除以 的相应元素。inputother
分	的别名 .
floor_divide
fmod	逐个入口应用 C++ 的 std：：fmod。
logaddexp	输入的幂和的对数。
logaddexp2	以 2 为基数的输入的幂数之和的对数。
多	乘以 。inputother
乘	的别名 .
nextafter	返回 towards 之后的下一个浮点值 ， elementwise。inputother
剩余	按入口计算 Python 的模运算。
子	从 中减去 、缩放 、 。otheralphainput
减去	的别名 .
true_divide	的别名 。rounding_mode=None
情 商	计算元素相等性
NE	计算$\text{input} \neq \text{other}$元素。
乐	计算$\text{input} \leq \text{other}$元素。
通用 电气	计算$\text{input} \geq \text{other}$元素。
大	的别名 .
greater_equal	的别名 .
燃气轮机	计算$\text{input} > \text{other}$元素。
less_equal	的别名 .
中尉	计算$\text{input} < \text{other}$元素。
少	的别名 .
最大	计算 和 的元素最大值。inputother
最低	计算 和 的元素最小值。inputother
fmax	计算 和 的元素最大值。inputother
fmin	计算 和 的元素最小值。inputother
not_equal	的别名 .

可用的就地二进制运算符是上述所有运算符，除了：

logaddexp	输入的幂和的对数。
logaddexp2	以 2 为基数的输入的幂数之和的对数。
平等	True如果两个 Tensor 具有相同的大小和元素，否则。False
fmin	计算 和 的元素最小值。inputother
最低	计算 和 的元素最小值。inputother
fmax	计算 和 的元素最大值。inputother

减少

以下缩减可用（支持 autograd）。有关更多信息，请参阅概述教程 详细介绍了一些 Reduction 的示例，而 Advanced semantics 教程 对我们如何决定某些归约语义进行了一些进一步的深入讨论。

和	返回张量中所有元素的总和。input
意味 着	返回张量中所有元素的平均值。input
阿明	返回给定 dimension（s） 中张量的每个切片的最小值。inputdim
阿麦斯	返回给定 dimension（s） 中张量的每个切片的最大值。inputdim
ARGMIN 公司	返回展平张量的最小值或沿维度的索引
Argmax	返回张量中所有元素的最大值的索引。input
刺	返回张量中所有元素的乘积。input
All	测试 中的所有元素是否计算结果都为 True。input
规范	返回给定张量的矩阵范数或向量范数。
var （无值）	计算 指定的维度的差异。dim
性病	计算 指定的维度的标准差。dim

View 和选择函数

我们还包含了许多 view 和 select 函数;直观地，这些运算符将应用于 数据和掩码，然后将结果包装在 .举个简单的例子， 考虑一下 ：MaskedTensor

>>> 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	返回每个输入张量的一维视图，维度为零。
broadcast_tensors	根据 Broadcasting 语义广播给定的 Tensor。
broadcast_to	广播到形状 。inputshape
猫	连接给定维度中的给定张量序列。seq
块	尝试将张量拆分为指定数量的块。
column_stack	通过在 中水平堆叠张量来创建新的张量。tensors
dsplit	根据 ，将具有三个或更多维度的张量 （Splits） 深度划分为多个张量。inputindices_or_sections
扁平 化	通过将其重塑为一维张量来展平。input
hsplit	Splits ，根据 将具有一个或多个维度的张量水平拆分为多个张量。inputindices_or_sections
hstack	水平顺序（逐列）堆叠张量。
克朗	计算 Kronecker 乘积，表示为$\otimes$、 的 和 。inputother
网格	创建由 attr：tensors 中的 1D 输入指定的坐标网格。
窄	返回一个新的 Tensor，该 Tensor 是 Tensor 的缩小版本。input
nn.functional.展开	从批处理的输入张量中提取滑动局部块。
拉威尔	返回一个连续的扁平化张量。
选择	在给定索引处沿所选维度对张量进行切片。input
分裂	将张量拆分为块。
叠	沿新维度连接一系列张量。
t	期望为 <= 2-D 张量并转置维度 0 和 1。input
Transpose （转置）	返回一个张量，该张量是 的转置版本。input
vsplit	根据 将具有两个或多个维度的张量垂直拆分为多个张量。inputindices_or_sections
VSTACK	按顺序垂直（逐行）堆叠张量。
张量.expand	返回张量的新视图，其中单例维度扩展为更大的大小。self
Tensor.expand_as	将此张量扩展为与 相同的大小。other
Tensor.reshape	返回一个张量，其数据和元素数与指定形状相同。self
Tensor.reshape_as	返回与 相同的形状的此张量。other
张量.unfold	返回原始张量的视图，其中包含维度中 tensor 的所有大小切片。sizeselfdimension
Tensor.view	返回一个新张量，其数据与张量相同，但具有不同的 。selfshape