Универсальные функции (ufunc)

Универсальная функция (или ufunc для краткости) — это функция, которая работает с ndarrays поэлементно, поддерживая векторное сложение, преобразование типов и ряд других стандартных функций. То есть ufunc — это «векторизованная» оболочка для функции, принимающей фиксированное количество определённых входных данных и производящей фиксированное количество определённых выходных данных.

В NumPy универсальные функции являются экземплярами класса numpy.ufunc. Многие встроенные функции реализованы на скомпилированном C-коде. Базовые ufuncs работают со скалярами, но существует также обобщённый вид, для которого базовыми элементами являются подмассивы (векторы, матрицы и т. д.), а векторизация выполняется по другим измерениям. Также можно создавать пользовательские ufunc экземпляры, используя фабричную функцию frompyfunc.

Векторное сложение

Каждая универсальная функция принимает массивы в качестве входных данных и производит массивы вывода, выполняя основную функцию поэлементно на входных данных (где элемент обычно является скаляром, но может быть вектором или подмассивом более высокого порядка для обобщённых ufuncs). Применяются стандартные правила векторизации, поэтому входные данные, не имеющие точно одинаковых форм, всё ещё могут быть использованы в вычислениях. Векторное сложение можно понять по четырём правилам:

1. Все входные массивы с ndim меньше, чем входной массив с наибольшим ndim, имеют 1 в начале их форм.
2. Размер в каждом измерении формы выходного массива является максимальным из всех размеров входных массивов в этом измерении.
3. Вводной массив может быть использован в вычислении, если его размер в определённом измерении либо совпадает с размером выходного массива в этом измерении, либо имеет значение ровно 1.
4. Если у входного массива размер измерения в его форме равен 1, то первое значение в этом измерении будет использоваться для всех вычислений вдоль этого измерения. Другими словами, механизм шагов ufunc просто не будет шагать по этому измерению (шаг шага будет равен 0 для этого измерения).

Векторное сложение используется в NumPy для определения способа обработки массивов с различными формами; например, все арифметические операции (+, -, *, …) между ndarrays векторизуют массивы перед операцией.

Набор массивов называется «совместимым» с одинаковой формой, если вышеперечисленные правила приводят к правильному результату, т. е., выполняется одно из следующих условий:

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

Пример

Если a.shape — (5,1), b.shape — (1,6), c.shape — (6,) и d.shape — (), так что d — скаляр, то a, b, c и d все векторизуются в размерность (5,6); и

• a ведет себя как массив (5,6), где a[:,0] векторизуется в другие столбцы,
• b ведет себя как массив (5,6), где b[0,:] векторизуется в другие строки,
• c ведет себя как массив (1,6) и поэтому как массив (5,6), где c[:] векторизуется в каждую строку, и, наконец,
• d ведет себя как массив (5,6), где единственное значение повторяется.

Определение типа результата

Результат ufunc (и его методов) необязательно является ndarray, если все входные аргументы не являются ndarrays. Действительно, если какой-либо входной аргумент определяет метод __array_ufunc__, управление полностью передаётся этой функции, то есть ufunc переопределяется.

Если ни один из входных аргументов не переопределяет ufunc, то все выходные массивы будут переданы методам __array_prepare__ и __array_wrap__ входных данных (кроме ndarrays и скаляров), которые его определяют и имеют наивысший __array_priority__ из всех других входных данных универсальной функции. Значение по умолчанию __array_priority__ для ndarray равно 0,0, а значение по умолчанию __array_priority__ для подтипов равно 0,0. У матриц __array_priority__ равно 10,0.

Все ufuncs также могут принимать аргументы вывода. При необходимости выходные данные будут преобразованы к типу данных(ов) предоставленного(ых) выходного(ых) массива(ов). Если для вывода используется класс с методом __array__, результаты будут записаны в объект, возвращаемый методом __array__. Затем, если у класса также есть метод __array_prepare__, он вызывается для определения метаданных на основе контекста ufunc (контекст состоит из самого ufunc, аргументов, переданных ufunc, и области ufunc). Объект массива, возвращённый методом __array_prepare__, передаётся ufunc для вычисления. Наконец, если у класса также есть метод __array_wrap__, возвращаемый ndarray результат будет передан этому методу перед передачей управления обратно вызывающей стороне.

