UFunc API

Константы

UFUNC_ERR_{HANDLER}

{HANDLER} может быть IGNORE, WARN, RAISE или CALL

UFUNC_{THING}_{ERR}

{THING} может быть MASK, SHIFT или FPE, а {ERR} может быть DIVIDEBYZERO, OVERFLOW, UNDERFLOW и INVALID.

PyUFunc_{VALUE}

{VALUE} может быть Один (1), Ноль (0) или Нет (-1)

Макросы

NPY_LOOP_BEGIN_THREADS

Используется в коде универсальной функции для освобождения блокировки GIL Python только в том случае, если loop->obj не истинно (т.е. это не цикл обработки массива OBJECT). Требует использования NPY_BEGIN_THREADS_DEF в области объявления переменных.

NPY_LOOP_END_THREADS

Используется в коде универсальной функции для повторного захвата блокировки GIL Python, если она была освобождена (потому что loop->obj не был истинным).

UFUNC_CHECK_ERROR(loop)

Макрос, используемый во внутренней проверке ошибок и переходе к метке fail при обнаружении ошибки. Этот макрос требует метки fail в текущем блоке кода. Переменная loop должна содержать по крайней мере члены (obj, errormask и errorobj). Если loop ->obj отлично от нуля, то вызывается PyErr_Occurred () (что означает, что должна быть захвачена блокировка GIL). Если loop ->obj равно нулю, то если loop ->errormask отлично от нуля, вызывается PyUFunc_checkfperr с аргументами loop ->errormask и loop ->errobj. Если результат этой проверки регистров IEEE с плавающей точкой истинный, то код перенаправляется на метку fail, которая должна быть определена.

UFUNC_CHECK_STATUS(ret)

Устарело: используйте npy_clear_floatstatus из npy_math.h вместо этого.

Макрос, который расширяется до платформозависимого кода. Переменная ret может быть любым целым числом. UFUNC_FPE_{ERR} биты устанавливаются в ret в соответствии со статусом соответствующих флагов ошибок процессора с плавающей точкой.

Функции

PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int unused)

Создает новую универсальную функцию с широковещательной рассылкой из необходимых переменных. Каждая функция ufunc строится вокруг понятия операции по элементам. Каждый объект ufunc содержит указатели на циклы 1-d, реализующие базовую функциональность для каждого поддерживаемого типа.

Примечание

Аргументы func, data, types, name и doc не копируются функцией PyUFunc_FromFuncAndData. Вызывающий код должен убедиться, что память, используемая этими массивами, не освобождается до тех пор, пока объект ufunc не будет уничтожен.

Параметры:

func – Должен быть массивом длиной ntypes, содержащим PyUFuncGenericFunction элементы. Эти элементы являются указателями на функции, которые фактически реализуют базовую (элемент-по-элементу) функцию раз. data – Должен быть NULL или указателем на массив размером ntypes. Этот массив может содержать произвольные дополнительные данные, которые будут переданы соответствующей функции цикла 1-d в массиве func. types – Должен иметь длину (nin + nout) * ntypes, и он содержит типы данных (только встроенные), с которыми может работать соответствующая функция в массиве func. ntypes – Сколько различных типов данных «подписей» реализовала функция ufunc. nin – Количество входных данных для этой операции. nout – Количество выходов name – Название для функции ufunc. Указание имени «add» или «multiply» включает специальное поведение для целочисленных сводок, когда не указан тип данных. Если тип входных данных является целочисленным (или булевым) типом данных, меньшим размера типа int_, он будет внутри преобразованы к типу int_ (или uint). doc – Позволяет передать строку документации для хранения с функцией ufunc. Строка документации не должна содержать имя функции или сигнатуру вызова, так как это будет динамически определяться из объекта и доступно при обращении к атрибуту __doc__ функции ufunc. unused – Неиспользуемый, присутствует для обратной совместимости C-API.

PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int unused, char *signature)

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

Параметры:	signature – Подпись для новой функции gufunc. Установка ее в значение NULL эквивалентна вызову PyUFunc_FromFuncAndData. Создается копия строки, поэтому переданный буфер можно освободить.

int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data)

