torch.masked

Введение

Мотивация

Предупреждение

API PyTorch для тензоров с масками находится на стадии прототипа и может быть изменен в будущем.

MaskedTensor служит расширением для torch.Tensor, предоставляя пользователю возможность:

использовать любые семантики масок (например, тензоры переменной длины, операции с NaN и т.д.)
различать градиенты 0 и NaN
различные применения разреженных данных (см. учебник ниже)

Термины «указанное» и «неуказанное» имеют давнюю историю в PyTorch без формальных семантик и, безусловно, без согласованности; на самом деле, MaskedTensor возник из накопившихся проблем, с которыми стандартный класс torch.Tensor не смог справиться должным образом. Таким образом, одной из основных целей MaskedTensor является стать источником истины для указанных и неуказанных значений в PyTorch, где они являются полноценными элементами, а не дополнениями. В свою очередь, это должно дополнительно раскрыть потенциал разреженности, обеспечить более безопасные и согласованные операции и предоставить более плавный и интуитивный опыт для пользователей и разработчиков.

Что такое MaskedTensor?

MaskedTensor — это подкласс тензора, который состоит из 1) входных данных и 2) маски. Маска указывает, какие элементы входных данных следует включать или игнорировать.

В качестве примера, предположим, что мы хотим замаскировать все значения, равные 0 (представленные серым цветом) и взять максимум:

Вверху представлен пример обычного тензора, а внизу — MaskedTensor, где все нули замаскированы. Это явно приводит к разному результату в зависимости от наличия маски, но эта гибкая структура позволяет пользователю систематически игнорировать любые элементы во время вычислений.

Уже существует ряд учебников, которые мы подготовили, чтобы помочь пользователям освоиться, например:

Поддерживаемые операторы

Унарные операторы

Унарные операторы — это операторы, содержащие только один вход. Их применение к MaskedTensor относительно просто: если данные замаскированы в данном индексе, мы применяем оператор, в противном случае мы продолжим маскировать данные.

Доступные унарные операторы:

`abs`	Вычисляет абсолютное значение каждого элемента в `input`.
`absolute`	Псевдоним для `torch.abs()`
`acos`	Вычисляет обратный косинус каждого элемента в `input`.
`arccos`	Псевдоним для `torch.acos()`.
`acosh`	Возвращает новый тензор с обратным гиперболическим косинусом элементов `input`.
`arccosh`	Псевдоним для `torch.acosh()`.
`angle`	Вычисляет угол (в радианах) каждого элемента заданного `input` тензора.
`asin`	Возвращает новый тензор с арксинусом элементов `input`.
`arcsin`	Псевдоним для `torch.asin()`.
`asinh`	Возвращает новый тензор с обратным гиперболическим синусом элементов `input`.
`arcsinh`	Псевдоним для `torch.asinh()`.
`atan`	Возвращает новый тензор с арктангенсом элементов `input`.
`arctan`	Псевдоним для `torch.atan()`.
`atanh`	Возвращает новый тензор с обратным гиперболическим тангенсом элементов `input`.
`arctanh`	Псевдоним для `torch.atanh()`.
`bitwise_not`	Вычисляет побитовое НЕ заданного входного тензора.
`ceil`	Возвращает новый тензор с целой частью элементов `input`, наименьшим целым числом, большим или равным каждому элементу.
`clamp`	Ограничивает все элементы в `input` в диапазоне `[` `min`, `max` `]`.
`clip`	Псевдоним для `torch.clamp()`.
`conj_physical`	Вычисляет комплексно-сопряжённое значение каждого элемента данного `input` тензора.
`cos`	Возвращает новый тензор с косинусом элементов `input`.
`cosh`	Возвращает новый тензор с гиперболическим косинусом элементов `input`.
`deg2rad`	Возвращает новый тензор, в котором каждый элемент из `input` преобразован из градусов в радианы.
`digamma`	Псевдоним для `torch.special.digamma()`.
`erf`	Псевдоним для `torch.special.erf()`.
`erfc`	Псевдоним для `torch.special.erfc()`.
`erfinv`	Псевдоним для `torch.special.erfinv()`.
`exp`	Возвращает новый тензор с экспонентой элементов входного тензора `input`.
`exp2`	Псевдоним для `torch.special.exp2()`.
`expm1`	Псевдоним для `torch.special.expm1()`.
`fix`	Псевдоним для `torch.trunc()`
`floor`	Возвращает новый тензор с наибольшим целым числом, меньшим или равным каждому элементу из `input`.
`frac`	Вычисляет дробную часть каждого элемента в `input`.
`lgamma`	Вычисляет натуральный логарифм абсолютного значения гамма-функции для `input`.
`log`	Возвращает новый тензор с натуральным логарифмом элементов `input`.
`log10`	Возвращает новый тензор с логарифмом по основанию 10 элементов `input`.
`log1p`	Возвращает новый тензор с натуральным логарифмом (1 + `input`).
`log2`	Возвращает новый тензор с логарифмом по основанию 2 элементов `input`.
`logit`	Псевдоним для `torch.special.logit()`.
`i0`	Псевдоним для `torch.special.i0()`.
`isnan`	Возвращает новый тензор с булевыми элементами, представляющими собой значение TRUE, если каждый элемент `input` является NaN или нет.
`nan_to_num`	Заменяет значения NaN, положительной и отрицательной бесконечности в `input` на значения, указанные `nan`, `posinf`, и `neginf`, соответственно.