Использование внутренних буферов

Внутри буферы используются для невыровненных данных, данных, которые нужно перевернуть, и данных, которые нужно преобразовать из одного типа данных в другой. Размер внутренних буферов настраивается для каждого потока. Может быть создано до \(2 (n_{\mathrm{inputs}} + n_{\mathrm{outputs}})\) буферов указанного размера для обработки данных со всех входных и выходных данных ufunc. Размер буфера по умолчанию составляет 10 000 элементов. Всякий раз, когда требуется вычисление на основе буфера, но все входные массивы меньше размера буфера, эти массивы с неправильным поведением или типом будут скопированы перед началом вычислений. Таким образом, изменение размера буфера может изменить скорость выполнения вычислений ufunc различных типов.

Обработка ошибок

Универсальные функции могут вызывать специальные регистры состояния операций с плавающей точкой в вашем оборудовании (например, деление на ноль). Если доступны на вашей платформе, эти регистры будут регулярно проверяться во время вычислений. Обработка ошибок контролируется для каждого потока и может быть настроена с помощью функций

Правила преобразования типов

В основе каждого ufunc лежит одномерный строковый цикл, реализующий фактическую функцию для определённой комбинации типов. При создании ufunc ему передаётся статический список внутренних циклов и соответствующий список сигнатур типов, по которым ufunc работает. Машина ufunc использует этот список для определения, какой внутренний цикл использовать в конкретном случае. Вы можете проверить атрибут .types для конкретного ufunc, чтобы увидеть, какие комбинации типов имеют определённый внутренний цикл и какой тип результата они генерируют (коды символов используются в этом результате для краткости).

Преобразование должно быть выполнено для одного или нескольких входных данных всякий раз, когда ufunc не имеет реализации основного цикла для предоставленных входных типов. Если реализация для входных типов не найдена, то алгоритм ищет реализацию с сигнатурой типа, в которую все входные данные могут быть преобразованы «безопасно». Первый найденный в своём внутреннем списке циклов выбирается и выполняется после всех необходимых преобразований типов. Имейте в виду, что внутренние копии во время ufunc (даже при преобразовании) ограничены размером внутреннего буфера (который можно настроить пользователем).

Согласно вышеизложенному описанию, правила преобразования в основном реализуются вопросом, когда тип данных может быть преобразован «безопасно» в другой тип данных. На этот вопрос можно ответить в Python с помощью вызова функции: can_cast(fromtype, totype). На рисунке ниже показаны результаты этого вызова для 24 поддерживаемых внутри типов на 64-битной системе автора. Вы можете сгенерировать эту таблицу для вашей системы с помощью кода, приведённого на рисунке.

