Tensor Attributes (original) (raw)

Created On: Apr 21, 2018 | Last Updated On: Jun 27, 2025

Each torch.Tensor has a torch.dtype, torch.device, and torch.layout.

torch.dtype#

class torch.dtype#

A torch.dtype is an object that represents the data type of atorch.Tensor. PyTorch has several different data types:

Floating point dtypes

Integer dtypes

shell(1,2,3,4,5,6,7,8,9)

a shell dtype a specialized dtype with limited op and backend support. Specifically, ops that support tensor creation (torch.empty, torch.fill, torch.zeros) and operations which do not peek inside the data elements (torch.cat, torch.view, torch.reshape) are supported. Ops that peek inside the data elements such as casting, matrix multiplication, nan/inf checks are supported only on a case by case basis, depending on maturity and presence of hardware accelerated kernels and established use cases.

1(1,2,3,4,5)

The “fn”, “fnu” and “fnuz” dtype suffixes mean: “f” - finite value encodings only, no infinity; “n” - nan value encodings differ from the IEEE spec; “uz” - “unsigned zero” only, i.e. no negative zero encoding

2(1,2,3)

Unsigned types asides from uint8 are currently planned to only have limited support in eager mode (they primarily exist to assist usage with torch.compile); if you need eager support and the extra range is not needed, we recommend using their signed variants instead. Seepytorch/pytorch#58734 for more details.

Note: legacy constructors such as torch.*.FloatTensor, torch.*.DoubleTensor, torch.*.HalfTensor,torch.*.BFloat16Tensor, torch.*.ByteTensor, torch.*.CharTensor, torch.*.ShortTensor, torch.*.IntTensor,torch.*.LongTensor, torch.*.BoolTensor only remain for backwards compatibility and should no longer be used.

To find out if a torch.dtype is a floating point data type, the property is_floating_pointcan be used, which returns True if the data type is a floating point data type.

To find out if a torch.dtype is a complex data type, the property is_complexcan be used, which returns True if the data type is a complex data type.

When the dtypes of inputs to an arithmetic operation (add, sub, div, mul) differ, we promote by finding the minimum dtype that satisfies the following rules:

A floating point scalar operand has dtype torch.get_default_dtype() and an integral non-boolean scalar operand has dtype torch.int64. Unlike numpy, we do not inspect values when determining the minimum dtypes of an operand. Complex types are not yet supported. Promotion for shell dtypes is not defined.

Promotion Examples:

float_tensor = torch.ones(1, dtype=torch.float) double_tensor = torch.ones(1, dtype=torch.double) complex_float_tensor = torch.ones(1, dtype=torch.complex64) complex_double_tensor = torch.ones(1, dtype=torch.complex128) int_tensor = torch.ones(1, dtype=torch.int) long_tensor = torch.ones(1, dtype=torch.long) uint_tensor = torch.ones(1, dtype=torch.uint8) bool_tensor = torch.ones(1, dtype=torch.bool)

zero-dim tensors

long_zerodim = torch.tensor(1, dtype=torch.long) int_zerodim = torch.tensor(1, dtype=torch.int)

torch.add(5, 5).dtype torch.int64

5 is an int64, but does not have higher category than int_tensor so is not considered.

(int_tensor + 5).dtype torch.int32 (int_tensor + long_zerodim).dtype torch.int32 (long_tensor + int_tensor).dtype torch.int64 (bool_tensor + long_tensor).dtype torch.int64 (bool_tensor + uint_tensor).dtype torch.uint8 (float_tensor + double_tensor).dtype torch.float64 (complex_float_tensor + complex_double_tensor).dtype torch.complex128 (bool_tensor + int_tensor).dtype torch.int32

Since long is a different kind than float, result dtype only needs to be large enough

to hold the float.

torch.add(long_tensor, float_tensor).dtype torch.float32

When the output tensor of an arithmetic operation is specified, we allow casting to its dtype except that:

Casting Examples:

allowed:

float_tensor *= float_tensor float_tensor *= int_tensor float_tensor *= uint_tensor float_tensor *= bool_tensor float_tensor *= double_tensor int_tensor *= long_tensor int_tensor *= uint_tensor uint_tensor *= int_tensor

