命名张量操作符覆盖范围

请先阅读命名张量，以了解命名张量的介绍。

本文档是关于名称推断的参考，这是一个定义命名张量如何 命名的过程：

1. 使用名称来提供额外的自动运行时正确性检查

2. 将输入张量的名称传播到输出张量

以下是支持命名张量及其相关名称推断规则的所有操作列表。

如果您在此处未看到列出的操作，但该操作对您的用例有帮助，请搜索是否已提交过问题，如果没有，请提交一个。

警告

命名张量 API 处于实验阶段，可能会发生变化。

支持的操作

API	名称推断规则
Tensor.abs(), torch.abs()	保留输入名称
Tensor.abs_()	保留输入名称
Tensor.acos(), torch.acos()	保留输入名称
Tensor.acos_()	保留输入名称
Tensor.add(), torch.add()	从输入中统一名称
Tensor.add_()	从输入中统一名称
Tensor.addmm(), torch.addmm()	移除维度
Tensor.addmm_()	移除维度
Tensor.addmv(), torch.addmv()	移除维度
Tensor.addmv_()	移除维度
Tensor.align_as()	查看文档
Tensor.align_to()	查看文档
Tensor.all(), torch.all()	请提供需要翻译的单词列表。
Tensor.any(), torch.any()	请提供需要翻译的单词列表。
Tensor.asin(), torch.asin()	保留输入名称
Tensor.asin_()	保留输入名称
Tensor.atan(), torch.atan()	保留输入名称
Tensor.atan2(), torch.atan2()	从输入中统一名称
Tensor.atan2_()	从输入中统一名称
Tensor.atan_()	保留输入名称
Tensor.bernoulli(), torch.bernoulli()	保留输入名称
Tensor.bernoulli_()	请提供需要翻译的单词列表。
Tensor.bfloat16()	保留输入名称
Tensor.bitwise_not(), torch.bitwise_not()	保留输入名称
Tensor.bitwise_not_()	请提供需要翻译的单词列表。
Tensor.bmm(), torch.bmm()	移除维度
Tensor.bool()	保留输入名称
Tensor.byte()	保留输入名称
torch.cat()	从输入中统一名称
Tensor.cauchy_()	请提供需要翻译的单词列表。
Tensor.ceil(), torch.ceil()	保留输入名称
Tensor.ceil_()	请提供需要翻译的单词列表。
Tensor.char()	保留输入名称
Tensor.chunk(), torch.chunk()	保留输入名称
Tensor.clamp(), torch.clamp()	保留输入名称
Tensor.clamp_()	请提供需要翻译的单词列表。
Tensor.copy_()	输出函数和原地操作变体
Tensor.cos(), torch.cos()	保留输入名称
Tensor.cos_()	请提供需要翻译的单词列表。
Tensor.cosh(), torch.cosh()	保留输入名称
Tensor.cosh_()	请提供需要翻译的单词列表。
Tensor.acosh(), torch.acosh()	保留输入名称
Tensor.acosh_()	请提供需要翻译的单词列表。
Tensor.cpu()	保留输入名称
Tensor.cuda()	保留输入名称
Tensor.cumprod(), torch.cumprod()	保留输入名称
Tensor.cumsum(), torch.cumsum()	保留输入名称
Tensor.data_ptr()	请提供需要翻译的单词列表。
Tensor.deg2rad(), torch.deg2rad()	保留输入名称
Tensor.deg2rad_()	请提供需要翻译的单词列表。
Tensor.detach(), torch.detach()	保留输入名称
Tensor.detach_()	请提供需要翻译的单词列表。
Tensor.device, torch.device()	请提供需要翻译的单词列表。
Tensor.digamma(), torch.digamma()	保留输入名称
Tensor.digamma_()	请提供需要翻译的单词列表。
Tensor.dim()	请提供需要翻译的单词列表。
Tensor.div(), torch.div()	从输入中统一名称
Tensor.div_()	从输入中统一名称
Tensor.dot(), torch.dot()	请提供需要翻译的单词列表。
Tensor.double()	保留输入名称
Tensor.element_size()	请提供需要翻译的单词列表。
torch.empty()	工厂函数
torch.empty_like()	工厂函数
Tensor.eq(), torch.eq()	从输入中统一名称
Tensor.erf(), torch.erf()	保留输入名称
Tensor.erf_()	请提供需要翻译的单词列表。
Tensor.erfc(), torch.erfc()	保留输入名称
Tensor.erfc_()	请提供需要翻译的单词列表。
Tensor.erfinv(), torch.erfinv()	保留输入名称
Tensor.erfinv_()	请提供需要翻译的单词列表。
Tensor.exp(), torch.exp()	保留输入名称
Tensor.exp_()	请提供需要翻译的单词列表。
Tensor.expand()	保留输入名称
Tensor.expm1(), torch.expm1()	保留输入名称
Tensor.expm1_()	请提供需要翻译的单词列表。
Tensor.exponential_()	请提供需要翻译的单词列表。
Tensor.fill_()	请提供需要翻译的单词列表。
Tensor.flatten(), torch.flatten()	查看文档
Tensor.float()	保留输入名称
Tensor.floor(), torch.floor()	保留输入名称
Tensor.floor_()	请提供需要翻译的单词列表。
Tensor.frac(), torch.frac()	保留输入名称
Tensor.frac_()	请提供需要翻译的单词列表。
Tensor.ge(), torch.ge()	从输入中统一名称
Tensor.get_device(), torch.get_device()	请提供需要翻译的单词列表。
Tensor.grad	请提供需要翻译的单词列表。
Tensor.gt(), torch.gt()	从输入中统一名称
Tensor.half()	保留输入名称
Tensor.has_names()	查看文档
Tensor.index_fill(), torch.index_fill()	保留输入名称
Tensor.index_fill_()	请提供需要翻译的单词列表。
Tensor.int()	保留输入名称
Tensor.is_contiguous()	请提供需要翻译的单词列表。
Tensor.is_cuda	请提供需要翻译的单词列表。
Tensor.is_floating_point(), torch.is_floating_point()	请提供需要翻译的单词列表。
Tensor.is_leaf	请提供需要翻译的单词列表。
Tensor.is_pinned()	请提供需要翻译的单词列表。
Tensor.is_shared()	请提供需要翻译的单词列表。
Tensor.is_signed(), torch.is_signed()	请提供需要翻译的单词列表。
Tensor.is_sparse	请提供需要翻译的单词列表。
Tensor.is_sparse_csr	请提供需要翻译的单词列表。
torch.is_tensor()	请提供需要翻译的单词列表。
Tensor.item()	请提供需要翻译的单词列表。
Tensor.kthvalue(), torch.kthvalue()	移除维度
Tensor.le(), torch.le()	从输入中统一名称
Tensor.log(), torch.log()	保留输入名称
Tensor.log10(), torch.log10()	保留输入名称
Tensor.log10_()	请提供需要翻译的单词列表。
Tensor.log1p(), torch.log1p()	保留输入名称
Tensor.log1p_()	请提供需要翻译的单词列表。
Tensor.log2(), torch.log2()	保留输入名称
Tensor.log2_()	请提供需要翻译的单词列表。
Tensor.log_()	请提供需要翻译的单词列表。
Tensor.log_normal_()	请提供需要翻译的单词列表。
Tensor.logical_not(), torch.logical_not()	保留输入名称
Tensor.logical_not_()	请提供需要翻译的单词列表。
Tensor.logsumexp(), torch.logsumexp()	移除维度
Tensor.long()	保留输入名称
Tensor.lt(), torch.lt()	从输入中统一名称
torch.manual_seed()	请提供需要翻译的单词列表。
Tensor.masked_fill(), torch.masked_fill()	保留输入名称
Tensor.masked_fill_()	请提供需要翻译的单词列表。
Tensor.masked_select(), torch.masked_select()	将掩码与输入对齐，然后从输入张量中统一名称
Tensor.matmul(), torch.matmul()	移除维度
Tensor.mean(), torch.mean()	移除维度
Tensor.median(), torch.median()	移除维度
Tensor.nanmedian(), torch.nanmedian()	移除维度
Tensor.mm(), torch.mm()	移除维度
Tensor.mode(), torch.mode()	移除维度
Tensor.mul(), torch.mul()	从输入中统一名称
Tensor.mul_()	从输入中统一名称
Tensor.mv(), torch.mv()	移除维度
Tensor.names	查看文档
Tensor.narrow(), torch.narrow()	保留输入名称
Tensor.ndim	请提供需要翻译的单词列表。
Tensor.ndimension()	请提供需要翻译的单词列表。
Tensor.ne(), torch.ne()	从输入中统一名称
Tensor.neg(), torch.neg()	保留输入名称
Tensor.neg_()	请提供需要翻译的单词列表。
torch.normal()	保留输入名称
Tensor.normal_()	请提供需要翻译的单词列表。
Tensor.numel(), torch.numel()	请提供需要翻译的单词列表。
torch.ones()	工厂函数
Tensor.pow(), torch.pow()	从输入中统一名称
Tensor.pow_()	请提供需要翻译的单词列表。
Tensor.prod(), torch.prod()	移除维度
Tensor.rad2deg(), torch.rad2deg()	保留输入名称
Tensor.rad2deg_()	请提供需要翻译的单词列表。
torch.rand()	工厂函数
torch.rand()	工厂函数
torch.randn()	工厂函数
torch.randn()	工厂函数
Tensor.random_()	请提供需要翻译的单词列表。
Tensor.reciprocal(), torch.reciprocal()	保留输入名称
Tensor.reciprocal_()	请提供需要翻译的单词列表。
Tensor.refine_names()	查看文档
Tensor.register_hook()	请提供需要翻译的单词列表。
Tensor.rename()	查看文档
Tensor.rename_()	查看文档
Tensor.requires_grad	请提供需要翻译的单词列表。
Tensor.requires_grad_()	请提供需要翻译的单词列表。
Tensor.resize_()	仅允许调整大小但不改变形状的操作
Tensor.resize_as_()	仅允许调整大小但不改变形状的操作
Tensor.round(), torch.round()	保留输入名称
Tensor.round_()	请提供需要翻译的单词列表。
Tensor.rsqrt(), torch.rsqrt()	保留输入名称
Tensor.rsqrt_()	请提供需要翻译的单词列表。
Tensor.select(), torch.select()	移除维度
Tensor.short()	保留输入名称
Tensor.sigmoid(), torch.sigmoid()	保留输入名称
Tensor.sigmoid_()	请提供需要翻译的单词列表。
Tensor.sign(), torch.sign()	保留输入名称
Tensor.sign_()	请提供需要翻译的单词列表。
Tensor.sgn(), torch.sgn()	保留输入名称
Tensor.sgn_()	请提供需要翻译的单词列表。
Tensor.sin(), torch.sin()	保留输入名称
Tensor.sin_()	请提供需要翻译的单词列表。
Tensor.sinh(), torch.sinh()	保留输入名称
Tensor.sinh_()	请提供需要翻译的单词列表。
Tensor.asinh(), torch.asinh()	保留输入名称
Tensor.asinh_()	请提供需要翻译的单词列表。
Tensor.size()	请提供需要翻译的单词列表。
Tensor.split(), torch.split()	保留输入名称
Tensor.sqrt(), torch.sqrt()	保留输入名称
Tensor.sqrt_()	请提供需要翻译的单词列表。
Tensor.squeeze(), torch.squeeze()	移除维度
Tensor.std(), torch.std()	移除维度
torch.std_mean()	移除维度
Tensor.stride()	请提供需要翻译的单词列表。
Tensor.sub(), torch.sub()	从输入中统一名称
Tensor.sub_()	从输入中统一名称
Tensor.sum(), torch.sum()	移除维度
Tensor.tan(), torch.tan()	保留输入名称
Tensor.tan_()	请提供需要翻译的单词列表。
Tensor.tanh(), torch.tanh()	保留输入名称
Tensor.tanh_()	请提供需要翻译的单词列表。
Tensor.atanh(), torch.atanh()	保留输入名称
Tensor.atanh_()	请提供需要翻译的单词列表。
torch.tensor()	工厂函数
Tensor.to()	保留输入名称
Tensor.topk(), torch.topk()	移除维度
Tensor.transpose(), torch.transpose()	对维度进行置换
Tensor.trunc(), torch.trunc()	保留输入名称
Tensor.trunc_()	请提供需要翻译的单词列表。
Tensor.type()	请提供需要翻译的单词列表。
Tensor.type_as()	保留输入名称
Tensor.unbind(), torch.unbind()	移除维度
Tensor.unflatten()	查看文档
Tensor.uniform_()	请提供需要翻译的单词列表。
Tensor.var(), torch.var()	移除维度
torch.var_mean()	移除维度
Tensor.zero_()	请提供需要翻译的单词列表。
torch.zeros()	工厂函数