>>> mark = {False: ' -', True: ' Y'}
>>> def print_table(ntypes):
...     print('X ' + ' '.join(ntypes))
...     for row in ntypes:
...         print(row, end='')
...         for col in ntypes:
...             print(mark[np.can_cast(row, col)], end='')
...         print()
...
>>> print_table(np.typecodes['All'])
X ? b h i l q p B H I L Q P e f d g F D G S U V O M m
? Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Y
b - Y Y Y Y Y Y - - - - - - Y Y Y Y Y Y Y Y Y Y Y - Y
h - - Y Y Y Y Y - - - - - - - Y Y Y Y Y Y Y Y Y Y - Y
i - - - Y Y Y Y - - - - - - - - Y Y - Y Y Y Y Y Y - Y
l - - - - Y Y Y - - - - - - - - Y Y - Y Y Y Y Y Y - Y
q - - - - Y Y Y - - - - - - - - Y Y - Y Y Y Y Y Y - Y
p - - - - Y Y Y - - - - - - - - Y Y - Y Y Y Y Y Y - Y
B - - Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Y
H - - - Y Y Y Y - Y Y Y Y Y - Y Y Y Y Y Y Y Y Y Y - Y
I - - - - Y Y Y - - Y Y Y Y - - Y Y - Y Y Y Y Y Y - Y
L - - - - - - - - - - Y Y Y - - Y Y - Y Y Y Y Y Y - -
Q - - - - - - - - - - Y Y Y - - Y Y - Y Y Y Y Y Y - -
P - - - - - - - - - - Y Y Y - - Y Y - Y Y Y Y Y Y - -
e - - - - - - - - - - - - - Y Y Y Y Y Y Y Y Y Y Y - -
f - - - - - - - - - - - - - - Y Y Y Y Y Y Y Y Y Y - -
d - - - - - - - - - - - - - - - Y Y - Y Y Y Y Y Y - -
g - - - - - - - - - - - - - - - - Y - - Y Y Y Y Y - -
F - - - - - - - - - - - - - - - - - Y Y Y Y Y Y Y - -
D - - - - - - - - - - - - - - - - - - Y Y Y Y Y Y - -
G - - - - - - - - - - - - - - - - - - - Y Y Y Y Y - -
S - - - - - - - - - - - - - - - - - - - - Y Y Y Y - -
U - - - - - - - - - - - - - - - - - - - - - Y Y Y - -
V - - - - - - - - - - - - - - - - - - - - - - Y Y - -
O - - - - - - - - - - - - - - - - - - - - - - - Y - -
M - - - - - - - - - - - - - - - - - - - - - - Y Y Y -
m - - - - - - - - - - - - - - - - - - - - - - Y Y - Y

Следует отметить, что, хотя они включены в таблицу для полноты, типы «S», «U» и «V» не могут обрабатываться ufunc. Также обратите внимание, что на 32-битной системе целые типы могут иметь разные размеры, что приводит к несколько изменённой таблице.

Смешанные операции скаляр-массив используют другой набор правил преобразования, гарантирующих, что скаляр не может «поднимать» массив, если скаляр не является фундаментально отличного типа данных (т.е., под другим уровнем в иерархии типов данных), чем массив. Это правило позволяет использовать скалярные константы в вашем коде (которые, как типы Python, интерпретируются соответствующим образом в ufunc), не беспокоясь о том, повлияет ли точность скалярной константы на повышение точности вашего большого (малой точности) массива.

Переопределение поведения Ufunc

Классы (включая подклассы ndarray) могут переопределить, как ufunc действуют на них, определив некоторые специальные методы. Для получения подробностей см. Стандартные подклассы массивов.

ufunc

Необязательные ключевые аргументы

Все ufunc принимают необязательные ключевые аргументы. Большинство из них представляют расширенное использование и обычно не используются.

out

Первый вывод может быть предоставлен как позиционный, так и ключевой параметр. Ключевые аргументы ‘out’ несовместимы с позиционными.

Ключевой аргумент ‘out’ ожидается в виде кортежа с одной записью на вывод (который может быть None для массивов, выделяемых ufunc). Для ufunc с одним выводом также допустимо передать один массив (вместо кортежа, содержащего один массив).

Передача одного массива в ключевом аргументе ‘out’ ufunc с несколькими выходами устарела и будет выводить предупреждение в numpy 1.10 и ошибку в будущей версии.

Если ‘out’ равно None (по умолчанию), создаётся неинициализированный массив возврата. Затем массив вывода заполняется результатами ufunc в тех местах, где трансляция ‘where’ равна True. Если ‘where’ равен скалярному True (по умолчанию), то это соответствует заполнению всего вывода. Обратите внимание, что выводы, которые явно не заполнены, сохраняют свои неинициализированные значения.

Операции, где входные и выходные операнды ufunc имеют перекрытие памяти, определяются так же, как и для эквивалентных операций, где памяти нет. Для устранения зависимости данных выполняются временные копии по мере необходимости. Поскольку определение таких случаев вычислительно дорого, используется эвристика, которая в редких случаях может привести к ненужным временным копиям. Для операций, где зависимость данных достаточно проста для анализа эвристикой, временные копии не будут создаваться, даже если массивы перекрываются, если можно предположить, что копии не нужны. Например, np.add(a, b, out=a) не будет вовлечь копий.

where

Принимает булевский массив, который транслируется вместе с операндами. Значения True указывают на вычисление ufunc в этом положении, значения False указывают на оставление значения в выводе в покое. Этот аргумент нельзя использовать для обобщённых ufunc, поскольку они принимают нескалярный вход.

Обратите внимание, что если создаётся неинициализированный массив возврата, значения False оставят эти значения неинициализированными.

axes

Список кортежей с индексами осей, по которым должен работать обобщённый ufunc. Например, для сигнатуры (i,j),(j,k)->(i,k) соответствующей матричному умножению, базовые элементы — это двумерные матрицы, и они предполагаются хранящимися в двух последних осях каждого аргумента. Соответствующий ключевой аргумент axes будет [(-2, -1), (-2, -1), (-2, -1)]. Для простоты, для обобщённых ufunc, работающих с одномерными массивами (векторами), принимается одно целое число вместо кортежа из одного элемента, а для обобщённых ufunc, для которых все выводы являются скалярными, кортежи вывода можно опустить.

axis

Одна ось, по которой обобщённый ufunc должен работать. Это сокращение для ufunc, которые работают по одной общей основной размерности, эквивалентное передаче axes со значениями (axis,) для каждого аргумента с одной основной размерностью и () для всех остальных. Например, для сигнатуры (i),(i)->(), это эквивалентно передаче axes=[(axis,), (axis,), ()].

keepdims

Если это установлено в True, оси, по которым производится сокращение, будут оставаться в результате как размерность с размером один, чтобы результат корректно транслировался по отношению к входам. Этот параметр может использоваться только для обобщённых ufunc, которые работают с входами, которые все имеют одинаковое количество основных измерений, и с выходами, которые не имеют основных измерений, то есть с сигнатурами, такими как (i),(i)->() или (m,m)->(). При использовании положение измерений в выводе можно контролировать с помощью axes и axis.

casting

Может быть ‘no’, ‘equiv’, ‘safe’, ‘same_kind’, или ‘unsafe’. См. can_cast для объяснений значений параметров.

Предоставляет политику для разрешённых преобразований. Для совместимости с предыдущими версиями NumPy по умолчанию установлено ‘unsafe’ для numpy < 1.7. В numpy 1.7 началось переход к ‘same_kind’, где ufunc создаёт DeprecationWarning для вызовов, которые разрешены по правилам ‘unsafe’, но не по правилам ‘same_kind’. В numpy 1.10 и далее значение по умолчанию — ‘same_kind’.

order

Устанавливает порядок итерации/структуру памяти массива вывода. По умолчанию ‘K’. ‘C’ означает, что вывод должен быть C-непрерывным, ‘F’ означает F-непрерывным, ‘A’ означает F-непрерывным, если входные данные F-непрерывны и не C-непрерывны, в противном случае C-непрерывный, а ‘K’ означает, что нужно максимально соответствовать порядку элементов входных данных.

dtype

Переопределяет тип данных выходных массивов так же, как и signature. Это должно обеспечить соответствие точности вычислений. Точные выбранные типы данных вычислений могут зависеть от ufunc, и входные данные могут быть преобразованы к этому типу данных для выполнения вычислений.

subok

По умолчанию true. Если установлено в false, вывод всегда будет строгим массивом, а не подтипом.

signature

Тип данных, кортеж типов данных или специальная строка сигнатуры, указывающая типы входных и выходных данных ufunc.

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

Когда все типы данных фиксированы, выбирается определённый цикл или генерируется ошибка, если соответствующий цикл не существует. Если некоторые типы данных не указаны и оставлены None, поведение может зависеть от ufunc. В настоящее время список доступных сигнатур предоставляется атрибутом types ufunc. (В этом списке могут отсутствовать типы данных, не определённые NumPy.)

signature указывает только класс/тип типа данных. Например, он может указать, что операция должна быть datetime64 или float64 операцией. Он не указывает datetime64 единицы измерения времени или float64 порядок байтов.