END_OF_DOCUMENT_MARKER

`neg`	Возвращает новый тензор с отрицанием элементов `input`.
`negative`	Псевдоним для `torch.neg()`
`positive`	Возвращает `input`.
`pow`	Возводит каждый элемент в `input` в степень `exponent` и возвращает тензор с результатом.
`rad2deg`	Возвращает новый тензор, в котором каждый элемент из `input` преобразован из углов в радианах в градусы.
`reciprocal`	Возвращает новый тензор с обратными значениями элементов `input`.
`round`	Округляет элементы `input` до ближайшего целого числа.
`rsqrt`	Возвращает новый тензор с обратными значениями квадратных корней каждого элемента из `input`.
`sigmoid`	Псевдоним для `torch.special.expit()`.
`sign`	Возвращает новый тензор со знаками элементов из `input`.
`sgn`	Эта функция является расширением torch.sign() для комплексных тензоров.
`signbit`	Проверяет, установлен ли бит знака каждого элемента `input` или нет.
`sin`	Возвращает новый тензор с синусом элементов `input`.
`sinc`	Псевдоним для `torch.special.sinc()`.
`sinh`	Возвращает новый тензор с гиперболическим синусом элементов `input`.
`sqrt`	Возвращает новый тензор с квадратными корнями элементов `input`.
`square`	Возвращает новый тензор с квадратами элементов `input`.
`tan`	Возвращает новый тензор с тангенсом элементов `input`.
`tanh`	Возвращает новый тензор с гиперболическим тангенсом элементов `input`.
`trunc`	Возвращает новый тензор с усеченными целочисленными значениями элементов `input`.

Доступные операторы с заменой (inplace) — все вышеперечисленные, кроме:

`angle`	Вычисляет угол (в радианах) каждого элемента заданного `input` тензора.
`positive`	Возвращает `input`.
`signbit`	Проверяет, установлен ли бит знака каждого элемента `input` или нет.
`isnan`	Возвращает новый тензор с булевыми элементами, указывающими, является ли каждый элемент `input` NaN или нет.

Бинарные операторы

Как вы могли видеть в руководстве, MaskedTensor также реализованы бинарные операции, с оговоркой, что маски в двух MaskedTensors должны совпадать, иначе будет выведено сообщение об ошибке. Как отмечено в сообщении об ошибке, если вам нужна поддержка конкретного оператора или у вас есть предложения по семантике их поведения, пожалуйста, откройте вопрос на GitHub. Пока мы решили придерживаться наиболее консервативной реализации, чтобы пользователи точно понимали, что происходит, и принимали осознанные решения в отношении маскированных семантик.

