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 только в том случае, если loop->obj не истинно (т.е. это не цикл обработки массива OBJECT). Требуется использование NPY_BEGIN_THREADS_DEF в области объявления переменных.

NPY_LOOP_END_THREADS

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

UFUNC_CHECK_ERROR(loop)

Внутренний макрос для проверки ошибок и перехода к метке fail при обнаружении ошибки. Этот макрос требует метки fail в текущем блоке кода. Переменная loop должна содержать как минимум члены (obj, errormask и errorobj). Если loop ->obj отлично от нуля, то вызывается PyErr_Occurred () (это означает, что блокировка интерпретатора Python должна быть захвачена). Если 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 вместо значений типа данных 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 установлено в качестве желаемого метода проверки ошибок. Эта процедура управляет блокировкой интерпретатора Python и безопасна для вызова даже после освобождения блокировки интерпретатора Python. Если обнаружена ошибка в оборудовании, совместимом с 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-d, специфичные для типа, для ufunc, где каждое вычисление получается путем вызова функции, принимающей один входной аргумент и возвращающей один выходной. Эта функция передаётся в func. Буквы соответствуют dtypechar'ам поддерживаемых типов данных (e — полуточная, f — плавающая точка, d — двойная, g — длинная двойная, F — комплексная плавающая точка, D — комплексная двойная, G — комплексная длинная двойная). Аргумент 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-вызываемый объект вызывается с входными аргументами, а 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.