保留输入名称

所有逐点一元函数都遵循此规则，还有一些其他的一元函数也是如此。

• 检查名称：None

• 传播名称：输入张量的名称将传播到输出。

>>> x = torch.randn(3, 3, names=('N', 'C'))
>>> x.abs().names
('N', 'C')

移除维度

所有约简操作，如 sum() 通过减少所需维度来移除维度。其他操作如 select() 和 squeeze() 也会移除维度。

在可以将整数维度索引传递给操作符的任何地方，也可以传递维度名称。接受维度索引列表的函数也可以接受维度名称列表。

• 检查名称：如果以名称列表的形式传入 dim 或 dims， 请确认这些名称存在于 self 中。

• 传播名称：如果由 dim 或 dims 指定的输入张量的维度在输出张量中不存在，则这些维度的相应名称不会出现在 output.names 中。

>>> x = torch.randn(1, 3, 3, 3, names=('N', 'C', 'H', 'W'))
>>> x.squeeze('N').names
('C', 'H', 'W')

>>> x = torch.randn(3, 3, 3, 3, names=('N', 'C', 'H', 'W'))
>>> x.sum(['N', 'C']).names
('H', 'W')

# Reduction ops with keepdim=True don't actually remove dimensions.
>>> x = torch.randn(3, 3, 3, 3, names=('N', 'C', 'H', 'W'))
>>> x.sum(['N', 'C'], keepdim=True).names
('N', 'C', 'H', 'W')