Эта функция позволяет пользователю зарегистрировать цикл 1-d с уже созданной функцией ufunc для использования всякий раз, когда функция ufunc вызывается с любым из ее входных аргументов как пользовательский тип данных. Это необходимо для работы функций ufunc с встроенными типами данных. Тип данных должен быть предварительно зарегистрирован в системе NumPy. Цикл передается в виде function. Этот цикл может принимать произвольные данные, которые должны быть переданы в виде data. Типы данных, необходимые циклу, передаются в виде arg_types, которые должны быть указателем на память, по крайней мере, такой же большой, как ufunc->nargs.

int PyUFunc_RegisterLoopForDescr(PyUFuncObject* ufunc, PyArray_Descr* userdtype, PyUFuncGenericFunction function, PyArray_Descr** arg_dtypes, void* data)

Эта функция ведет себя как функция PyUFunc_RegisterLoopForType выше, за исключением того, что она позволяет пользователю зарегистрировать цикл 1-d с использованием объектов PyArray_Descr вместо значений num типа данных. Это позволяет зарегистрировать цикл 1-d для структурных массивов и пользовательских типов данных вместо скалярных типов данных.

int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, PyUFuncGenericFunction newfunc, int* signature, PyUFuncGenericFunction* oldfunc)

Заменяет цикл 1-d, соответствующий заданной signature в уже созданной функции ufunc, новым циклом 1-d newfunc. Возвращает старую функцию цикла 1-d в oldfunc. Возвращает 0 при успехе и -1 при ошибке. Эта функция работает только со встроенными типами (используйте PyUFunc_RegisterLoopForType для пользовательских типов). Подпись — это массив номеров типов данных, указывающих входные данные, за которыми следуют выходные данные, предполагаемые циклом 1-d.

int PyUFunc_GenericFunction(PyUFuncObject* self, PyObject* args, PyObject* kwds, PyArrayObject** mps)

Общий вызов функции ufunc. Функция ufunc передается как self, аргументы функции ufunc как args и kwds. Аргумент mps — массив указателей на PyArrayObject, значения которых отбрасываются, и которые получают преобразованные входные аргументы, а также выходные данные функции ufunc при возвращении успеха. Пользователь отвечает за управление этим массивом и получает новую ссылку для каждого массива в mps. Общее количество массивов в mps задается self ->nin + self ->nout.

Возвращает 0 при успехе, -1 при ошибке.

int PyUFunc_checkfperr(int errmask, PyObject* errobj)

Простой интерфейс к поддержке проверки флагов ошибок IEEE. Аргумент errmask — маска UFUNC_MASK_{ERR} битовых масок, указывающих, какие ошибки проверять (и как их проверять). errobj должен быть кортежем Python с двумя элементами: строкой, содержащей имя, которое будет использоваться при любом сообщении об ошибке, и либо вызываемым объектом Python (функцией обратного вызова), либо Py_None. Вызываемый объект будет использоваться только если UFUNC_ERR_CALL установлен как желаемый метод проверки ошибок. Эта процедура управляет блокировкой GIL и безопасна для вызова даже после освобождения блокировки GIL. Если в оборудовании с совместимой IEEE-архитектурой определяется ошибка, возвращается -1, в противном случае — 0.

void PyUFunc_clearfperr()

Очистка флагов ошибок IEEE.

void PyUFunc_GetPyValues(char* name, int* bufsize, int* errmask, PyObject** errobj)

Получение значений Python, используемых для обработки функции ufunc, из области локального хранилища потока, если не были установлены значения по умолчанию, в этом случае поиск по имени пропускается. Имя помещается как строка в первый элемент *errobj. Второй элемент — это найденная функция для вызова при обратном вызове ошибки. Значение найденного размера буфера для использования передается в bufsize, а значение маски ошибки помещается в errmask.

Общие функции

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

