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} может быть One (1), Zero (0) или None (-1)

Макросы

NPY_LOOP_BEGIN_THREADS

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

NPY_LOOP_END_THREADS

Используется в коде универсальной функции для повторного получения блокировки Python GIL, если она была освобождена (потому что 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 check_return)

Создает новую универсальную функцию вещания из необходимых переменных. Каждая 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. check_return – Не используется и присутствует для обратной совместимости C-API. Соответствующее целое число check_return существует в структуре ufunc, и оно устанавливается с этим значением при создании объекта ufunc.

PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func,

void** data, char* types, int ntypes, int nin, int nout, int identity,

char* name, char* doc, int check_return, 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 вместо значений типа данных dtype. Это позволяет зарегистрировать цикл 1-d для структурированных массивов данных и пользовательских типов данных вместо скалярных типов данных.

int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc,

PyUFuncGenericFunction newfunc, int* signature,

PyUFuncGenericFunction* oldfunc)

Заменяет цикл 1-d, соответствующий данной signature в уже созданной ufunc, новым циклом 1-d newfunc. Возвращает старый цикл 1-d function в 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-мерные функции для ufuncs, где каждый вычисление получается путем вызова функции, принимающей один входной аргумент и возвращающей один выходной. Эта функция передается в func. Буквы соответствуют dtypechar’ам поддерживаемых типов данных ( e - half, 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-мерные функции для ufuncs, где каждое вычисление получается путем вызова функции, принимающей два входных аргумента и возвращающей один выходной. Базовая функция для вызова передается как 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-мерная функция ядра предполагает, что func — это строка, представляющая метод входного объекта. На каждой итерации цикла объект Python извлекается из массива, и вызывается его метод func, возвращая результат в выходной массив.

void PyUFunc_OO_O_method(char** args, npy_intp* dimensions,

npy_intp* steps, void* func)

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

void PyUFunc_On_Om(char** args, npy_intp* dimensions,

npy_intp* steps, void* func)

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

PyUFunc_PyFuncData

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

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

Импорт API

PY_UFUNC_UNIQUE_SYMBOL

NO_IMPORT_UFUNC

void import_ufunc(void)

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

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