Функция broadcast_to

Функция broadcast_to возвращает новый тензор, который является расширенной версией исходного тензора до указанной формы. Расширение выполняется по правилам broadcasting, при этом данные исходного тензора не копируются - фактически создаётся представление (view) с новой формой. Первым параметром функция принимает исходный тензор, вторым - целевую форму в виде кортежа или списка чисел.

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

Синтаксис

torch.broadcast_to(tensor, shape)

Пример

Расширим одномерный тензор из трёх элементов до двумерной формы (2, 3):

import torch

t = torch.tensor([1, 2, 3])
res = torch.broadcast_to(t, (2, 3))
print(res)

Результат выполнения кода:

tensor([
	[1, 2, 3],
	[1, 2, 3],
])

Как видно, тензор был расширен по первой размерности путём повторения строки.

Пример

Расширим двумерный тензор формы (1, 4) до формы (3, 4):

import torch

t = torch.tensor([[1, 2, 3, 4]])
res = torch.broadcast_to(t, (3, 4))
print(res)

Результат выполнения кода:

tensor([
	[1, 2, 3, 4],
	[1, 2, 3, 4],
	[1, 2, 3, 4],
])

Пример

Расширение тензора с добавлением новых размерностей. Исходный тензор имеет форму (3,), расширим до (2, 3, 2):

import torch

t = torch.tensor([1, 2, 3])
res = torch.broadcast_to(t, (2, 3, 2))
print(res)

Результат выполнения кода:

tensor([
	[
		[1, 1],
		[2, 2],
		[3, 3],
	],
	[
		[1, 1],
		[2, 2],
		[3, 3],
	],
])

Обратите внимание: исходная размерность 3 соответствует второй размерности целевой формы, а новые размерности (первая и третья) успешно расширены, так как по правилам broadcasting они могут быть добавлены.

Пример

Попытка расширения до несовместимой формы вызовет ошибку. Исходный тензор формы (2, 3) не может быть расширен до (2, 4):

import torch

t = torch.tensor([
	[1, 2, 3],
	[4, 5, 6],
])
try:
	res = torch.broadcast_to(t, (2, 4))
except RuntimeError as e:
	print(e)

Результат выполнения кода:

"The expanded size of the tensor (4) must match the existing size (3) at non-singleton dimension 1."

Ошибка возникает потому, что вторая размерность исходного тензора равна трём, а целевая - четырём, и при этом размерность не является единичной, что нарушает правила broadcasting.

Пример

Использование broadcast_to для создания маски. Расширим вектор до формы матрицы для поэлементных операций:

import torch

t = torch.tensor([1, 2, 3])
mask = torch.broadcast_to(t, (4, 3))
print(mask)

Результат выполнения кода:

tensor([
	[1, 2, 3],
	[1, 2, 3],
	[1, 2, 3],
	[1, 2, 3],
])

Смотрите также

функцию broadcast_tensors,
которая одновременно расширяет несколько тензоров до общей формы
функцию reshape,
которая изменяет форму тензора с возможным копированием данных
функцию atleast_2d,
которая приводит тензор как минимум к двумерной форме
функцию stack,
которая объединяет тензоры вдоль новой размерности