torch.Storage

API нетипизированного хранилища

torch.UntypedStorage — это непрерывный одномерный массив элементов. Его длина равна количеству байтов тензора. Хранилище служит базовым контейнером данных для тензоров. Как правило, тензор, созданный в PyTorch с помощью обычных конструкторов, таких как zeros(), zeros_like() или new_zeros(), будет иметь взаимно-однозначное соответствие между хранилищем тензора и самим тензором.

Однако одно хранилище может использоваться несколькими тензорами. Например, любое представление тензора (полученное с помощью view() или некоторых, но не всех видов индексирования, таких как целые числа и срезы) будет указывать на то же базовое хранилище, что и исходный тензор. При сериализации и десериализации тензоров, использующих общее хранилище, эта связь сохраняется, и тензоры продолжают указывать на одно и то же хранилище. Примечательно, что десериализация нескольких тензоров, указывающих на одно хранилище, может выполняться быстрее, чем десериализация нескольких независимых тензоров.

Доступ к хранилищу тензора можно получить с помощью метода untyped_storage(). Он возвращает объект типа torch.UntypedStorage. К счастью, у хранилищ есть уникальный идентификатор, доступный через метод torch.UntypedStorage.data_ptr(). В обычных условиях два тензора с одним и тем же хранилищем данных будут иметь одинаковый data_ptr хранилища. Однако сами тензоры могут указывать на два отдельных хранилища: одно для атрибута данных, а другое — для атрибута grad. Каждому из них потребуется собственный data_ptr(). В общем случае нет гарантии, что torch.Tensor.data_ptr() и torch.UntypedStorage.data_ptr() совпадают; не следует исходить из того, что это так.

Нетипизированные хранилища в некоторой степени независимы от построенных на них тензоров. На практике это означает, что тензоры с разными типами данных или формами могут указывать на одно и то же хранилище. Это также означает, что хранилище тензора можно изменить, как показано в следующем примере:

>>> t = torch.ones(3)
>>> s0 = t.untyped_storage()
>>> s0
 0
 0
 128
 63
 0
 0
 128
 63
 0
 0
 128
 63
[torch.storage.UntypedStorage(device=cpu) of size 12]
>>> s1 = s0.clone()
>>> s1.fill_(0)
 0
 0
 0
 0
 0
 0
 0
 0
 0
 0
 0
 0
[torch.storage.UntypedStorage(device=cpu) of size 12]
>>> # Fill the tensor with a zeroed storage
>>> t.set_(s1, storage_offset=t.storage_offset(), stride=t.stride(), size=t.size())
tensor([0., 0., 0.])

Помимо data_ptr, у нетипизированного хранилища есть и другие атрибуты, например filename (если хранилище указывает на файл на диске), device или is_cuda для проверки устройства. Хранилище также можно изменять на месте или создавать его копии с помощью таких методов, как copy_, fill_ или pin_memory. Дополнительные сведения см. в справочнике API ниже. Помните, что изменение хранилищ — это низкоуровневый API, связанный с рисками! Большинство таких API также существуют на уровне тензоров: если они доступны, им следует отдавать предпочтение перед соответствующими API хранилищ.

Особые случаи

Мы упоминали, что тензор с атрибутом grad, значение которого не равно None, фактически содержит две части данных. В этом случае untyped_storage() вернёт хранилище атрибута data, а хранилище градиента можно получить через tensor.grad.untyped_storage().

>>> t = torch.zeros(3, requires_grad=True)
>>> t.sum().backward()
>>> assert list(t.untyped_storage()) == [0] * 12  # the storage of the tensor is just 0s
>>> assert list(t.grad.untyped_storage()) != [0] * 12  # the storage of the gradient isn't

Существуют также особые случаи, когда у тензоров нет обычного хранилища или хранилища нет вовсе:

• Тензоры на устройстве "meta": тензоры на устройстве "meta" используются для вывода формы и не содержат фактических данных.
• Фиктивные тензоры: другой внутренний инструмент компилятора PyTorch — FakeTensor, основанный на аналогичной идее.

Подклассы тензоров и объекты, подобные тензорам, также могут демонстрировать необычное поведение. В общем случае мы не ожидаем, что многим сценариям использования потребуется работа на уровне Storage!

class torch.UntypedStorage(*args, **kwargs) [исходный код]

bfloat16() [исходный код]

Преобразует это хранилище к типу bfloat16.

bool() [исходный код]

Преобразует это хранилище к типу bool.

byte() [исходный код]

Преобразует это хранилище к типу byte.

byteswap(dtype) [исходный код]

Меняет порядок байтов в базовых данных.

char() [исходный код]

Преобразует это хранилище к типу char.

clone() [исходный код]

Возвращает копию этого хранилища.

complex_double() [исходный код]

