API UFunc

Константы

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 не равно true (т.е. это не цикл для массива OBJECT). Требует использования NPY_BEGIN_THREADS_DEF в области объявления переменной.

NPY_LOOP_END_THREADS

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

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 равен true, то код перенаправляется к метке 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 вместо значений типа данных dtype. Это позволяет регистрировать цикл 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 находится набор функций, специфичных для типа данных, которые определяют основную функциональность для каждого поддерживаемого типа. Эти функции должны вычислять основную функцию раз. Дополнительные данные могут быть переданы и использованы во время вычисления. Эта функция позволяет использовать некоторые общие функции в качестве этих основных циклических функций. Общая функция содержит весь код, необходимый для указания переменных в нужное место и настройки вызова функции. Общая функция предполагает, что фактическая функция для вызова передается в качестве дополнительных данных и вызывает ее с правильными значениями. Все эти функции подходят для размещения непосредственно в массиве функций, хранящемся в члене functions структуры 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-мерные функции для 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-мерные функции для 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-го измерения с одним входом, одним выходом и двумя входами, одним выходом для типа данных 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-мерной функции, используемое динамическими ufunc, созданными 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)

Это константы и функции для доступа к C-API ufunc из модулей расширения точно так же, как можно получить доступ к 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.