从输入中统一名称

所有二进制算术运算都遵循此规则。广播操作仍然会从右侧按位置进行广播，以保持与未命名张量的兼容性。要通过名称执行显式广播，请使用 Tensor.align_as()。

• 检查名称：所有名称必须从右开始位置匹配。即，在 tensor + other， match(tensor.names[i], other.names[i]) 对于 i 中的所有 (-min(tensor.dim(), other.dim()) + 1, -1] 必须为真。

• 检查名称：此外，所有命名维度必须从右侧对齐。在匹配过程中，如果我们匹配一个命名维度 A 与一个未命名维度 None，那么 A 不得出现在具有未命名维度的张量中。

• 传播名称：将两个张量右侧的名称对统一，以生成输出名称。

例如，

# tensor: Tensor[   N, None]
# other:  Tensor[None,    C]
>>> tensor = torch.randn(3, 3, names=('N', None))
>>> other = torch.randn(3, 3, names=(None, 'C'))
>>> (tensor + other).names
('N', 'C')

检查名称：

• match(tensor.names[-1], other.names[-1]) 是 True

• match(tensor.names[-2], tensor.names[-2]) 是 True

• 因为我们匹配了 None 在 tensor 中与 'C'， 检查以确保 'C' 不存在于 tensor（它不存在）。