disallowed (RuntimeError: result type can't be cast to the desired output type):

int_tensor *= float_tensor bool_tensor *= int_tensor bool_tensor *= uint_tensor float_tensor *= complex_float_tensor

torch.device#

class torch.device#

A torch.device is an object representing the device on which a torch.Tensor is or will be allocated.

The torch.device contains a device type (most commonly “cpu” or “cuda”, but also potentially “mps”, “xpu”,“xla” or “meta”) and optional device ordinal for the device type. If the device ordinal is not present, this object will always represent the current device for the device type, even after torch.cuda.set_device() is called; e.g., a torch.Tensor constructed with device 'cuda' is equivalent to 'cuda:X' where X is the result of torch.cuda.current_device().

A torch.Tensor’s device can be accessed via the Tensor.device property.

A torch.device can be constructed using:

Via a device string:

torch.device('cuda:0') device(type='cuda', index=0)

torch.device('cpu') device(type='cpu')

torch.device('mps') device(type='mps')

torch.device('cuda') # implicit index is the "current device index" device(type='cuda')

Via a device type and a device ordinal:

torch.device('cuda', 0) device(type='cuda', index=0)

torch.device('mps', 0) device(type='mps', index=0)

torch.device('cpu', 0) device(type='cpu', index=0)

Via a device ordinal:

Note

This method will raise a RuntimeError if no accelerator is currently detected.

torch.device(0) # the current accelerator is cuda device(type='cuda', index=0)

torch.device(1) # the current accelerator is xpu device(type='xpu', index=1)

torch.device(0) # no current accelerator detected Traceback (most recent call last): File "", line 1, in RuntimeError: Cannot access accelerator device when none is available.

The device object can also be used as a context manager to change the default device tensors are allocated on:

with torch.device('cuda:1'): ... r = torch.randn(2, 3) r.device device(type='cuda', index=1)

This context manager has no effect if a factory function is passed an explicit, non-None device argument. To globally change the default device, see alsotorch.set_default_device().

Warning

This function imposes a slight performance cost on every Python call to the torch API (not just factory functions). If this is causing problems for you, please comment onpytorch/pytorch#92701

Note

The torch.device argument in functions can generally be substituted with a string. This allows for fast prototyping of code.

Example of a function that takes in a torch.device

cuda1 = torch.device('cuda:1') torch.randn((2,3), device=cuda1)

You can substitute the torch.device with a string

torch.randn((2,3), device='cuda:1')

Note

Methods which take a device will generally accept a (properly formatted) string or an integer device ordinal, i.e. the following are all equivalent:

torch.randn((2,3), device=torch.device('cuda:1')) torch.randn((2,3), device='cuda:1') torch.randn((2,3), device=1) # equivalent to 'cuda:1' if the current accelerator is cuda

Note

Tensors are never moved automatically between devices and require an explicit call from the user. Scalar Tensors (with tensor.dim()==0) are the only exception to this rule and they are automatically transferred from CPU to GPU when needed as this operation can be done “for free”. Example:

two scalars

torch.ones(()) + torch.ones(()).cuda() # OK, scalar auto-transferred from CPU to GPU torch.ones(()).cuda() + torch.ones(()) # OK, scalar auto-transferred from CPU to GPU

one scalar (CPU), one vector (GPU)

torch.ones(()) + torch.ones(1).cuda() # OK, scalar auto-transferred from CPU to GPU torch.ones(1).cuda() + torch.ones(()) # OK, scalar auto-transferred from CPU to GPU

one scalar (GPU), one vector (CPU)

torch.ones(()).cuda() + torch.ones(1) # Fail, scalar not auto-transferred from GPU to CPU and non-scalar not auto-transferred from CPU to GPU torch.ones(1) + torch.ones(()).cuda() # Fail, scalar not auto-transferred from GPU to CPU and non-scalar not auto-transferred from CPU to GPU

torch.layout#

class torch.layout#

Warning

The torch.layout class is in beta and subject to change.

A torch.layout is an object that represents the memory layout of atorch.Tensor. Currently, we support torch.strided (dense Tensors) and have beta support for torch.sparse_coo (sparse COO Tensors).

torch.strided represents dense Tensors and is the memory layout that is most commonly used. Each strided tensor has an associatedtorch.Storage, which holds its data. These tensors provide multi-dimensional, stridedview of a storage. Strides are a list of integers: the k-th stride represents the jump in the memory necessary to go from one element to the next one in the k-th dimension of the Tensor. This concept makes it possible to perform many tensor operations efficiently.

Example:

x = torch.tensor([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]]) x.stride() (5, 1)

x.t().stride() (1, 5)

For more information on torch.sparse_coo tensors, see torch.sparse.

torch.memory_format#

class torch.memory_format#

A torch.memory_format is an object representing the memory format on which a torch.Tensor is or will be allocated.

Possible values are: