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

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

Основы универсальных функций (ufunc)

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

ufunc

numpy.ufunc()

Функции, которые работают поэлементно на целых массивах.

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

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

выход

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

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

Если ‘out’ равен None (по умолчанию), создаётся неинициализированный выходной массив, который будет заполнен в ufunc. В конце этот массив возвращается, если он не нульмерный, в этом случае он преобразуется в скаляр; это преобразование можно избежать, передав out=.... Это также может быть записано как out=Ellipsis если вы считаете, что это понятнее.

Обратите внимание, что выходные данные заполняются только в тех местах, где условие 'where' равно True. Если 'where' — скаляр True (по умолчанию), то это соответствует всем элементам вывода, но в других случаях элементы, не заполненные явно, остаются с неинициализированными значениями.

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

где

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

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

оси

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

ось

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

keepdims

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

приведение типов

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

Определяет политику того, какие виды приведения разрешены. Для совместимости с предыдущими версиями NumPy, по умолчанию это 'unsafe' для numpy < 1.7. В numpy 1.7 начался переход к 'same_kind', где ufuncs выдают DeprecationWarning для вызовов, которые разрешены по правилам 'unsafe', но не по правилам 'same_kind'. Начиная с numpy 1.10 и далее, по умолчанию используется 'same_kind'.

порядок

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

dtype

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

subok

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

сигнатура

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

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

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

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

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

Атрибуты

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

__doc__	Строка документации для каждой универсальной функции. Первая часть строки документации динамически генерируется из количества выходов, имени и количества входов. Вторая часть строки документации предоставляется во время создания и хранится вместе с универсальной функцией.
__name__	Имя ufunc.
__signature__	Сигнатура вызова ufunc, как inspect.Signature объект.

ufunc.nin	Количество входов.
ufunc.nout	Количество выходов.
ufunc.nargs	Количество аргументов.
ufunc.ntypes	Количество типов.
ufunc.types	Возвращает список с типами, сгруппированными по входу->выходу.
ufunc.identity	Значение идентичности.
ufunc.signature	Определение основных элементов, на которых работает обобщённая универсальная функция.

Методы

ufunc.reduce(array[, axis, dtype, out, ...])	Сокращает arrayизмерение 's на единицу, применяя ufunc вдоль одной оси.
ufunc.accumulate(array[, axis, dtype, out])	Накопить результат применения оператора ко всем элементам.
ufunc.reduceat(array, indices[, axis, ...])	Выполняет (локальное) сокращение с указанными срезами по одной оси.
ufunc.outer(A, B, /, **kwargs)	Применить ufunc op ко всем парам (a, b), где a в A и b в B.
ufunc.at(a, indices[, b])	Выполняет небуферизованную операцию на месте для операнда 'a' для элементов, указанных 'indices'.

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

Операция, подобная reduce, на массиве с типом данных, который имеет диапазон "слишком мал" для обработки результата, будет тихо оборачиваться. Следует использовать dtype для увеличения размера типа данных, над которым производится редукция.

Доступные ufuncs

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

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

Примечание

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

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

