torch.masked

Введение

Мотивация

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

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

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

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

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

Что такое MaskedTensor?

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

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

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

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

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

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

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

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

`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`	Возвращает новый тензор с булевыми элементами, указывающими, является ли каждый элемент `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`.

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

`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`	Логарифм суммы экспонент входных данных в базе-2.
`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`.

Сведения

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

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

Функции просмотра и выбора

Мы включили ряд функций просмотра и выбора; интуитивно, эти операторы будут применяться как к данным, так и к маске, а затем результат будет обернут в 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`	Создает сетки координат, заданные входными 1D в `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/1.13/masked.html