torch.masked

介绍

赋予动机

警告

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

MaskedTensor 用作torch.Tensor这使用户能够：

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

• 区分 0 和 NaN 梯度

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

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

什么是 MaskedTensor？

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

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

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

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

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

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

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

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

支持的运算符

一元运算符

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

可用的一元运算符包括：

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

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

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

二元运算符

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

可用的二元运算符有：

add	将 、缩放比例为 的 添加到 。otheralphainput
atan2	元素反正切$\text{input}_{i} / \text{other}_{i}$考虑到象限。
arctan2	别名torch.atan2().
bitwise_and	计算 和 的按位 AND 。inputother
bitwise_or	计算 和 的按位 OR 。inputother
bitwise_xor	计算 和 的按位 XOR 。inputother
bitwise_left_shift	计算 by bits 的左算术移位。inputother
bitwise_right_shift	计算按位的正确算术移位。inputother
div	将输入的每个元素除以 的相应元素。inputother
divide	别名torch.div().
floor_divide
fmod	逐个入口应用 C++ 的 std：：fmod。
logaddexp	输入的幂和的对数。
logaddexp2	以 2 为基数的输入的幂数之和的对数。
mul	乘以 。inputother
multiply	别名torch.mul().
nextafter	返回 towards 之后的下一个浮点值 ， elementwise。inputother
remainder	按入口计算 Python 的模运算。
sub	从 中减去 、缩放 、 。otheralphainput
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().
maximum	计算 和 的元素最大值。inputother
minimum	计算 和 的元素最小值。inputother
fmax	计算 和 的元素最大值。inputother
fmin	计算 和 的元素最小值。inputother
not_equal	别名torch.ne().

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

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

减少

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

sum	返回张量中所有元素的总和。input
mean	返回张量中所有元素的平均值。input
amin	返回给定 dimension（s） 中张量的每个切片的最小值。inputdim
amax	返回给定 dimension（s） 中张量的每个切片的最大值。inputdim
argmin	返回展平张量的最小值或沿维度的索引
argmax	返回张量中所有元素的最大值的索引。input
prod	返回张量中所有元素的乘积。input
all	测试 中的所有元素是否计算结果都为 True。input
norm	返回给定张量的矩阵范数或向量范数。
var	计算 指定的维度的差异。dim
std	计算 指定的维度的标准差。dim

View 和选择函数

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

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