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

См. также

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

ufunc

numpy.ufunc()

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

Дополнительные ключевые аргументы

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

out

Введено в версии 1.6.

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

Введено в версии 1.10.

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

Передача одного массива в ключевом аргументе «out» для ufunc с несколькими результатами устарела и будет генерировать предупреждение в NumPy 1.10 и ошибку в будущих версиях.

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

Введено в версии 1.13.

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

where

Введено в версии 1.7.

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

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

axes

Введено в версии 1.15.

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

axis

Введено в версии 1.15.

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

keepdims

Введено в версии 1.15.

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

casting

Введено в версии 1.6.

Может быть «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

Введено в версии 1.6.

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

dtype

Введено в версии 1.6.

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

subok

Введено в версии 1.6.

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

signature

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

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

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

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

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

Атрибуты

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

__doc__

Строка документации для каждой ufunc. Первая часть строки документации динамически генерируется из количества результатов, имени и количества входных данных. Вторая часть строки документации предоставляется при создании и хранится с ufunc.

__name__

Имя ufunc.

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

Методы

`ufunc.reduce`(array[, axis, dtype, out, ...])	Уменьшает размерность массива `array` на единицу, применяя 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'.

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

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

Доступные ufuncs

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

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

Примечание

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

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

`add`(x1, x2, /[, out, where, casting, order, ...])	Складывает аргументы поэлементно.
`subtract`(x1, x2, /[, out, where, casting, ...])	Вычитает аргументы поэлементно.
`multiply`(x1, x2, /[, out, where, casting, ...])	Умножает аргументы поэлементно.
`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^x для всех элементов входного массива.
`log`(x, /[, out, where, casting, order, ...])	Натуральный логарифм поэлементно.
`log2`(x, /[, out, where, casting, order, ...])	Логарифм по основанию 2 от входного массива.
`log10`(x, /[, out, where, casting, order, ...])	Возвращает десятичный логарифм входного массива поэлементно.
`expm1`(x, /[, out, where, casting, order, ...])	Вычисляет e^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, ...])	Возвращает наибольший общий делитель двух чисел.
`lcm`(x1, x2, /[, out, where, casting, order, ...])	Возвращает наименьшее общее кратное двух чисел.

Подсказка

Необязательные выходные аргументы могут помочь вам сэкономить память при больших вычислениях. Если ваши массивы большие, сложные выражения могут занимать больше времени, чем необходимо, из-за создания и (позже) уничтожения временных областей вычислений. Например, выражение 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`, корректно выбирая квадрант.
`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, ...])	Вычислите значение истинности x1 ИСКЛЮЧАЮЩЕЕ ИЛИ x2 поэлементно.
`logical_not`(x, /[, out, where, casting, ...])	Вычислите значение истинности НЕ x поэлементно.

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

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

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

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

Подсказка

Функция Python max() найдет максимум по одномерному массиву, но сделает это с помощью более медленного последовательного интерфейса. Метод reduce функции ufunc maximum намного быстрее. Кроме того, метод 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, где бит знака установлен (меньше нуля).
`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, ...])	Возвращает целую часть числа, поэлементно.