• 请检查以确保 'N' 不存在于 other 中（它确实不存在）。

最后，输出名称通过 [unify('N', None), unify(None, 'C')] = ['N', 'C'] 计算得出

更多示例：

# Dimensions don't match from the right:
# tensor: Tensor[N, C]
# other:  Tensor[   N]
>>> tensor = torch.randn(3, 3, names=('N', 'C'))
>>> other = torch.randn(3, names=('N',))
>>> (tensor + other).names
RuntimeError: Error when attempting to broadcast dims ['N', 'C'] and dims
['N']: dim 'C' and dim 'N' are at the same position from the right but do
not match.

# Dimensions aren't aligned when matching tensor.names[-1] and other.names[-1]:
# tensor: Tensor[N, None]
# other:  Tensor[      N]
>>> tensor = torch.randn(3, 3, names=('N', None))
>>> other = torch.randn(3, names=('N',))
>>> (tensor + other).names
RuntimeError: Misaligned dims when attempting to broadcast dims ['N'] and
dims ['N', None]: dim 'N' appears in a different position from the right
across both lists.

注意

在前面的两个示例中，可以通过名称对齐张量，然后执行加法操作。使用 Tensor.align_as() 按名称对齐张量，或使用 Tensor.align_to() 将张量对齐到自定义维度顺序。