Доступные бинарные операторы:

`add`	Добавляет `other`, масштабированную на `alpha`, к `input`.
`atan2`	Элемент-поэлементная арктангенс от $\text{input}_{i} / \text{other}_{i}$ с учётом квадранта.
`arctan2`	Псевдоним для `torch.atan2()`.
`bitwise_and`	Вычисляет побитовое И от `input` и `other`.
`bitwise_or`	Вычисляет побитовое ИЛИ от `input` и `other`.
`bitwise_xor`	Вычисляет побитовое ИСКЛЮЧАЮЩЕЕ ИЛИ от `input` и `other`.
`bitwise_left_shift`	Вычисляет сдвиг влево `input` на `other` бит.
`bitwise_right_shift`	Вычисляет сдвиг вправо `input` на `other` бит.
`div`	Делит каждый элемент входного `input` на соответствующий элемент `other`.
`divide`	Псевдоним для `torch.div()`.
`floor_divide`
`fmod`	Применяет std::fmod из C++ поэлементно.
`logaddexp`	Логарифм суммы экспонент входов.
`logaddexp2`	Логарифм суммы экспонент входов в двоичной системе.
`mul`	Умножает `input` на `other`.
`multiply`	Псевдоним для `torch.mul()`.
`nextafter`	Возвращает следующее значение с плавающей запятой после `input` в направлении `other`, поэлементно.
`remainder`	Вычисляет модуль Python поэлементно.
`sub`	Вычитает `other`, масштабированную на `alpha`, из `input`.
`subtract`	Псевдоним для `torch.sub()`.
`true_divide`	Псевдоним для `torch.div()` с `rounding_mode=None`.
`eq`	Вычисляет поэлементное равенство
`ne`	Вычисляет $\text{input} \neq \text{other}$ поэлементно.
`le`	Вычисляет $\text{input} \leq \text{other}$ поэлементно.
`ge`	Вычисляет $\text{input} \geq \text{other}$ поэлементно.
`greater`	Псевдоним для `torch.gt()`.
`greater_equal`	Псевдоним для `torch.ge()`.
`gt`	Вычисляет $\text{input} > \text{other}$ поэлементно.
`less_equal`	Псевдоним для `torch.le()`.
`lt`	Вычисляет $\text{input} < \text{other}$ поэлементно.
`less`	Псевдоним для `torch.lt()`.
`maximum`	Вычисляет поэлементный максимум `input` и `other`.
`minimum`	Вычисляет поэлементный минимум `input` и `other`.
`fmax`	Вычисляет поэлементный максимум `input` и `other`.
`fmin`	Вычисляет поэлементный минимум `input` и `other`.
`not_equal`	Псевдоним для `torch.ne()`.

Доступные операторы бинарных операций inplace — все вышеперечисленные, кроме:

`logaddexp`	Логарифм суммы экспоненциальных значений входных данных.
`logaddexp2`	Логарифм суммы экспоненциальных значений входных данных в основании 2.
`equal`	`True` если два тензора имеют одинаковый размер и элементы, `False` в противном случае.
`fmin`	Вычисляет поэлементный минимум `input` и `other`.
`minimum`	Вычисляет поэлементный минимум `input` и `other`.
`fmax`	Вычисляет поэлементный максимум `input` и `other`.

Сводки

Доступны следующие сводки (с поддержкой автографа). Более подробную информацию можно найти в учебнике Обзор, где приведены примеры сводок, а в учебнике Расширенная семантика — более глубокое обсуждение принятых правил семантики сводок.