add(x1, x2, / [, out, where, casting, order, ...])	Добавить аргументы поэлементно.
subtract(x1, x2, /[, out, where, casting, ...])	Вычитает аргументы поэлементно.
multiply(x1, x2, /[, out, where, casting, ...])	invalid_raise
matmul(x1, x2, /[, out, casting, order, ...])	Матричное произведение двух массивов.
divide(x1, x2, /[, out, where, casting, ...])	Разделите аргументы поэлементно.
logaddexp(x1, x2, /[, out, where, casting, ...])	Логарифм суммы экспонент входных данных.
logaddexp2(x1, x2, /[, out, where, casting, ...])	Логарифм суммы экспонент входных данных по основанию 2.
true_divide(x1, x2, /[, out, where, ...])	Разделите аргументы поэлементно.
floor_divide(x1, x2, /[, out, where, ...])	Возвращает наибольшее целое число, меньшее или равное результату деления входных данных.
negative(x, /[, out, where, casting, order, ...])	Поэлементное числовое отрицание.
positive(x, /[, out, where, casting, order, ...])	Числовое положительное, поэлементно.
power(x1, x2, /[, out, where, casting, ...])	Элементы первого массива, возведенные в степени из второго массива, поэлементно.
float_power(x1, x2, /[, out, where, ...])	Элементы первого массива, возведенные в степени из второго массива, поэлементно.
remainder(x1, x2, /[, out, where, casting, ...])	Возвращает поэлементный остаток от деления.
mod(x1, x2, / [, out, where, casting, order, ...])	Возвращает поэлементный остаток от деления.
fmod(x1, x2, /[, out, where, casting, ...])	Возвращает поэлементный остаток от деления.
divmod(x1, x2[, out1, out2], / [[, out, ...])	Возвращает поэлементное частное и остаток одновременно.
absolute(x, /[, out, where, casting, order, ...])	Вычислить абсолютное значение поэлементно.
fabs(x, /[, out, where, casting, order, ...])	Вычисление абсолютных значений поэлементно.
rint(x, /[, out, where, casting, order, ...])	Округлить элементы массива до ближайшего целого числа.
sign(x, /[, out, where, casting, order, ...])	Возвращает поэлементное указание знака числа.
heaviside(x1, x2, /[, out, where, casting, ...])	Вычислить функцию Хевисайда.
conj(x, /[, out, where, casting, order, ...])	Вернуть комплексно-сопряженное значение поэлементно.
conjugate(x, /[, out, where, casting, ...])	Вернуть комплексно-сопряженное значение поэлементно.
exp(x, /[, out, where, casting, order, ...])	Вычислить экспоненту всех элементов входного массива.
exp2(x, /[, out, where, casting, order, ...])	Вычислить 2**p для всех p кортежи.
log(x, /[, out, where, casting, order, ...])	Натуральный логарифм, поэлементно.
log2(x, /[, out, where, casting, order, ...])	Логарифм по основанию 2 от x.
log10(x, /[, out, where, casting, order, ...])	Возвращает десятичный логарифм входного массива поэлементно.
expm1(x, /[, out, where, casting, order, ...])	Вычислить exp(x) - 1 для всех элементов в массиве.
log1p(x, /[, out, where, casting, order, ...])	Возвращает натуральный логарифм от единицы плюс входной массив, поэлементно.
sqrt(x, /[, out, where, casting, order, ...])	Возвращает неотрицательный квадратный корень из массива поэлементно.
square(x, /[, out, where, casting, order, ...])	Возвращает поэлементный квадрат входных данных.
cbrt(x, /[, out, where, casting, order, ...])	Возвращает кубический корень массива поэлементно.
reciprocal(x, /[, out, where, casting, ...])	Возвращает обратную величину аргумента поэлементно.
gcd(x1, x2, / [, out, where, casting, order, ...])	Возвращает наибольший общий делитель |x1| и |x2|
lcm(x1, x2, / [, out, where, casting, order, ...])	Возвращает наименьшее общее кратное |x1| и |x2|

Совет

Необязательные выходные аргументы могут использоваться для помощи в экономии памяти при больших вычислениях. Если ваши массивы большие, сложные выражения могут выполняться дольше, чем абсолютно необходимо, из-за создания и (позже) уничтожения временных областей вычислений. Например, выражение G = A * B + C эквивалентно T1 = A * B; G = T1 + C; del T1. Он будет выполнен быстрее как G = A * B; add(G, C, G) что то же самое, что G = A * B; G += C.

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

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

sin(x, /[, out, where, casting, order, ...])	Тригонометрический синус, поэлементно.
cos(x, /[, out, where, casting, order, ...])	Косинус поэлементно.
tan(x, /[, out, where, casting, order, ...])	Вычисляет тангенс поэлементно.
arcsin(x, /[, out, where, casting, order, ...])	Обратный синус, поэлементно.
arccos(x, /[, out, where, casting, order, ...])	Тригонометрический арккосинус, поэлементно.
arctan(x, /[, out, where, casting, order, ...])	Тригонометрический арктангенс, поэлементно.
arctan2(x1, x2, /[, out, where, casting, ...])	Поэлементный арктангенс x1/x2 Довольно часто новые массивы должны создаваться из кода модуля расширения. Возможно, требуется выходной массив, и вы не хотите, чтобы вызывающая сторона должна была его предоставить. Возможно, нужен только временный массив для хранения промежуточных вычислений. Независимо от потребности существуют простые способы получения объекта ndarray любого необходимого типа данных. Наиболее общая функция для этого —
hypot(x1, x2, /[, out, where, casting, ...])	Для заданных "катетов" прямоугольного треугольника вернуть его гипотенузу.
sinh(x, /[, out, where, casting, order, ...])	Гиперболический синус, поэлементно.
cosh(x, /[, out, where, casting, order, ...])	Гиперболический косинус, поэлементно.
tanh(x, /[, out, where, casting, order, ...])	Вычислить гиперболический тангенс поэлементно.
arcsinh(x, /[, out, where, casting, order, ...])	Обратный гиперболический синус поэлементно.
arccosh(x, /[, out, where, casting, order, ...])	Обратный гиперболический косинус, поэлементно.
arctanh(x, /[, out, where, casting, order, ...])	Обратный гиперболический тангенс поэлементно.
degrees(x, /[, out, where, casting, order, ...])	Преобразовать углы из радиан в градусы.
radians(x, /[, out, where, casting, order, ...])	Преобразует углы из градусов в радианы.
deg2rad(x, /[, out, where, casting, order, ...])	Преобразует углы из градусов в радианы.
rad2deg(x, /[, out, where, casting, order, ...])	Преобразовать углы из радиан в градусы.

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

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

bitwise_and(x1, x2, /[, out, where, ...])	Вычислить побитовое И двух массивов поэлементно.
bitwise_or(x1, x2, /[, out, where, casting, ...])	Вычислить побитовое ИЛИ двух массивов поэлементно.
bitwise_xor(x1, x2, /[, out, where, ...])	Вычислить побитовое исключающее ИЛИ двух массивов поэлементно.
invert(x, /[, out, where, casting, order, ...])	Выполняет побитовую инверсию, или побитовое НЕ, поэлементно.
left_shift(x1, x2, /[, out, where, casting, ...])	Сдвинуть биты целого числа влево.
right_shift(x1, x2, /[, out, where, ...])	Сдвинуть биты целого числа вправо.

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

greater(x1, x2, /[, out, where, casting, ...])	Возвращает истинное значение (x1 > x2) поэлементно.
greater_equal(x1, x2, /[, out, where, ...])	Возвращает истинное значение (x1 >= x2) поэлементно.
less(x1, x2, /[, out, where, casting, ...])	Вернуть истинное значение (x1 < x2) поэлементно.
less_equal(x1, x2, /[, out, where, casting, ...])	Возвращает истинное значение (x1 <= x2) поэлементно.
not_equal(x1, x2, /[, out, where, casting, ...])	Возвращает (x1 != x2) поэлементно.
equal(x1, x2, /[, out, where, casting, ...])	Возвращает (x1 == x2) поэлементно.

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

Не используйте ключевые слова Python and и or для объединения логических выражений массивов. Эти ключевые слова проверяют истинность всего массива (а не поэлементно, как можно было бы ожидать). Вместо них используйте побитовые операторы & и |.

logical_and(x1, x2, /[, out, where, ...])	Вычисляет логическое значение x1 И x2 поэлементно.
logical_or(x1, x2, /[, out, where, casting, ...])	Вычисляет поэлементное логическое ИЛИ x1 ИЛИ x2.
logical_xor(x1, x2, /[, out, where, ...])	Вычисляет логическое значение XOR для x1 и x2 поэлементно.
logical_not(x, /[, out, where, casting, ...])	Вычислите логическое значение NOT x поэлементно.

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

Побитовые операторы & и | — это правильный способ выполнения поэлементных сравнений массивов. Убедитесь, что вы понимаете приоритет операторов: (a > 2) & (a < 5) является правильным синтаксисом, потому что a > 2 & a < 5 приведёт к ошибке из-за того, что 2 & a вычисляется первым.

maximum(x1, x2, /[, out, where, casting, ...])

Поэлементный максимум элементов массива.

Совет

Функция Python max() найдет максимум по одномерному массиву, но сделает это с использованием более медленного последовательного интерфейса. Метод reduce ufunc максимума намного быстрее. Также, max() метод не даст ожидаемых ответов для массивов с более чем одним измерением. Метод reduce для minimum также позволяет вычислить общий минимум по массиву.

minimum(x1, x2, /[, out, where, casting, ...])

Поэлементный минимум элементов массива.

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

поведение maximum(a, b) отличается от max(a, b). Как ufunc, maximum(a, b) выполняет поэлементное сравнение a и b и выбирает каждый элемент результата в зависимости от того, какой элемент в двух массивах больше. В отличие от max(a, b) обрабатывает объекты a и b в целом, рассматривает (полное) истинностное значение a > b и использует его для возврата либо a или b (в целом). Аналогичное различие существует между minimum(a, b) и min(a, b).

fmax(x1, x2, /[, out, where, casting, ...])	Поэлементный максимум элементов массива.
fmin(x1, x2, /[, out, where, casting, ...])	Поэлементный минимум элементов массива.

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

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

isfinite(x, /[, out, where, casting, order, ...])	Поэлементная проверка на конечность (не бесконечность и не Not a Number).
isinf(x, /[, out, where, casting, order, ...])	Проверяет поэлементно на положительную или отрицательную бесконечность.
isnan(x, /[, out, where, casting, order, ...])	Проверить поэлементно на NaN и вернуть результат в виде булева массива.
isnat(x, /[, out, where, casting, order, ...])	Проверить поэлементно на NaT (не время) и вернуть результат в виде логического массива.
fabs(x, /[, out, where, casting, order, ...])	Вычисление абсолютных значений поэлементно.
signbit(x, /[, out, where, casting, order, ...])	Возвращает поэлементно True, где установлен signbit (меньше нуля).
copysign(x1, x2, /[, out, where, casting, ...])	Изменить знак x1 на знак x2, поэлементно.
nextafter(x1, x2, /[, out, where, casting, ...])	Возвращает следующее значение с плавающей точкой после x1 в направлении x2, поэлементно.
spacing(x, /[, out, where, casting, order, ...])	Возвращает расстояние между x и ближайшим соседним числом.
modf(x[, out1, out2], / [[, out, where, ...])	Возвращает дробную и целую части массива поэлементно.
ldexp(x1, x2, /[, out, where, casting, ...])	Возвращает x1 * 2**x2 поэлементно.
frexp(x[, out1, out2], / [[, out, where, ...])	Разложить элементы x на мантиссу и двоичную экспоненту.
fmod(x1, x2, /[, out, where, casting, ...])	Возвращает поэлементный остаток от деления.
floor(x, /[, out, where, casting, order, ...])	Возвращает округление вниз входных данных поэлементно.
ceil(x, /[, out, where, casting, order, ...])	Возвращает округление вверх для каждого элемента входных данных.
trunc(x, /[, out, where, casting, order, ...])	Возвращает усечённое значение входных данных поэлементно.