Warning

The named tensor API is experimental and subject to change.

Keeps input names#

All pointwise unary functions follow this rule as well as some other unary functions.

• Check names: None

• Propagate names: input tensor’s names are propagated to the output.

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

Removes dimensions#

All reduction ops likesum() remove dimensions by reducingover the desired dimensions. Other operations likeselect() andsqueeze() remove dimensions.

Wherever one can pass an integer dimension index to an operator, one can also passa dimension name. Functions that take lists of dimension indices can also take in alist of dimension names.

• Check names: Ifdim ordims is passed in as a list of names,check that those names exist inself.

• Propagate names: If the dimensions of the input tensor specified bydimordims are not present in the output tensor, then the corresponding namesof those dimensions do not appear inoutput.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')

Unifies names from inputs#

All binary arithmetic ops follow this rule. Operations that broadcast stillbroadcast positionally from the right to preserve compatibility with unnamedtensors. To perform explicit broadcasting by names, useTensor.align_as().

• Check names: All names must match positionally from the right. i.e., intensor+other,match(tensor.names[i],other.names[i]) must be true for alli in(-min(tensor.dim(),other.dim())+1,-1].

• Check names: Furthermore, all named dimensions must be aligned from the right.During matching, if we match a named dimensionA with an unnamed dimensionNone, thenA must not appear in the tensor with the unnamed dimension.

• Propagate names: unify pairs of names from the right from both tensors toproduce output names.

For example,

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

Check names:

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

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

• Because we matchedNone intensor with'C',check to make sure'C' doesn’t exist intensor (it does not).

• Check to make sure'N' doesn’t exists inother (it does not).

Finally, the output names are computed with[unify('N',None),unify(None,'C')]=['N','C']

More examples:

# 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).namesRuntimeError:Errorwhenattemptingtobroadcastdims['N','C']anddims['N']:dim'C'anddim'N'areatthesamepositionfromtherightbutdonotmatch.# 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).namesRuntimeError:Misaligneddimswhenattemptingtobroadcastdims['N']anddims['N',None]:dim'N'appearsinadifferentpositionfromtherightacrossbothlists.

Permutes dimensions#

Some operations, likeTensor.t(), permute the order of dimensions. Dimension namesare attached to individual dimensions so they get permuted as well.

If the operator takes in positional indexdim, it is also able to take a dimensionname asdim.

• Check names: Ifdim is passed as a name, check that it exists in the tensor.

• Propagate names: Permute dimension names in the same way as the dimensions that arebeing permuted.

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

Contracts away dims#

Matrix multiply functions follow some variant of this. Let’s go throughtorch.mm() first and then generalize the rule for batch matrix multiplication.

Fortorch.mm(tensor,other):

• Check names: None

• Propagate names: result names are(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')

Inherently, a matrix multiplication performs a dot product over two dimensions,collapsing them. When two tensors are matrix-multiplied, the contracted dimensionsdisappear and do not show up in the output tensor.

torch.mv(),torch.dot() work in a similar way: name inference does notcheck input names and removes the dimensions that are involved in the dot product:

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

Now, let’s take a look attorch.matmul(tensor,other). Assume thattensor.dim()>=2andother.dim()>=2.

• Check names: Check that the batch dimensions of the inputs are aligned and broadcastable.SeeUnifies names from inputs for what it means for the inputs to be aligned.

• Propagate names: result names are obtained by unifying the batch dimensions and removingthe contracted dimensions: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')

Finally, there are fusedadd versions of many matmul functions. i.e.,addmm()andaddmv(). These are treated as composing name inference for i.e.mm() andname inference foradd().

Factory functions#

Factory functions now take a newnames argument that associates a namewith each dimension.

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

out function and in-place variants#

A tensor specified as anout= tensor has the following behavior:

• If it has no named dimensions, then the names computed from the operationget propagated to it.

• If it has any named dimensions, then the names computed from the operationmust be exactly equal to the existing names. Otherwise, the operation errors.

All in-place methods modify inputs to have names equal to the computed namesfrom name inference. For example:

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

• torchao
• torchrec
• torchft
• TorchCodec
• torchvision
• ExecuTorch
• PyTorch on XLA Devices