張量屬性

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

torch.dtype

類別 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。

當算術運算（add、sub、div、mul）的輸入的 dtypes 不同時，我們會透過尋找滿足以下規則的最小 dtype 來進行提升

• 如果純量運算元的類型高於張量運算元（其中複數 > 浮點數 > 整數 > 布林值），我們會提升到大小足以容納該類別所有純量運算元的類型。

• 如果零維張量運算元的類別高於維度運算元，我們會提升到大小和類別足以容納該類別所有零維張量運算元的類型。

• 如果沒有較高類別的零維運算元，我們會提升到大小和類別足以容納所有維度運算元的類型。

浮點數純量運算元的 dtype 為 torch.get_default_dtype()，而整數非布林值純量運算元的 dtype 為 torch.int64。與 numpy 不同，我們在判斷運算元的最小 dtypes 時不會檢查值。目前尚不支援量化和複數類型。

提升範例

>>> 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)
>>> double_tensor = torch.ones(1, dtype=torch.double)
>>> 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

當指定算術運算的輸出張量時，我們允許轉換為其 dtype，但以下情況除外

• 整數輸出張量不能接受浮點數張量。

• 布林值輸出張量不能接受非布林值張量。

• 非複數輸出張量不能接受複數張量

轉換範例

# 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

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() 的結果。

可以透過 Tensor.device 屬性訪問 torch.Tensor 的設備。

可以透過字串或透過字串和設備序號構造 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')

備註

出於遺 legacy 的原因，可以透過單個設備序號構造設備，該設備序號被視為 cuda 設備。這與 Tensor.get_device() 相匹配，後者返回 cuda 張量的序號，並且不支持 cpu 張量。

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

備註

採用設備的方法通常會接受（格式正確的）字串或（遺 legacy 的）整數設備序號，即以下所有內容都是等效的

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