Преобразует это хранилище к типу complex double.

complex_float() [исходный код]

Преобразует это хранилище к типу complex float.

copy_()

cpu() [исходный код]

Возвращает копию этого хранилища в памяти CPU, если оно ещё не находится в памяти CPU.

cuda(device=None, non_blocking=False) [исходный код]

Возвращает копию этого объекта в памяти CUDA.

Если этот объект уже находится в памяти CUDA на нужном устройстве, копирование не выполняется и возвращается исходный объект.

Параметры:

• device (int) – идентификатор целевого GPU. По умолчанию используется текущее устройство.
• non_blocking (bool) – Если True и источник находится в закреплённой памяти, копирование будет выполняться асинхронно относительно хоста. В противном случае аргумент не оказывает влияния.

Тип возвращаемого значения:

_StorageBase | TypedStorage

data_ptr()

device: device

double() [исходный код]

Преобразует это хранилище к типу double.

element_size()

property filename: str | None

Возвращает имя файла, связанного с этим хранилищем.

Имя файла будет строкой, если хранилище находится на CPU и было создано с помощью from_file() с shared в качестве True. В противном случае значение этого атрибута — None.

fill_()

float() [исходный код]

Преобразует это хранилище к типу float.

float8_e4m3fn() [исходный код]

Преобразует это хранилище к типу float8_e4m3fn

float8_e4m3fnuz() [исходный код]

Преобразует это хранилище к типу float8_e4m3fnuz

float8_e5m2() [исходный код]

Преобразует это хранилище к типу float8_e5m2

float8_e5m2fnuz() [исходный код]

Преобразует это хранилище к типу float8_e5m2fnuz

static from_buffer()

static from_file(filename, shared=False, nbytes=0) → Storage

Создаёт хранилище CPU, основанное на файле, отображённом в память.

Если shared равно True, память является общей для всех процессов. Все изменения записываются в файл. Если shared равно False, изменения в хранилище не влияют на файл.

nbytes — это количество байтов хранилища. Если shared равно False, файл должен содержать не менее nbytes байтов. Если shared равно True, при необходимости файл будет создан. (Обратите внимание, что для UntypedStorage этот аргумент отличается от аргумента TypedStorage.from_file.)

Параметры:

• filename (str) – имя файла для отображения
• shared (bool) – использовать ли общую память (передаётся ли MAP_SHARED или MAP_PRIVATE в нижележащий вызов mmap(2))
• nbytes (int) – количество байтов хранилища

get_device() [исходный код]

Тип возвращаемого значения:

int

half() [исходный код]

Преобразует это хранилище к типу half.

hpu(device=None, non_blocking=False) [исходный код]

Возвращает копию этого объекта в памяти HPU.

Если этот объект уже находится в памяти HPU на нужном устройстве, копирование не выполняется и возвращается исходный объект.

Параметры:

• device (int) – идентификатор целевого HPU. По умолчанию используется текущее устройство.
• non_blocking (bool) – Если True и источник находится в закреплённой памяти, копирование будет выполняться асинхронно относительно хоста. В противном случае аргумент не оказывает влияния.

Тип возвращаемого значения:

_StorageBase | TypedStorage

int() [исходный код]

Преобразует это хранилище к типу int.

property is_cuda

property is_hpu

is_pinned(device=None) [исходный код]

Определяет, закреплено ли уже хранилище CPU в памяти устройства.

Параметры:

device (str или torch.device) – устройство, в памяти которого следует закрепить данные (по умолчанию: None). Использование этого аргумента не рекомендуется; он подлежит устареванию.

Возвращает:

Логическое значение.

is_shared()

is_sparse: bool = False

is_sparse_csr: bool = False

long() [исходный код]

Преобразует это хранилище к типу long.

mps() [исходный код]

Возвращает копию этого хранилища в памяти MPS, если оно ещё не находится в памяти MPS.

nbytes()

new()

pin_memory(device=None) [исходный код]

Копирует хранилище CPU в закреплённую память, если оно ещё не закреплено.

Параметры:

device (str или torch.device) – устройство, в памяти которого следует закрепить данные (по умолчанию: None). Использование этого аргумента не рекомендуется; он подлежит устареванию.

Возвращает:

Хранилище CPU в закреплённой памяти.

resizable()

resize_()

share_memory_(*args, **kwargs) [исходный код]

Перемещает хранилище в разделяемую память.

Операция ничего не делает для хранилищ, уже находящихся в разделяемой памяти, а также для хранилищ CUDA, которые не требуется перемещать для совместного использования между процессами. Хранилища в разделяемой памяти нельзя изменять по размеру.