`sum`	Возвращает сумму всех элементов в тензоре `input`.
`mean`	Возвращает среднее значение всех элементов в тензоре `input`.
`amin`	Возвращает минимальное значение каждого среза тензора `input` по заданным измерениям `dim`.
`amax`	Возвращает максимальное значение каждого среза тензора `input` по заданным измерениям `dim`.
`argmin`	Возвращает индексы минимального(ых) значения(й) уплощенного тензора или по измерению.
`argmax`	Возвращает индексы максимального значения всех элементов в тензоре `input`.
`prod`	Возвращает произведение всех элементов в тензоре `input`.
`all`	Проверяет, вычисляются ли все элементы в `input` как `True`.
`norm`	Возвращает матричную или векторную норму данного тензора.
`var`	Вычисляет дисперсию по измерениям, указанным в `dim`.
`std`	Вычисляет стандартное отклонение по измерениям, указанным в `dim`.

Функции представления и выбора

Мы включили ряд функций представления и выбора; интуитивно эти операторы будут применяться как к данным, так и к маске, а результат будет заключён в MaskedTensor. Для быстрого примера рассмотрим select():

>>> data = torch.arange(12, dtype=torch.float).reshape(3, 4)
>>> data
tensor([[ 0.,  1.,  2.,  3.],
        [ 4.,  5.,  6.,  7.],
        [ 8.,  9., 10., 11.]])
>>> mask = torch.tensor([[True, False, False, True], [False, True, False, False], [True, True, True, True]])
>>> mt = masked_tensor(data, mask)
>>> data.select(0, 1)
tensor([4., 5., 6., 7.])
>>> mask.select(0, 1)
tensor([False,  True, False, False])
>>> mt.select(0, 1)
MaskedTensor(
  [      --,   5.0000,       --,       --]
)

В настоящее время поддерживаются следующие операции:

`atleast_1d`	Возвращает одномерный вид каждого входного тензора с нулевыми измерениями.
`broadcast_tensors`	Распространяет заданные тензоры в соответствии с семантикой распространения.
`broadcast_to`	Распространяет `input` до формы `shape`.
`cat`	Конкатенирует заданную последовательность `seq` тензоров по заданному измерению.
`chunk`	Попытка разбить тензор на указанное количество кусков.
`column_stack`	Создает новый тензор, объединяя тензоры в `tensors` по горизонтали.
`dsplit`	Делит `input`, тензор с тремя или более измерениями, на несколько тензоров по глубине в соответствии с `indices_or_sections`.
`flatten`	Сглаживает `input`, преобразуя его в одномерный тензор.
`hsplit`	Делит `input`, тензор с одним или несколькими измерениями, на несколько тензоров по горизонтали в соответствии с `indices_or_sections`.
`hstack`	Упаковывает тензоры последовательно по горизонтали (по столбцам).
`kron`	Вычисляет кронекеровское произведение, обозначенное как $\otimes$ , тензоров `input` и `other`.
`meshgrid`	Создает сетки координат, задаваемые одномерными входами в тензорах `attr`.
`narrow`	Возвращает новый тензор, который является суженным вариантом тензора `input`.
`ravel`	Возвращает сплошной, сглаженный тензор.
`select`	Вырезает фрагмент тензора `input` вдоль выбранного измерения по указанному индексу.
`split`	Разбивает тензор на части.
`t`	Ожидает `input` быть тензором размерности не более 2 и транспонирует измерения 0 и 1.
`transpose`	Возвращает тензор, являющийся транспонированной версией `input`.
`vsplit`	Делит `input`, тензор с двумя или более измерениями, на несколько тензоров по вертикали в соответствии с `indices_or_sections`.
`vstack`	Упаковывает тензоры последовательно по вертикали (по строкам).
`Tensor.expand`	Возвращает новый вид тензора `self` с одиночными измерениями, расширенными до большего размера.
`Tensor.expand_as`	Расширяет этот тензор до размера, равного `other`.
`Tensor.reshape`	Возвращает тензор с теми же данными и количеством элементов, что и `self`, но с указанной формой.
`Tensor.reshape_as`	Возвращает этот тензор с формой, такой же как у `other`.
`Tensor.view`	Возвращает новый тензор с теми же данными, что и тензор `self`, но с другой `shape`.

© 2024, PyTorch Contributors
PyTorch has a BSD-style license, as found in the LICENSE file.
https://pytorch.org/docs/2.1/masked.html