张量属性 §

每个 torch.Tensor 都有一个 torch.dtype 、 torch.device 和 torch.layout 。

torch.dtype

class torch.dtype

torch.dtype 代表一个数据类型， torch.Tensor 的数据类型。PyTorch 有十二种不同的数据类型：

数据类型	dtype	旧构造函数
32 位浮点数	torch.float32 或 torch.float	torch.*.FloatTensor
64 位浮点数	torch.float64 或 torch.double	torch.*.DoubleTensor
64 位复数	torch.complex64 或 torch.cfloat
128 位复数	torch.complex128 或 torch.cdouble
16 位浮点数 [1]	torch.float16 或 torch.half	torch.*.HalfTensor
16 位浮点数 [2]	torch.bfloat16	torch.*.BFloat16Tensor
8 位无符号整数	torch.uint8	torch.*.ByteTensor
8 位有符号整数	torch.int8	torch.*.CharTensor
16 位有符号整数	torch.int16 或 torch.short	torch.*.ShortTensor
32 位有符号整数	torch.int32 或 torch.int	torch.*.IntTensor
64 位有符号整数	torch.int64 或 torch.long	torch.*.LongTensor
布尔值	torch.bool	torch.*.BoolTensor

[1]

有时被称为 binary16：使用 1 个符号位、5 个指数位和 10 个尾数位。当精度很重要时很有用。

[2]

有时被称为 Brain Floating Point：使用 1 个符号位、8 个指数位和 7 个尾数位。当范围很重要时很有用，因为它与 float32 具有相同数量的指数位。

要判断一个 torch.dtype 是否为浮点数据类型，可以使用属性 is_floating_point ，如果数据类型是浮点数据类型，则返回 True 。

要判断一个 torch.dtype 是否为复杂数据类型，可以使用属性 is_complex ，如果数据类型是复杂数据类型，则返回 True 。

当算术运算（加、减、除、乘）的输入数据类型（dtypes）不同时，我们会通过找到满足以下规则的最小数据类型来进行提升：

• 如果标量操作数的类型高于张量操作数的类型类别（复数 > 浮点 > 整数 > 布尔），我们会提升到足够容纳该类别所有标量操作数的大小类型。

• 如果零维张量操作数具有比维数操作数更高的类别，我们将提升到足够大小和类别的类型，以容纳该类别中所有零维张量操作数。

• 如果没有更高类别的零维操作数，我们将提升到足够大小和类别的类型，以容纳所有维数操作数。

浮点标量操作数的 dtype 为 torch.get_default_dtype()，而整型非布尔标量操作数的 dtype 为 torch.int64。与 numpy 不同，我们在确定操作数的最小 dtype 时不会检查值。量化类型和复数类型尚不支持。

提升示例：

>>> 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

当指定算术运算的输出张量时，我们允许将其转换为相应的数据类型，但有以下限制：

• 整数类型的输出张量不能接受浮点数类型的张量。

• 布尔类型的输出张量不能接受非布尔类型的张量。

• 非复数类型的输出张量不能接受复数类型的张量。

模拟示例：

# 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

类 torch.device ¶

torch.device 代表一个对象，表示 torch.Tensor 将被分配到的设备。

“ torch.device ” 包含设备类型（最常见的是“cpu”或“cuda”，但也可能是“mps”、“xpu”、“xla”或“meta”），以及可选的设备序号。如果设备序号不存在，此对象将始终代表该设备类型的当前设备，即使在调用 torch.cuda.set_device() 之后也是如此；例如，使用设备 'cuda' 构造的 torch.Tensor 等同于 'cuda:X' ，其中 X 是 torch.cuda.current_device() 的结果。

一个 torch.Tensor 的设备可以通过 Tensor.device 属性访问。

一个 torch.device 可以通过字符串或通过字符串和设备序号来构造。

通过字符串：

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

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

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

>>> torch.device('cuda')  # current cuda device
device(type='cuda')

通过字符串和设备序号：

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

设备对象也可以用作上下文管理器来更改默认设备张量分配到的设备：

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

如果将显式非 None 的设备参数传递给工厂函数，则此上下文管理器将没有效果。要全局更改默认设备，请参阅 torch.set_default_device() 。

警告

此函数会对每次调用 torch API 的 Python 调用（不仅仅是工厂函数）产生轻微的性能开销。如果这给您带来了问题，请评论 https://github.com/pytorch/pytorch/issues/92701

注意

函数中的 torch.device 参数通常可以用字符串替换，这允许快速进行代码原型设计。

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

注意

由于历史原因，可以通过单个设备序号来构造设备，该序号被视为当前加速器类型。这与 Tensor.get_device() 相匹配，它返回设备张量的序号，但不支持 CPU 张量。

>>> torch.device(1)
device(type='cuda', index=1)

注意

接受设备的函数通常可以接受（格式正确）的字符串或（旧式）整数设备序号，即以下都是等效的：

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

注意

张量永远不会自动在设备之间移动，需要用户显式调用。标量张量（tensor.dim()==0）是此规则的唯一例外，当需要时它们会自动从 CPU 转移到 GPU，因为这个操作可以“免费”完成。例如：

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

警告

torch.layout 类处于测试阶段，可能会发生变化。

torch.layout 是一个表示 torch.Tensor 内存布局的对象。目前，我们支持 torch.strided （密集张量）并提供了对 torch.sparse_coo （稀疏 COO 张量）的测试支持。

torch.strided 代表密集张量，是最常用的内存布局。每个具有步长的张量都有一个关联的 torch.Storage ，它存储其数据。这些张量提供了存储的多维步长视图。步长是一个整数列表：第 k 个步长表示在张量的第 k 维中从一个元素跳到下一个元素所需的内存跳跃。这个概念使得许多张量操作可以高效执行。

示例：

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

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

关于 torch.sparse_coo 张量的更多信息，请参阅 torch.sparse。

torch.memory_format

class torch.memory_format

torch.memory_format 代表一个对象，用于表示在哪个内存格式上分配或将要分配 torch.Tensor 。

可能的值有：

• torch.contiguous_format ：张量将在密集的非重叠内存中分配。步长由递减的值表示。

• torch.channels_last ：张量将在密集的非重叠内存中分配。步长由 strides[0] > strides[2] > strides[3] > strides[1] == 1 即 NHWC 顺序的值表示。

• torch.channels_last_3d 张量将在密集的非重叠内存中分配。 strides[0] > strides[2] > strides[3] > strides[4] > strides[1] == 1 表示的步长遵循 NDHWC 顺序。

• torch.preserve_format 用于函数如 clone 以保留输入张量的内存格式。如果输入张量在密集的非重叠内存中分配，则输出张量的步长将复制自输入。否则输出步长将遵循 torch.contiguous_format