Обратите внимание: для предотвращения таких проблем, как эта, эту функцию можно безопасно вызывать из нескольких потоков для одного объекта. Однако вызов любой другой функции для self без надлежащей синхронизации НЕ является потокобезопасным. Подробнее см. в разделе Рекомендации по использованию многопроцессности.

Примечание

Когда все ссылки на хранилище в разделяемой памяти удаляются, связанный с ним объект разделяемой памяти также удаляется. В PyTorch предусмотрен специальный процесс очистки, гарантирующий это даже в случае неожиданного завершения текущего процесса.

Следует учитывать разницу между share_memory_() и from_file() с shared = True

1. share_memory_ использует shm_open(3) для создания объекта разделяемой памяти POSIX, тогда как from_file() использует open(2) для открытия имени файла, переданного пользователем.
2. Оба метода используют вызов mmap(2) с MAP_SHARED для отображения файла/объекта в текущее виртуальное адресное пространство.
3. share_memory_ вызывает shm_unlink(3) для объекта после его отображения, чтобы гарантировать освобождение объекта разделяемой памяти, когда ни один процесс не держит его открытым. torch.from_file(shared=True) не удаляет файл. Этот файл является постоянным и будет существовать, пока пользователь его не удалит.

Возвращает:

self

short() [исходный код]

Преобразует это хранилище к типу short.

size() [исходный код]

Тип возвращаемого значения:

int

to(*, device, non_blocking=False) [исходный код]

tolist() [исходный код]

Возвращает список, содержащий элементы этого хранилища.

type(dtype=None, non_blocking=False) [исходный код]

Тип возвращаемого значения:

_StorageBase | TypedStorage

untyped() [исходный код]

Устаревшее типизированное хранилище

torch.Storage — это псевдоним класса хранилища, соответствующего типу данных по умолчанию (torch.get_default_dtype()). Например, если тип данных по умолчанию — torch.float, то torch.Storage соответствует torch.FloatStorage.

Классы torch.<type>Storage и torch.cuda.<type>Storage, такие как torch.FloatStorage, torch.IntStorage и т. д., фактически никогда не создаются как экземпляры. Вызов их конструкторов создаёт объект torch.TypedStorage с соответствующими torch.dtype и torch.device. Классы torch.<type>Storage имеют все те же методы класса, что и torch.TypedStorage.

torch.TypedStorage — это непрерывный одномерный массив элементов определённого torch.dtype. Ему можно задать любой torch.dtype, и внутренние данные будут интерпретироваться соответствующим образом. torch.TypedStorage содержит torch.UntypedStorage, в котором данные хранятся в виде нетипизированного массива байтов.

Каждый тензор torch.Tensor со страйдами содержит torch.TypedStorage, в котором хранятся все данные, просматриваемые тензором torch.Tensor.

class torch.TypedStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

bfloat16() [исходный код]

Преобразует это хранилище к типу bfloat16.

bool() [исходный код]

Преобразует это хранилище к типу bool.

byte() [исходный код]

Преобразует это хранилище к типу byte.

char() [исходный код]

Преобразует это хранилище к типу char.

clone() [исходный код]

Возвращает копию этого хранилища.

complex_double() [исходный код]

Преобразует это хранилище к типу complex double.

complex_float() [исходный код]

Преобразует это хранилище к типу complex float.

copy_(source, non_blocking=None) [исходный код]

cpu() [исходный код]

Возвращает копию этого хранилища на CPU, если оно ещё не находится в памяти CPU.

cuda(device=None, non_blocking=False) [исходный код]

Возвращает копию этого объекта в памяти CUDA.

Если этот объект уже находится в памяти CUDA на нужном устройстве, копирование не выполняется и возвращается исходный объект.

Параметры:

• device (int) – Идентификатор целевого GPU. По умолчанию используется текущее устройство.
• non_blocking (bool) – Если True и источник находится в закреплённой памяти, копирование будет выполняться асинхронно относительно хоста. В противном случае аргумент не влияет на результат.

Тип возвращаемого значения:

Self

data_ptr() [исходный код]

property device

double() [исходный код]

Преобразует это хранилище к типу double.

dtype: dtype

element_size() [исходный код]

property filename: str | None

Возвращает имя файла, связанного с этим хранилищем, если оно было создано с помощью отображения файла в память, или None, если хранилище не было создано таким способом.

fill_(value) [исходный код]

float() [исходный код]

Преобразует это хранилище к типу float.

float8_e4m3fn() [исходный код]

Преобразует это хранилище к типу float8_e4m3fn

float8_e4m3fnuz() [исходный код]

Преобразует это хранилище к типу float8_e4m3fnuz

float8_e5m2() [исходный код]

Преобразует это хранилище к типу float8_e5m2

float8_e5m2fnuz() [исходный код]

Преобразует это хранилище к типу float8_e5m2fnuz

classmethod from_buffer(*args, **kwargs) [исходный код]

