命名张量运算符覆盖范围¶

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

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

使用名称提供额外的自动运行时正确性检查
将名称从输入张量传播到输出张量

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

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

警告

命名张量 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.itemsize`	无
`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.nbytes`	无
`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.register_post_accumulate_grad_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.softmax()`，`torch.softmax()`	保留输入名称
`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()`	工厂函数

保留输入名称¶

所有逐元素一元函数以及其他一些一元函数都遵循此规则。

检查名称：无
传播名称：输入张量的名称会传播到输出。

>>> 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
因为我们将 tensor 中的 None 与 '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)

检查名称：无
传播名称：结果名称为 (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])。

示例

# 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')

最后，许多 matmul 函数都有融合的 add 版本。即，addmm() 和 addmv()。这些被视为将 i.e. 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')