评价此页

torch.masked#

创建时间:2022 年 8 月 15 日 | 最后更新时间:2025 年 6 月 17 日

引言#

动机#

警告

PyTorch 的掩码张量 API 处于原型阶段,将来可能会或可能不会改变。

MaskedTensor 是 torch.Tensor 的扩展,它为用户提供了以下能力:

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

  • 区分 0 和 NaN 梯度

  • 各种稀疏应用(请参阅下面的教程)

“指定”和“未指定”在 PyTorch 中有着悠久的历史,但没有正式的语义,更没有一致性;事实上,MaskedTensor 是在香草 torch.Tensor 类无法正确解决的一系列问题之上诞生的。因此,MaskedTensor 的主要目标是成为 PyTorch 中所述“指定”和“未指定”值的真相来源,在那里它们是头等公民而不是事后诸葛亮。反过来,这应该进一步释放稀疏性的潜力,实现更安全、更一致的运算符,并为用户和开发人员提供更流畅、更直观的体验。

什么是 MaskedTensor?#

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

举个例子,假设我们想掩盖所有等于 0 的值(由灰色表示)并取最大值

_images/tensor_comparison.jpg

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

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

支持的运算符#

一元运算符#

一元运算符是只包含单个输入的运算符。将它们应用于 MaskedTensor 相对简单:如果给定索引处的数据被掩盖,我们应用运算符,否则我们将继续掩盖数据。

可用的一元运算符包括

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

返回一个新张量,其中包含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的指数。

exp2

torch.special.exp2() 的别名。

expm1

torch.special.expm1() 的别名。

fix

torch.trunc() 的别名

floor

返回一个新张量,其中包含 input 元素的向下取整值,即小于或等于每个元素的最大整数。

frac

计算input中每个元素的小数部分。

lgamma

计算 input 上伽马函数绝对值的自然对数。

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

input 中的 NaN、正无穷和负无穷值分别替换为 nanposinfneginf 指定的值。

neg

返回一个新张量,其中包含input元素的负值。

negative

torch.neg() 的别名

positive

返回 input

pow

计算 input 中每个元素的 exponent 次幂,并返回一个包含结果的张量。

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

返回一个新张量,其中包含布尔元素,表示 input 的每个元素是否为 NaN。

二元运算符#

如您在教程中看到的,MaskedTensor 也实现了二元操作,但需要注意的是,两个 MaskedTensor 中的掩码必须匹配,否则会引发错误。正如错误中提到的,如果您需要对特定运算符的支持,或者对它们的行为方式有建议的语义,请在 GitHub 上提出问题。目前,我们决定采用最保守的实现,以确保用户确切地了解正在发生的事情,并有意识地决定掩码语义。

可用的二元运算符包括

add

other(按 alpha 缩放)添加到 input

atan2

逐元素计算 inputi/otheri\text{input}_{i} / \text{other}_{i} 的反正切,并考虑象限。

arctan2

torch.atan2() 的别名。

bitwise_and

计算 inputother 的按位 AND。

bitwise_or

计算 inputother 的按位 OR。

bitwise_xor

计算 inputother 的按位 XOR。

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

逐元素返回 inputother 方向的下一个浮点值。

remainder

逐元素计算 Python 的模运算

sub

input 中减去 other(按 alpha 缩放)。

subtract

torch.sub() 的别名。

true_divide

rounding_mode=None 时,torch.div() 的别名。

eq

计算逐元素相等

ne

逐元素计算 inputother\text{input} \neq \text{other}

le

逐元素计算 inputother\text{input} \leq \text{other}

ge

逐元素计算 inputother\text{input} \geq \text{other}

greater

torch.gt() 的别名。

greater_equal

torch.ge() 的别名。

gt

逐元素计算 input>other\text{input} > \text{other}

less_equal

torch.le() 的别名。

lt

逐元素计算 input<other\text{input} < \text{other}

less

torch.lt() 的别名。

maximum

计算 inputother 的逐元素最大值。

minimum

计算 inputother 的逐元素最小值。

fmax

计算 inputother 的逐元素最大值。

fmin

计算 inputother 的逐元素最小值。

not_equal

torch.ne() 的别名。

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

logaddexp

输入指数和的对数。

logaddexp2

以2为底的输入指数和的对数。

equal

如果两个张量具有相同的大小和元素,则为True,否则为False

fmin

计算 inputother 的逐元素最小值。

minimum

计算 inputother 的逐元素最小值。

fmax

计算 inputother 的逐元素最大值。

约简#

以下约简可用(支持自动梯度)。有关更多信息,概述教程详细介绍了一些约简示例,而高级语义教程对我们如何确定某些约简语义有一些更深入的讨论。

sum

返回 input 张量中所有元素的和。

mean

amin

返回 input 张量在给定维度 dim 中的每个切片的最小值。

amax

返回 input 张量在给定维度 dim 中的每个切片的最大值。

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

返回每个零维输入张量的一维视图。

broadcast_tensors

根据广播语义广播给定的张量。

broadcast_to

input 广播到形状 shape

cat

在给定维度中连接 tensors 中的给定张量序列。

chunk

尝试将张量分割成指定数量的块。

column_stack

通过水平堆叠tensors中的张量来创建新张量。

dsplit

根据 indices_or_sectionsinput(一个具有三维或更多维度的张量)深度分割成多个张量。

flatten

通过将 input 重塑为一维张量来将其展平。

hsplit

根据 indices_or_sectionsinput(一个具有一维或更多维度的张量)水平分割成多个张量。

hstack

按水平(列方向)顺序堆叠张量。

kron

计算 inputother 的克罗内克积,表示为 \otimes

meshgrid

创建由 attr:tensors 中一维输入指定的坐标网格。

narrow

返回一个新的张量,它是 input 张量的缩窄版本。

nn.functional.unfold

从批量输入张量中提取滑动局部块。

ravel

返回一个连续的展平张量。

select

沿所选维度在给定索引处切分 input 张量。

split

将张量分割成块。

stack

沿新维度连接一系列张量。

t

期望input为小于等于2维的张量,并转置维度0和1。

转置

返回一个张量,它是 input 的转置版本。

vsplit

根据 indices_or_sectionsinput(一个具有二维或更多维度的张量)垂直分割成多个张量。

vstack

按垂直(行方向)顺序堆叠张量。

Tensor.expand

返回 self 张量的新视图,其中单例维度已扩展到更大的大小。

Tensor.expand_as

将此张量扩展为与 other 相同的大小。

Tensor.reshape

返回一个张量,其数据和元素数量与 self 相同,但形状已指定。

Tensor.reshape_as

将此张量返回为与 other 相同的形状。

Tensor.unfold

返回原始张量的视图,其中包含 self 张量中在维度 dimension 处所有大小为 size 的切片。

Tensor.view

返回一个新张量,其数据与 self 张量相同,但 shape 不同。