classmethod from_file(filename, shared=False, size=0) → Storage [исходный код]

Создаёт хранилище CPU, размещённое в файле, отображённом в память.

Если shared равно True, память совместно используется всеми процессами. Все изменения записываются в файл. Если shared равно False, изменения в хранилище не влияют на файл.

size — количество элементов в хранилище. Если shared равно False, файл должен содержать не менее size * sizeof(Type) байт (Type — тип хранилища). Если shared равно True, файл будет создан при необходимости.

Параметры:

• filename (str) – имя файла для отображения
• shared (bool) – использовать ли общую память (передаётся ли MAP_SHARED или MAP_PRIVATE в системный вызов mmap(2))
• size (int) – количество элементов в хранилище

get_device() [исходный код]

Тип возвращаемого значения:

int

half() [исходный код]

Преобразует это хранилище к типу half.

hpu(device=None, non_blocking=False) [исходный код]

Возвращает копию этого объекта в памяти HPU.

Если этот объект уже находится в памяти HPU на нужном устройстве, копирование не выполняется и возвращается исходный объект.

Параметры:

• device (int) – Идентификатор целевого HPU. По умолчанию используется текущее устройство.
• non_blocking (bool) – Если True и источник находится в закреплённой памяти, копирование будет выполняться асинхронно относительно хоста. В противном случае аргумент не влияет на результат.

Тип возвращаемого значения:

Self

int() [исходный код]

Преобразует это хранилище к типу int.

property is_cuda

property is_hpu

is_pinned(device=None) [исходный код]

Определяет, закреплено ли уже типизированное хранилище CPU в памяти устройства.

Параметры:

device (str или torch.device) – Устройство, на котором следует закрепить память (по умолчанию: None). Использование этого аргумента не рекомендуется; он объявлен устаревшим.

Возвращает:

Логическое значение.

is_shared() [исходный код]

is_sparse: bool = False

long() [исходный код]

Преобразует это хранилище к типу long.

nbytes() [исходный код]

pickle_storage_type() [исходный код]

pin_memory(device=None) [исходный код]

Копирует типизированное хранилище CPU в закреплённую память, если оно ещё не закреплено.

Параметры:

device (str или torch.device) – Устройство, на котором следует закрепить память (по умолчанию: None). Использование этого аргумента не рекомендуется; он объявлен устаревшим.

Возвращает:

Закреплённое хранилище CPU.

resizable() [исходный код]

resize_(size) [исходный код]

share_memory_() [исходный код]

См. torch.UntypedStorage.share_memory_()

short() [исходный код]

Преобразует это хранилище к типу short.

size() [исходный код]

to(*, device, non_blocking=False) [исходный код]

Возвращает копию этого объекта в памяти устройства.

Если этот объект уже находится на нужном устройстве, копирование не выполняется и возвращается исходный объект.

Параметры:

• device (int) – Целевое устройство.
• non_blocking (bool) – Если True и источник находится в закреплённой памяти, копирование будет выполняться асинхронно относительно хоста. В противном случае аргумент не влияет на результат.

Тип возвращаемого значения:

Self

tolist() [исходный код]

Возвращает список, содержащий элементы этого хранилища.

type(dtype=None, non_blocking=False) [исходный код]

Возвращает тип, если dtype не задан; в противном случае преобразует этот объект к указанному типу.

Если объект уже имеет нужный тип, копирование не выполняется и возвращается исходный объект.

Параметры:

• dtype (type или строка) – Требуемый тип
• non_blocking (bool) – Если True, а источник находится в закреплённой памяти и целевое устройство — GPU, или наоборот, копирование выполняется асинхронно относительно хоста. В противном случае аргумент не влияет на результат.
• **kwargs – Для совместимости может содержать ключ async вместо аргумента non_blocking. Аргумент async объявлен устаревшим.

Тип возвращаемого значения:

_StorageBase | TypedStorage | str

untyped() [исходный код]

Возвращает внутреннее torch.UntypedStorage.

class torch.DoubleStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.float64

class torch.FloatStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.float32

class torch.HalfStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.float16

class torch.LongStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.int64

class torch.IntStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.int32

class torch.ShortStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.int16

class torch.CharStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.int8

class torch.ByteStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.uint8

class torch.BoolStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.bool

class torch.BFloat16Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.bfloat16

class torch.ComplexDoubleStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.complex128

class torch.ComplexFloatStorage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.complex64

class torch.QUInt8Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.quint8

class torch.QInt8Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.qint8

class torch.QInt32Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.qint32

class torch.QUInt4x2Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.quint4x2

class torch.QUInt2x4Storage(*args, wrap_storage=None, dtype=None, device=None, _internal=False) [исходный код]

dtype: torch.dtype = torch.quint2x4