对维度进行置换

某些操作，如 Tensor.t()，会置换维度的顺序。维度名称 会附加到各个维度上，因此它们也会被置换。

如果操作符接收位置索引 dim，它也可以接收一个维度名为 dim。

• 检查名称：如果将 dim 作为名称传递，请检查它是否存在于张量中。

• 传播名称：以与被置换的维度相同的方式置换维度名称。

>>> x = torch.randn(3, 3, names=('N', 'C'))
>>> x.transpose('N', 'C').names
('C', 'N')

移除维度

矩阵乘法函数遵循这个变体。我们先来了解 torch.mm()，然后推广该规则到批量矩阵乘法的情况。

对于 torch.mm(tensor, other):

• 检查名称：None

• 传播名称：结果名称是 (tensor.names[-2], other.names[-1])。

>>> x = torch.randn(3, 3, names=('N', 'D'))
>>> y = torch.randn(3, 3, names=('in', 'out'))
>>> x.mm(y).names
('N', 'out')

本质上，矩阵乘法在两个维度上执行点积，从而将它们折叠。当两个张量进行矩阵相乘时，被收缩的维度会消失，并不会出现在输出张量中。

torch.mv(), torch.dot() 的工作方式类似：名称推断不会检查输入名称，并删除涉及点积的维度：

>>> x = torch.randn(3, 3, names=('N', 'D'))
>>> y = torch.randn(3, names=('something',))
>>> x.mv(y).names
('N',)

现在，让我们来看一下 torch.matmul(tensor, other)。假设 tensor.dim() >= 2 和 other.dim() >= 2。

• 检查名称：检查输入的批次维度是否对齐且可广播。 请参阅统一输入的名称以了解输入对齐的含义。

• 传播名称：通过统一批量维度并删除收缩维度来获得结果名称： unify(tensor.names[:-2], other.names[:-2]) + (tensor.names[-2], other.names[-1])。

Examples:

# Batch matrix multiply of matrices Tensor['C', 'D'] and Tensor['E', 'F'].
# 'A', 'B' are batch dimensions.
>>> x = torch.randn(3, 3, 3, 3, names=('A', 'B', 'C', 'D'))
>>> y = torch.randn(3, 3, 3, names=('B', 'E', 'F'))
>>> torch.matmul(x, y).names
('A', 'B', 'C', 'F')

最后，许多矩阵乘法函数都有融合的add版本。例如，addmm()和addmv()。这些被视为组合名称推断，例如 mm() 和 add() 的名称推断。

工厂函数

工厂函数现在接受一个新的 names 参数，该参数将每个维度与一个名称相关联。

>>> torch.zeros(2, 3, names=('N', 'C'))
tensor([[0., 0., 0.],
        [0., 0., 0.]], names=('N', 'C'))

out 函数和原地操作变体

将张量指定为out=张量时，具有以下行为：

• 如果它没有命名维度，则从该操作计算出的名称会传播到它。

• 如果它具有任何命名维度，则从操作中计算出的名称必须与现有名称完全相等。否则，操作将报错。

所有原地方法都会修改输入，使其名称等于通过名称推断计算出的名称。例如：

>>> x = torch.randn(3, 3)
>>> y = torch.randn(3, 3, names=('N', 'C'))
>>> x.names
(None, None)

>>> x += y
>>> x.names
('N', 'C')