void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_f_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_g_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_F_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_G_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_e_e(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_e_e_As_f_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_e_e_As_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Функции ядра 1-d для ufunc, специфичные для типа, где каждый расчёт получается путём вызова функции, принимающей один аргумент и возвращающей один результат. Эта функция передаётся в func. Буквы соответствуют dtypechar’ам поддерживаемых типов данных (e — половина, f — float, d — double, g — long double, F — cfloat, D — cdouble, G — clongdouble). Аргумент func должен поддерживать такую же сигнатуру. Варианты _As_X_X предполагают ndarray’ы одного типа данных, но преобразуют значения для использования базовой функции, принимающей другой тип данных. Таким образом, PyUFunc_f_f_As_d_d использует ndarray’ы типа данных NPY_FLOAT, но вызывает C-функцию, которая принимает double и возвращает double.

void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_ff_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_gg_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_FF_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_GG_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_ee_e(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_ee_e_As_ff_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_ee_e_As_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Функции ядра 1-d для ufunc, специфичные для типа, где каждый расчёт получается путём вызова функции, принимающей два аргумента и возвращающей один результат. Базовая функция для вызова передаётся как func. Буквы соответствуют dtypechar’ам конкретного типа данных, поддерживаемого функцией общего назначения. Аргумент func должен поддерживать соответствующую сигнатуру. Варианты _As_XX_X предполагают ndarray’ы одного типа данных, но преобразуют значения на каждой итерации цикла для использования базовой функции, принимающей другой тип данных.

void PyUFunc_O_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

void PyUFunc_OO_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Функции ядра 1-d, принимающие один вход и выдающие один выход, и два входа и один выход, для типа данных NPY_OBJECT. Эти функции обрабатывают проблемы с счётчиками ссылок и возвращают результат при ошибке. Фактическая вызываемая функция — func, и она должна принимать вызовы со сигнатурой (PyObject*) (PyObject*) для PyUFunc_O_O или (PyObject*)(PyObject *, PyObject *) для PyUFunc_OO_O.

void PyUFunc_O_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Эта функция ядра 1-d общего назначения предполагает, что func — это строка, представляющая метод входного объекта. На каждой итерации цикла из массива извлекается Python-объект, и вызывается его метод func, возвращая результат в массив вывода.

void PyUFunc_OO_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Эта функция ядра 1-d общего назначения предполагает, что func — это строка, представляющая метод входного объекта, принимающий один аргумент. Первый аргумент в args — это метод, функция которого вызывается, а второй аргумент в args — это аргумент, передаваемый функции. Результат функции сохраняется в третьем элементе args.

void PyUFunc_On_Om(char** args, npy_intp* dimensions, npy_intp* steps, void* func)

Это функция ядра 1-d, используемая динамическими ufunc, созданными umath.frompyfunc(function, nin, nout). В этом случае func — указатель на структуру PyUFunc_PyFuncData, которая имеет определение

PyUFunc_PyFuncData

typedef struct {
    int nin;
    int nout;
    PyObject *callable;
} PyUFunc_PyFuncData;

На каждой итерации цикла объекты nin входных данных извлекаются из своих массивов объектов и помещаются в кортеж аргументов, вызываемый Python callable с входными аргументами, а выходные данные nout помещаются в свои массивы объектов.

Импортирование API

PY_UFUNC_UNIQUE_SYMBOL

NO_IMPORT_UFUNC

void import_ufunc(void)

Это константы и функции для доступа к ufunc C-API из модулей расширения точно так же, как можно получить доступ к массивному C-API. Функция import_ufunc () должна всегда вызываться (в подпрограмме инициализации модуля расширения). Если ваш модуль расширения находится в одном файле, этого достаточно. Две другие константы полезны, если ваш модуль расширения использует несколько файлов. В этом случае задайте PY_UFUNC_UNIQUE_SYMBOL чему-то уникальному для вашего кода, а затем в файлах исходного кода, которые не содержат функцию инициализации модуля, но всё ещё нуждаются в доступе к API UFUNC, задайте PY_UFUNC_UNIQUE_SYMBOL тому же самому имени, что и ранее, а также задайте NO_IMPORT_UFUNC.

C-API на самом деле представляет собой массив указателей на функции. Этот массив создаётся (и к нему ссылается глобальная переменная) функцией import_ufunc. Глобальная переменная либо статически определена, либо доступна другим файлам в зависимости от состояния PY_UFUNC_UNIQUE_SYMBOL и NO_IMPORT_UFUNC.