Для обратной совместимости этот аргумент также может быть передан как sig, хотя предпочтительнее использовать полную форму. Обратите внимание, что это не следует путать с обобщенной функцией ufunc подпись, которая хранится в атрибуте signature объекта ufunc.

extobj

список длиной 3, определяющий размер буфера ufunc, целое число режима ошибки и функцию обратного вызова ошибки. Обычно эти значения ищутся в словаре, связанном с потоком. Передача их сюда обходит этот поиск и использует низкоуровневое определение для режима ошибки. Это может быть полезно, например, в качестве оптимизации для вычислений, требующих многих вызовов ufunc для небольших массивов в цикле.

Атрибуты

Существуют некоторые информационные атрибуты, которыми обладают универсальные функции. Ни один из атрибутов не может быть изменен.

Методы

Все функции ufunc имеют четыре метода. Однако эти методы имеют смысл только для скалярных функций ufunc, принимающих два входных аргумента и возвращающих один выходной аргумент. Попытка вызвать эти методы для других функций ufunc приведет к ValueError. Методы, похожие на reduce, все принимают ключевое слово axis, ключевое слово dtype и ключевое слово out, а массивы должны иметь размерность >= 1. Ключевое слово axis задает ось массива, по которой будет выполняться уменьшение (с отрицательными значениями, отсчитываемыми назад). Обычно это целое число, хотя для ufunc.reduce оно также может быть кортежем из int для уменьшения по нескольким осям одновременно или None для уменьшения по всем осям. Ключевое слово dtype позволяет управлять очень распространенной проблемой, возникающей при небрежном использовании ufunc.reduce. Иногда у вас может быть массив определенного типа данных, и вы хотите сложить все его элементы, но результат не помещается в тип данных массива. Это часто происходит, если у вас есть массив целых чисел с одним байтом. Ключевое слово dtype позволяет изменить тип данных, по которому выполняется уменьшение (и, следовательно, тип выходного значения). Таким образом, вы можете убедиться, что выходной тип имеет точность, достаточную для обработки вашего результата. Ответственность за изменение типа reduce в основном лежит на вас. Есть одно исключение: если для операции reduce с операциями «сложение» или «умножение» не задан dtype, то если входной тип — целого (или булевого) типа данных и меньше размера типа данных int_, он будет неявно преобразован к типу данных int_ (или uint). Наконец, ключевое слово out позволяет указать выходной массив (для функций ufunc с одним выходом, которые в настоящее время поддерживаются; для будущих расширений можно передать кортеж с одним аргументом). Если задано out, то аргумент dtype игнорируется.

Функции ufunc также имеют пятый метод, который позволяет выполнять операции на месте с помощью индексации с помощью элементов.

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

Доступные функции ufunc

В настоящее время в numpy определены более 60 универсальных функций для одного или нескольких типов, охватывающих широкий спектр операций. Некоторые из этих функций ufunc вызываются автоматически для массивов при использовании соответствующей инфиксной записи (например, add(a, b) вызывается неявно при записи a + b и a или b является ndarray). Тем не менее, вы по-прежнему можете использовать вызов функции ufunc, чтобы использовать необязательный выходной аргумент(ы) для размещения выходного(ых) значения(й) в объекте(ах) по вашему выбору.

Помните, что каждая функция ufunc работает поэлементно. Поэтому каждая скалярная функция ufunc будет описана так, как если бы она действовала на наборе скалярных входов, чтобы вернуть набор скалярных выходов.

Математические операции

Тригонометрические функции

Все тригонометрические функции используют радианы, когда требуется угол. Соотношение градусов к радианам составляет \(180^{\circ}/\pi.\)

Функции битового манипулирования

Все эти функции требуют целочисленных аргументов и манипулируют битовым представлением этих аргументов.

Функции сравнения

Функции с плавающей запятой

Обратите внимание, что все эти функции работают поэлементно над массивом, возвращая массив результатов. Подробное описание содержит только одну операцию.