Array API#

Признак первоклассного интеллекта — способность удерживать в уме две
противоположные идеи в уме одновременно, и все еще сохранять
способность функционировать.
— Ф. Скотт Фицджеральд

Для успешной технологии реальность должна преобладать над общественным
отношения, ибо Природу нельзя обмануть.
— Ричард Ф. Фейнман

Структура массива и доступ к данным#

Эти макросы обращаются к PyArrayObject члены структуры и определены в ndarraytypes.h. Входной аргумент, arr, может быть любым PyObject* который напрямую интерпретируется как PyArrayObject* (любой экземпляр PyArray_Type и его подтипы).

int PyArray_NDIM(PyArrayObject *arr)#: Количество измерений в массиве.

int PyArray_FLAGS(PyArrayObject *arr)#: Возвращает целое число, представляющее array-flags.

int PyArray_TYPE(PyArrayObject *arr)#: Вернуть (встроенный) номер типа для элементов этого массива.

int PyArray_Pack(const PyArray_Descr *descr, void *item, const PyObject *значение)#

Добавлено в версии 2.0.

Устанавливает местоположение в памяти item типа данных descr to value.

Функция эквивалентна установке одного элемента массива с помощью присваивания в Python. Возвращает 0 при успехе и -1 с установленной ошибкой при неудаче.

Примечание

Если descr имеет NPY_NEEDS_INIT флаг установлен, данные должны быть корректными или память обнулена.

int PyArray_SETITEM(PyArrayObject *arr, void *itemptr, PyObject *obj)#: Преобразовать obj и поместить его в ndarray, arr, в месте, указанном itemptr. Возвращает -1 при возникновении ошибки или 0 при успехе.

Примечание

В общем случае предпочтительно использование PyArray_Pack при обработке произвольных объектов Python. Setitem, например, не может обрабатывать произвольные преобразования между различными dtypes.

void PyArray_ENABLEFLAGS(PyArrayObject *arr, int флаги)#: Включает указанные флаги массива. Эта функция не выполняет проверку и предполагает, что вы знаете, что делаете.

void PyArray_CLEARFLAGS(PyArrayObject *arr, int флаги)#: Очищает указанные флаги массива. Эта функция не выполняет проверку и предполагает, что вы знаете, что делаете.

void *PyArray_DATA(PyArrayObject *arr)#

char *PyArray_BYTES(PyArrayObject *arr)#: Эти два макроса похожи и получают указатель на буфер данных массива. Первый макрос может (и должен быть) присвоен конкретному указателю, тогда как второй предназначен для общей обработки. Если вы не гарантировали непрерывный и/или выровненный массив, убедитесь, что понимаете, как получить доступ к данным в массиве, чтобы избежать проблем с памятью и/или выравниванием.

npy_intp *PyArray_DIMS(PyArrayObject *arr)#: Возвращает указатель на размеры/форму массива. Количество элементов соответствует количеству измерений массива. Может возвращать NULL для 0-мерных массивов.

npy_intp *PyArray_SHAPE(PyArrayObject *arr)#: Синоним для PyArray_DIMS, назван для согласованности с shape использование в Python.

npy_intp *PyArray_STRIDES(PyArrayObject *arr)#: Возвращает указатель на шаги массива. Количество элементов соответствует количеству измерений массива.

npy_intp PyArray_DIM(PyArrayObject *arr, int n)#: Возвращает форму в n \(^{\textrm{th}}\) измерение.

npy_intp PyArray_STRIDE(PyArrayObject *arr, int n)#: Возвращает шаг в n \(^{\textrm{th}}\) измерение.

npy_intp PyArray_ITEMSIZE(PyArrayObject *arr)#

Возвращает размер элемента для элементов этого массива.

Обратите внимание, что в старом API, который был устаревшим в версии 1.7, эта функция имела тип возвращаемого значения int.

npy_intp PyArray_SIZE(PyArrayObject *arr)#: Возвращает общий размер (в количестве элементов) массива.

npy_intp PyArray_Size(PyObject *obj)#: Возвращает 0, если obj не является подклассом ndarray. В противном случае, возвращает общее количество элементов в массиве. Более безопасная версия PyArray_SIZE (obj).

npy_intp PyArray_NBYTES(PyArrayObject *arr)#: Возвращает общее количество байтов, занимаемых массивом.

PyObject *PyArray_BASE(PyArrayObject *arr)#

Возвращает базовый объект массива. В большинстве случаев это означает объект, которому принадлежит память, на которую указывает массив.

Если вы создаёте массив с помощью C API и указываете свою собственную память, вам следует использовать функцию PyArray_SetBaseObject чтобы установить базу на объект, который владеет памятью.

Если NPY_ARRAY_WRITEBACKIFCOPY флаг установлен, он имеет другое значение, а именно base — это массив, в который текущий массив будет скопирован при разрешении копирования. Эта перегрузка свойства base для двух функций, вероятно, изменится в будущей версии NumPy.

PyArray_Descr *PyArray_DESCR(PyArrayObject *arr)#: Возвращает заимствованную ссылку на свойство dtype массива.

PyArray_Descr *PyArray_DTYPE(PyArrayObject *arr)#: Синоним для PyArray_DESCR, названный для согласованности с использованием ‘dtype’ в Python.

PyObject *PyArray_GETITEM(PyArrayObject *arr, void *itemptr)#

Получить объект Python встроенного типа из ndarray, arr, в месте, на которое указывает itemptr. Возвращает NULL при неудаче.

numpy.ndarray.item идентичен PyArray_GETITEM.

int PyArray_FinalizeFunc(PyArrayObject *arr, PyObject *obj)#: Функция, на которую указывает PyCapsule __array_finalize__. Первый аргумент — это вновь созданный подтип. Второй аргумент (если не NULL) — это «родительский» массив (если массив был создан с использованием срезов или какой-либо другой операции, где присутствует чётко различимый родитель). Эта процедура может делать всё, что захочет. Она должна возвращать -1 при ошибке и 0 в противном случае.

Доступ к данным#

Эти функции и макросы предоставляют лёгкий доступ к элементам ndarray из C. Они работают для всех массивов. Однако вам может потребоваться осторожность при доступе к данным в массиве, если он не в порядке байтов машины, не выровнен или не доступен для записи. Другими словами, обязательно уважайте состояние флагов, если вы не знаете, что делаете, или ранее гарантировали массив, доступный для записи, выровненный и в порядке байтов машины, используя PyArray_FromAny. Если вы хотите обрабатывать все типы массивов, функция copyswap для каждого типа полезна для обработки некорректных массивов. Некоторые платформы (например, Solaris) не любят невыровненные данные и завершатся с ошибкой, если вы разыменуете невыровненный указатель. Другие платформы (например, x86 Linux) просто будут работать медленнее с невыровненными данными.

void *PyArray_GetPtr(PyArrayObject *aobj, npy_intp *ind)#: Возвращает указатель на данные ndarray, aobj, по N-мерному индексу, заданному c-массивом, ind, (который должен быть не менее aobj ->nd в размере). Возможно, вы захотите привести возвращённый указатель к типу данных ndarray.

void *PyArray_GETPTR1(PyArrayObject *obj, npy_intp i)#

void *PyArray_GETPTR2(PyArrayObject *obj, npy_intp i, npy_intp j)#

void *PyArray_GETPTR3(PyArrayObject *obj, npy_intp i, npy_intp j, npy_intp k)#

void *PyArray_GETPTR4(PyArrayObject *obj, npy_intp i, npy_intp j, npy_intp k, npy_intp l)#: Быстрый встроенный доступ к элементу по заданным координатам в ndarray, obj, которые должны иметь соответственно 1, 2, 3 или 4 измерения (это не проверяется). Соответствующие i, j, k, и l координаты могут быть любыми целыми числами, но будут интерпретироваться как npy_intp. Возможно, потребуется привести возвращаемый указатель к типу данных ndarray.

Создание массивов#

С нуля#

PyObject *PyArray_NewFromDescr(PyTypeObject *подтип, PyArray_Descr *descr, int nd, npy_intp const *dims, npy_intp const *strides, void *данные, int флаги, PyObject *obj)#

Эта функция крадет ссылку на descr. Самый простой способ получить его — использовать PyArray_DescrFromType.

Это основная функция создания массивов. Большинство новых массивов создаются с помощью этой гибкой функции.

Возвращаемый объект является объектом типа Python подтип, который должен быть подтипом PyArray_Type. Массив имеет nd размерности, описанные dims. Дескриптор типа данных нового массива descr.

Если подтип является подклассом массива вместо базового &PyArray_Type, затем obj является объектом для передачи в __array_finalize__ метод подкласса.

Если данные является NULL, тогда будет выделена новая неинициализированная память и флаги может быть ненулевым, чтобы указать массив в стиле Fortran. Используйте PyArray_FILLWBYTE для инициализации памяти.

Если данные не является NULL, то предполагается, что он указывает на память, которая будет использоваться для массива, и флаги аргумент используется как новые флаги для массива (кроме состояния NPY_ARRAY_OWNDATA, NPY_ARRAY_WRITEBACKIFCOPY флаг нового массива будет сброшен).

Кроме того, если данные не NULL, тогда strides также может быть предоставлен. Если strides является NULL, тогда шаги массива вычисляются как C-стиль непрерывный (по умолчанию) или Fortran-стиль непрерывный (флаги ненулевой для данные = NULL или флаги & NPY_ARRAY_F_CONTIGUOUS ненулевой не-NULL данные). Любой предоставленный dims и strides копируются во вновь выделенные массивы размерностей и шагов для нового объекта массива.

PyArray_CheckStrides может помочь проверить не- NULL информация о шаге.

Если data предоставлен, он должен оставаться активным на протяжении жизни массива. Один из способов управления этим — через PyArray_SetBaseObject

PyObject *PyArray_NewLikeArray(PyArrayObject *прототип, NPY_ORDER порядок, PyArray_Descr *descr, int subok)#

Эта функция крадет ссылку на descr если он не NULL. Эта процедура создания массива позволяет удобно создавать новый массив, соответствующий формам и расположению памяти существующего массива, возможно, изменяя расположение и/или тип данных.

Когда порядок является NPY_ANYORDER, порядок результата NPY_FORTRANORDER if прототип является массивом Fortran, NPY_CORDER в противном случае. Когда порядок является NPY_KEEPORDER, порядок результата соответствует порядку прототип, даже когда оси прототип не находятся в порядке C или Fortran.

Если descr равен NULL, тип данных прототип используется.

Если subok равен 1, вновь созданный массив будет использовать подтип прототип для создания нового массива, иначе он создаст массив базового класса.

PyObject *PyArray_New(PyTypeObject *подтип, int nd, npy_intp const *dims, int type_num, npy_intp const *strides, void *данные, int itemsize, int флаги, PyObject *obj)#: Это похоже на PyArray_NewFromDescr (…) за исключением того, что вы указываете дескриптор типа данных с type_num и itemsize, где type_num соответствует встроенному (или пользовательскому) типу. Если тип всегда имеет одинаковое количество байтов, то itemsize игнорируется. В противном случае itemsize указывает конкретный размер этого массива.

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

Если данные передаются в PyArray_NewFromDescr или PyArray_New, эта память не должна освобождаться до удаления нового массива. Если эти данные получены из другого объекта Python, это можно сделать с помощью Py_INCREF на этом объекте и установке базового члена нового массива для указания на этот объект. Если шаги переданы, они должны быть согласованы с размерами, размером элемента и данными массива.

PyObject *PyArray_SimpleNew(int nd, npy_intp const *dims, int typenum)#: Создание нового неинициализированного массива типа, typenum, чей размер в каждом из nd размерности задаются целочисленным массивом, dims. Память для массива не инициализирована (если только typenum не NPY_OBJECT в этом случае каждый элемент в массиве устанавливается в NULL). typenum аргумент позволяет указать любой из встроенных типов данных, таких как NPY_FLOAT или NPY_LONG. Память для массива может быть установлена в ноль при желании с помощью PyArray_FILLWBYTE (return_object, 0). Эта функция не может быть использована для создания массива гибкого типа (не указан itemsize).

PyObject *PyArray_SimpleNewFromData(int nd, npy_intp const *dims, int typenum, void *данные)#: Создать обёртку массива вокруг данные указываемый данным указателем. Флаги массива будут иметь значение по умолчанию, что область данных корректна и непрерывна в стиле C. Форма массива задаётся dims c-массив длины nd. Тип данных массива указывается typenum. Если данные поступают из другого объекта Python с подсчётом ссылок, счётчик ссылок на этот объект должен быть увеличен после передачи указателя, и базовый член возвращаемого ndarray должен указывать на объект Python, которому принадлежат данные. Это гарантирует, что предоставленная память не будет освобождена, пока возвращаемый массив существует.

PyObject *PyArray_SimpleNewFromDescr(int nd, npy_int const *dims, PyArray_Descr *descr)#

Эта функция крадет ссылку на descr.

Создать новый массив с предоставленным дескриптором типа данных, descr, формы, определяемой nd и dims.

void PyArray_FILLWBYTE(PyObject *obj, int val)#: Заполните массив, на который указывает obj —который должен быть (подклассом of) ndarray—с содержимым val (оценивается как байт). Этот макрос вызывает memset, поэтому obj должен быть непрерывным.

PyObject *PyArray_Zeros(int nd, npy_intp const *dims, PyArray_Descr *dtype, int fortran)#: Создать новый nd -мерный массив с формой, заданной dims и тип данных, заданный dtype. Если fortran не равно нулю, то создаётся массив в порядке Fortran, иначе создаётся массив в порядке C. Заполните память нулями (или объектом 0, если dtype соответствует NPY_OBJECT ).

PyObject *PyArray_ZEROS(int nd, npy_intp const *dims, int type_num, int fortran)#: Макроформа PyArray_Zeros который принимает номер типа вместо объекта типа данных.

PyObject *PyArray_Empty(int nd, npy_intp const *dims, PyArray_Descr *dtype, int fortran)#: Создать новый nd -мерный массив с формой, заданной dims и тип данных, заданный dtype. Если fortran не равно нулю, то создаётся массив в порядке Fortran, иначе создаётся массив в порядке C. Массив не инициализирован, если тип данных не соответствует NPY_OBJECT в этом случае массив заполняется Py_None.

PyObject *PyArray_EMPTY(int nd, npy_intp const *dims, int typenum, int fortran)#: Макроформа PyArray_Empty который принимает номер типа, typenum, вместо объекта типа данных.

PyObject *PyArray_Arange(double начало, double стоп, double шаг, int typenum)#: Создать новый одномерный массив типа данных, typenum, который изменяется от начало to стоп (исключительно) с шагом шаг . Эквивалентно arange (начало, стоп, шаг, dtype).

PyObject *PyArray_ArangeObj(PyObject *начало, PyObject *стоп, PyObject *шаг, PyArray_Descr *descr)#: Создать новый 1-мерный массив с типом данных, определяемым descr, который варьируется от start to stop (исключительно) с шагом step. Эквивалентно arange( start, stop, step, typenum ).

int PyArray_SetBaseObject(PyArrayObject *arr, PyObject *obj)#

Эта функция крадет ссылку to obj и устанавливает его как базовое свойство arr.

Если вы создаёте массив, передавая свой собственный буфер памяти в качестве параметра, вам нужно установить основание свойство для обеспечения соответствующего времени жизни буфера памяти.

Возвращаемое значение равно 0 при успехе, -1 при неудаче.

Если предоставленный объект является массивом, эта функция проходит по цепочке основание указатели, чтобы каждый массив указывал непосредственно на владельца памяти. После установки базы её нельзя изменить на другое значение.

Из других объектов#

PyObject *PyArray_FromAny(PyObject *op, PyArray_Descr *dtype, int минимальная глубина, int max_depth, int требования, PyObject *контекст)#

Это основная функция, используемая для получения массива из любой вложенной последовательности или объекта, предоставляющего интерфейс массива, op. Параметры позволяют указать требуемые dtype, минимум (минимальная глубина) и максимум (max_depth) количество измерений допустимо, и другие требования для массива. Эта функция крадет ссылку к аргументу dtype, который должен быть PyArray_Descr структура, указывающая желаемый тип данных (включая требуемый порядок байтов). dtype аргумент может быть NULL, указывая, что любой тип данных (и порядок байтов) допустим. Если только NPY_ARRAY_FORCECAST присутствует в flags, этот вызов вызовет ошибку, если тип данных не может быть безопасно получен из объекта. Если вы хотите использовать NULL для dtype и убедиться, что массив не свопнут, затем использовать PyArray_CheckFromAny. Значение 0 для любого из параметров глубины приводит к игнорированию параметра. Любой из следующих флагов массива может быть добавлен (например, используя |) для получения требования аргумент. Если ваш код может обрабатывать общие (например, страйдные, с измененным порядком байтов или невыровненные массивы), тогда требования может быть 0. Также, если op если ещё не является массивом (или не предоставляет интерфейс массива), то будет создан новый массив (и заполнен из op используя протокол последовательности). Новый массив будет иметь NPY_ARRAY_DEFAULT как его член flags. контекст аргумент не используется.

NPY_ARRAY_C_CONTIGUOUS: Убедитесь, что возвращаемый массив является C-стиль смежным
NPY_ARRAY_F_CONTIGUOUS: Убедитесь, что возвращаемый массив является смежным в стиле Fortran.
NPY_ARRAY_ALIGNED: Убедитесь, что возвращаемый массив выровнен по соответствующим границам для его типа данных. Выровненный массив имеет указатель данных и каждый множитель шага как кратное коэффициенту выравнивания для дескриптора типа данных.
NPY_ARRAY_WRITEABLE: Убедитесь, что возвращаемый массив доступен для записи.
NPY_ARRAY_ENSURECOPY: Убедитесь, что создана копия op. Если этот флаг отсутствует, данные не копируются, если этого можно избежать.
NPY_ARRAY_ENSUREARRAY: Убедитесь, что результат является ndarray базового класса. По умолчанию, если op является экземпляром подкласса ndarray, возвращается экземпляр того же подкласса. Если установлен этот флаг, вместо этого будет возвращен объект ndarray.
NPY_ARRAY_FORCECAST: Принудительное преобразование к выходному типу, даже если это не может быть сделано безопасно. Без этого флага преобразование данных произойдёт только если оно может быть выполнено безопасно, в противном случае возникает ошибка.
NPY_ARRAY_WRITEBACKIFCOPY: Если op уже является массивом, но не удовлетворяет требованиям, то создается копия (которая будет удовлетворять требованиям). Если этот флаг присутствует и должна быть сделана копия (объекта, который уже является массивом), то соответствующий NPY_ARRAY_WRITEBACKIFCOPY флаг установлен в возвращаемой копии и op сделано только для чтения. Вы должны быть уверены, что вызвали PyArray_ResolveWritebackIfCopy скопировать содержимое обратно в op и op массив снова станет доступным для записи. Если op не доступен для записи изначально, или если это ещё не массив, то возникает ошибка.

Комбинации флагов массива также может быть добавлен.

PyObject *PyArray_CheckFromAny(PyObject *op, PyArray_Descr *dtype, int минимальная глубина, int max_depth, int требования, PyObject *контекст)#: Почти идентично PyArray_FromAny (…) за исключением требования может содержать NPY_ARRAY_NOTSWAPPED (переопределяя спецификацию в dtype) и NPY_ARRAY_ELEMENTSTRIDES что указывает, что массив должен быть выровнен в том смысле, что шаги являются кратными размеру элемента.

PyObject *PyArray_FromArray(PyArrayObject *op, PyArray_Descr *newtype, int требования)#: Частный случай PyArray_FromAny для случая, когда op уже является массивом, но он должен быть определённого newtype (включая порядок байтов) или имеет определенные требования.

PyObject *PyArray_FromStructInterface(PyObject *op)#: Возвращает объект ndarray из объекта Python, который предоставляет __array_struct__ атрибут и следует протоколу интерфейса массива. Если объект не содержит этот атрибут, то заимствованная ссылка на Py_NotImplemented возвращается.

PyObject *PyArray_FromInterface(PyObject *op)#: Возвращает объект ndarray из объекта Python, который предоставляет __array_interface__ атрибут, следующий протоколу интерфейса массива. Если объект не содержит этот атрибут, то заимствованная ссылка на Py_NotImplemented возвращается.

PyObject *PyArray_FromArrayAttr(PyObject *op, PyArray_Descr *dtype, PyObject *контекст)#: Возвращает объект ndarray из объекта Python, который предоставляет __array__ метод. Сторонние реализации __array__ должен принимать dtype и copy именованные аргументы. context не используется.

PyObject *PyArray_ContiguousFromAny(PyObject *op, int typenum, int минимальная глубина, int max_depth)#: Эта функция возвращает (C-стиль) непрерывный и корректный функциональный массив из любой вложенной последовательности или объекта, экспортирующего интерфейс массива. op, (негибкого) типа, заданного перечисленным typenum, минимальной глубины минимальная глубина, и максимальной глубины max_depth. Эквивалентно вызову PyArray_FromAny с требованиями, установленными на NPY_ARRAY_DEFAULT и член type_num аргумента type установлен в typenum.

PyObject *PyArray_ContiguousFromObject(PyObject *op, int typenum, int минимальная глубина, int max_depth)#: Эта функция возвращает корректный C-стиль непрерывный массив из любой вложенной последовательности или объекта, экспортирующего интерфейс массива. Минимальное количество измерений, которое может иметь массив, задается минимальная глубина в то время как максимум max_depth. Это эквивалентно вызову PyArray_FromAny с требованиями NPY_ARRAY_DEFAULT и NPY_ARRAY_ENSUREARRAY.

PyObject *PyArray_FromObject(PyObject *op, int typenum, int минимальная глубина, int max_depth)#: Возвращает выровненный массив с порядком байтов системы из любой вложенной последовательности или объекта, экспортирующего интерфейс массива, op, типа, заданного перечислением typenum. Минимальное количество измерений массива задается min_depth, а максимальное — max_depth. Это эквивалентно вызову PyArray_FromAny с требованиями, установленными на BEHAVED.

PyObject *PyArray_EnsureArray(PyObject *op)#: Эта функция крадет ссылку to op и гарантирует, что op является базовым классом ndarray. Он специально обрабатывает скаляры массивов, но в остальных случаях вызывает PyArray_FromAny ( op, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY, NULL).

PyObject *PyArray_FromString(char *string, npy_intp slen, PyArray_Descr *dtype, npy_intp число, char *sep)#: Создать одномерный ndarray единого типа из двоичных или (ASCII) текстовых данных string длины slen. Тип данных создаваемого массива задаётся dtype. Если num равен -1, то copy всю строку и возвращает массив соответствующего размера, в противном случае, num это количество элементов для copy из строки. Если sep равен NULL (или ""), то интерпретировать строку как байты двоичных данных, иначе преобразовать подстроки, разделенные sep к элементам типа данных dtype. Некоторые типы данных могут быть нечитаемы в текстовом режиме, и будет вызвана ошибка, если это произойдёт. Все ошибки возвращают NULL.

PyObject *PyArray_FromFile(FILE *fp, PyArray_Descr *dtype, npy_intp число, char *sep)#: Создает одномерный ndarray единого типа из двоичного или текстового файла. Открытый указатель файла fp, тип данных создаваемого массива задаётся dtype. Это должно соответствовать данным в файле. Если num равно -1, то читать до конца файла и возвращать массив соответствующего размера, в противном случае, num — это количество элементов для чтения. Если sep равен NULL (или ""), то чтение из файла в бинарном режиме, иначе чтение из файла в текстовом режиме с sep предоставляя разделитель элементов. Некоторые типы массивов нельзя читать в текстовом режиме, в этом случае возникает ошибка.

PyObject *PyArray_FromBuffer(PyObject *buf, PyArray_Descr *dtype, npy_intp count, npy_intp смещение)#: Создать одномерный ndarray единого типа из объекта, buf, который экспортирует протокол буфера (односегментный) (или имеет атрибут __buffer__, возвращающий объект, экспортирующий протокол буфера). Сначала будет попытка использовать записываемый буфер, затем буфер только для чтения. NPY_ARRAY_WRITEABLE флаг возвращаемого массива будет отражать, какой из них был успешным. Предполагается, что данные начинаются с offset байтов от начала места в памяти для объекта. Тип данных в буфере будет интерпретироваться в зависимости от дескриптора типа данных, dtype. Если count отрицательно, то оно будет определено из размера буфера и запрошенного itemsize, в противном случае, count указывает, сколько элементов должно быть преобразовано из буфера.

int PyArray_CopyInto(PyArrayObject *dest, PyArrayObject *src)#: Копировать из исходного массива, src, в целевой массив, dest, выполняя преобразование типа данных при необходимости. Если возникает ошибка, возвращает -1 (иначе 0). Форма src должны быть транслируемы к форме dest. NumPy проверяет перекрытие памяти при копировании двух массивов.

int PyArray_CopyObject(PyArrayObject *dest, PyObject *src)#: Присвоить объект src в массив NumPy dest согласно правилам приведения массивов. Это в основном идентично PyArray_FromAny, но присваивает напрямую выходному массиву. Возвращает 0 при успехе и -1 при неудачах.

PyArrayObject *PyArray_GETCONTIGUOUS(PyObject *op)#: Если op уже (в стиле C) непрерывный и хорошо себя ведущий, то просто возвращает ссылку, иначе возвращает (непрерывную и хорошо себя ведущую) копию массива. Параметр op должен быть (подклассом) ndarray, и проверка этого не выполняется.

PyObject *PyArray_FROM_O(PyObject *obj)#: Преобразовать obj в ndarray. Аргументом может быть любая вложенная последовательность или объект, экспортирующий интерфейс массива. Это макроформа PyArray_FromAny используя NULL, 0, 0, 0 для других аргументов. Ваш код должен уметь обрабатывать любой дескриптор типа данных и любую комбинацию флагов данных для использования этого макроса.

PyObject *PyArray_FROM_OF(PyObject *obj, int требования)#: Аналогично PyArray_FROM_O за исключением того, что может принимать аргумент типа требования указывая свойства, которыми должен обладать результирующий массив. Доступные требования, которые могут быть применены: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_NOTSWAPPED, NPY_ARRAY_ENSURECOPY, NPY_ARRAY_WRITEBACKIFCOPY, NPY_ARRAY_FORCECAST, и NPY_ARRAY_ENSUREARRAY. Стандартные комбинации флагов также могут использоваться:

PyObject *PyArray_FROM_OT(PyObject *obj, int typenum)#: Аналогично PyArray_FROM_O за исключением того, что может принимать аргумент typenum указывая тип-номер возвращаемого массива.

PyObject *PyArray_FROM_OTF(PyObject *obj, int typenum, int требования)#: Комбинация PyArray_FROM_OF и PyArray_FROM_OT позволяя как typenum и флаги аргумент должен быть предоставлен.

PyObject *PyArray_FROMANY(PyObject *obj, int typenum, int min, int max, int требования)#: Аналогично PyArray_FromAny за исключением того, что тип данных указывается с помощью номера типа. PyArray_DescrFromType (typenum) передается напрямую в PyArray_FromAny. Этот макрос также добавляет NPY_ARRAY_DEFAULT к требованиям, если NPY_ARRAY_ENSURECOPY передается в качестве требований.

PyObject *PyArray_CheckAxis(PyObject *obj, int *ось, int требования)#: Инкапсулирует функциональность функций и методов, которые принимают ключевое слово axis= и правильно работают с None как аргументом оси. Входной массив obj, в то время как *axis является преобразованным целым числом (так что *axis == NPY_RAVEL_AXIS является значением None), и requirements даёт необходимые свойства obj. Выходные данные — это преобразованная версия входных данных, чтобы требования были выполнены, и, если необходимо, произошло сглаживание. На выходе отрицательные значения *axis преобразуются, и новое значение проверяется на соответствие форме obj.

Работа с типами#

Общая проверка типа Python#

int PyArray_Check(PyObject *op)#: Вычисляет true, если op является объектом Python, тип которого является подтипом PyArray_Type.

int PyArray_CheckExact(PyObject *op)#: Вычисляет true, если op является объектом Python типа PyArray_Type.

int PyArray_HasArrayInterface(PyObject *op, PyObject *выход)#: Если op реализует любую часть интерфейса массива, тогда out будет содержать новую ссылку на вновь созданный ndarray с использованием интерфейса или out будет содержать NULL если произошла ошибка во время преобразования. В противном случае out будет содержать заимствованную ссылку на Py_NotImplemented и условие ошибки не установлено.

int PyArray_HasArrayInterfaceType(PyObject *op, PyArray_Descr *dtype, PyObject *контекст, PyObject *выход)#: Если op реализует любую часть интерфейса массива, тогда out будет содержать новую ссылку на вновь созданный ndarray с использованием интерфейса или out будет содержать NULL если произошла ошибка при преобразовании. В противном случае out будет содержать заимствованную ссылку на Py_NotImplemented, и условие ошибки не установлено. Эта версия позволяет установить dtype в части интерфейса массива, которая ищет __array__ атрибут. контекст не используется.

int PyArray_IsZeroDim(PyObject *op)#: Вычисляет true, если op является экземпляром (подклассом) PyArray_Type и имеет 0 измерений.

PyArray_IsScalar(op, cls)#: Вычисляет true, если op является экземпляром Py{cls}ArrType_Type.

int PyArray_CheckScalar(PyObject *op)#: Вычисляет true, если op является либо скаляром массива (экземпляром подтипа PyGenericArrType_Type ), либо экземпляр (подкласса) PyArray_Type размерность которого равна 0.

int PyArray_IsPythonNumber(PyObject *op)#: Вычисляет true, если op является экземпляром встроенного числового типа (int, float, complex, long, bool)

int PyArray_IsPythonScalar(PyObject *op)#: Вычисляет true, если op является встроенным скалярным объектом Python (int, float, complex, bytes, str, long, bool).

int PyArray_IsAnyScalar(PyObject *op)#: Вычисляет true, если op является либо объектом скалярного типа Python (см. PyArray_IsPythonScalar) или скаляр массива (экземпляр подтипа PyGenericArrType_Type ).

int PyArray_CheckAnyScalar(PyObject *op)#: Вычисляет true, если op является объектом скалярного типа Python (см. PyArray_IsPythonScalar), скаляр массива (экземпляр подтипа PyGenericArrType_Type) или экземпляр подтипа PyArray_Type размерность которого равна 0.

Аксессоры типа данных#

Некоторые атрибуты дескрипторов могут быть не всегда определены и их следует или нельзя обращаться напрямую.

Изменено в версии 2.0: До NumPy 2.0 ABI был другим, но излишне большим для пользовательских DTypes. Эти методы доступа были добавлены в 2.0 и могут быть перенесены назад (см. Структура PyArray_Descr была изменена).

npy_intp PyDataType_ELSIZE(PyArray_Descr *descr)#: Размер элемента типа данных (itemsize в Python).

Примечание

Если descr присоединен к массиву PyArray_ITEMSIZE(arr) может использоваться и доступна во всех версиях NumPy.

void PyDataType_SET_ELSIZE(PyArray_Descr *descr, npy_intp размер)#: Позволяет установить itemsize, это only актуально для строковых/байтовых типов данных, так как это текущий шаблон для определения нового размера.

npy_intp PyDataType_ALIGNMENT(PyArray_Descr *descr)#: Выравнивание типа данных.

PyObject *PyDataType_METADATA(PyArray_Descr *descr)#: Метаданные, прикрепленные к типу данных, либо NULL или словарь.

PyObject *PyDataType_NAMES(PyArray_Descr *descr)#: NULL или кортеж имён структурированных полей, прикреплённых к dtype.

PyObject *PyDataType_FIELDS(PyArray_Descr *descr)#

NULL, None, или словарь полей структурированного dtype, этот словарь не должен изменяться, NumPy может изменить способ хранения полей в будущем.

Это тот же словарь, что возвращается np.dtype.fields.

NpyAuxData *PyDataType_C_METADATA(PyArray_Descr *descr)#: C-метаданные объекта, прикреплённые к дескриптору. Этот аксессор обычно не нужен. Поле C-Metadata предоставляет доступ к информации о единице времени datetime/timedelta.

PyArray_ArrayDescr *PyDataType_SUBARRAY(PyArray_Descr *descr)#

Информация о подмассиве dtype, эквивалентном Python np.dtype.base и np.dtype.shape.

Если это не NULL, тогда этот дескриптор типа данных — это массив в стиле C, смежный с другим дескриптором типа данных. Другими словами, каждый элемент, который описывает этот дескриптор, на самом деле является массивом некоторого другого базового дескриптора. Это наиболее полезно в качестве дескриптора типа данных для поля в другом дескрипторе типа данных. Поле fields должно быть NULL если это не- NULL (член fields базового дескриптора может быть не- NULL однако).

тип PyArray_ArrayDescr#

typedef struct {
    PyArray_Descr *base;
    PyObject *shape;
} PyArray_ArrayDescr;

PyArray_Descr *основание#: Объект описателя типа данных базового типа.

PyObject *shape#: Форма (всегда C-style непрерывная) подмассива как кортеж Python.

Проверка типа данных#

Для макросов typenum аргументом является целое число, представляющее перечисленный тип данных массива. Для макросов проверки типа массива аргумент должен быть PyObject* который может быть непосредственно интерпретирован как PyArrayObject*.

int PyTypeNum_ISUNSIGNED(int число)#

int PyDataType_ISUNSIGNED(PyArray_Descr *descr)#

int PyArray_ISUNSIGNED(PyArrayObject *obj)#: Тип представляет беззнаковое целое число.

int PyTypeNum_ISSIGNED(int число)#

int PyDataType_ISSIGNED(PyArray_Descr *descr)#

int PyArray_ISSIGNED(PyArrayObject *obj)#: Тип представляет собой знаковое целое число.

int PyTypeNum_ISINTEGER(int число)#

int PyDataType_ISINTEGER(PyArray_Descr *descr)#

int PyArray_ISINTEGER(PyArrayObject *obj)#: Тип представляет любое целое число.

int PyTypeNum_ISFLOAT(int число)#

int PyDataType_ISFLOAT(PyArray_Descr *descr)#

int PyArray_ISFLOAT(PyArrayObject *obj)#: Тип представляет любое число с плавающей запятой.

int PyTypeNum_ISCOMPLEX(int число)#

int PyDataType_ISCOMPLEX(PyArray_Descr *descr)#

int PyArray_ISCOMPLEX(PyArrayObject *obj)#: Тип представляет любое комплексное число с плавающей точкой.

int PyTypeNum_ISNUMBER(int число)#

int PyDataType_ISNUMBER(PyArray_Descr *descr)#

int PyArray_ISNUMBER(PyArrayObject *obj)#: Тип представляет любое целое, вещественное или комплексное вещественное число.

int PyTypeNum_ISSTRING(int число)#

int PyDataType_ISSTRING(PyArray_Descr *descr)#

int PyArray_ISSTRING(PyArrayObject *obj)#: Тип представляет строковый тип данных.

int PyTypeNum_ISFLEXIBLE(int число)#

int PyDataType_ISFLEXIBLE(PyArray_Descr *descr)#

int PyArray_ISFLEXIBLE(PyArrayObject *obj)#: Тип представляет один из гибких типов массивов ( NPY_STRING, NPY_UNICODE, или NPY_VOID ).

int PyDataType_ISUNSIZED(PyArray_Descr *descr)#

Тип не имеет информации о размере и может быть изменен. Должен вызываться только для гибких типов данных. Типы, прикрепленные к массиву, всегда имеют размер, поэтому макрос в форме массива не существует.

Для структурированных типов данных без полей эта функция теперь возвращает False.

int PyTypeNum_ISUSERDEF(int число)#

int PyDataType_ISUSERDEF(PyArray_Descr *descr)#

int PyArray_ISUSERDEF(PyArrayObject *obj)#: Тип представляет пользовательский тип.

int PyTypeNum_ISEXTENDED(int число)#

int PyDataType_ISEXTENDED(PyArray_Descr *descr)#

int PyArray_ISEXTENDED(PyArrayObject *obj)#: Тип является гибким или пользовательским.

int PyTypeNum_ISOBJECT(int число)#

int PyDataType_ISOBJECT(PyArray_Descr *descr)#

int PyArray_ISOBJECT(PyArrayObject *obj)#: Тип представляет тип данных объекта.

int PyTypeNum_ISBOOL(int число)#

int PyDataType_ISBOOL(PyArray_Descr *descr)#

int PyArray_ISBOOL(PyArrayObject *obj)#: Тип представляет логический тип данных.

int PyDataType_HASFIELDS(PyArray_Descr *descr)#

int PyArray_HASFIELDS(PyArrayObject *obj)#: Тип имеет связанные с ним поля.

int PyArray_ISNOTSWAPPED(PyArrayObject *m)#: Вычисляет истину, если область данных ndarray m находится в порядке байтов машины согласно дескриптору типа данных массива.

int PyArray_ISBYTESWAPPED(PyArrayObject *m)#: Вычисляет истину, если область данных ndarray m является не в порядке байтов машины в соответствии с дескриптором типа данных массива.

npy_bool PyArray_EquivTypes(PyArray_Descr *type1, PyArray_Descr *type2)#: Возвращает NPY_TRUE if type1 и type2 фактически представляют эквивалентные типы для этой платформы (член fortran каждого типа игнорируется). Например, на 32-битных платформах, NPY_LONG и NPY_INT эквивалентны. В противном случае возвращает NPY_FALSE.

npy_bool PyArray_EquivArrTypes(PyArrayObject *a1, PyArrayObject *a2)#: Возвращает NPY_TRUE if a1 и a2 являются массивами с эквивалентными типами для этой платформы.

npy_bool PyArray_EquivTypenums(int typenum1, int typenum2)#: Частный случай PyArray_EquivTypes (…) который не принимает гибкие типы данных, но может быть проще для вызова.

int PyArray_EquivByteorders(int b1, int b2)#: True, если символы порядка байтов b1 и b2 ( NPY_LITTLE, NPY_BIG, NPY_NATIVE, NPY_IGNORE ) либо равны, либо эквивалентны по спецификации собственного порядка байтов. Таким образом, на машине с little-endian NPY_LITTLE и NPY_NATIVE эквивалентны там, где они не эквивалентны на машине с порядком байтов от старшего к младшему.

Преобразование типов данных#

PyObject *PyArray_Cast(PyArrayObject *arr, int typenum)#: В основном для обратной совместимости с Numeric C-API и для простого приведения к негибким типам. Возвращает новый объект массива с элементами arr приведение к типу данных typenum который должен быть одним из перечисленных типов, а не гибким типом.

PyObject *PyArray_CastToType(PyArrayObject *arr, PyArray_Descr *тип, int fortran)#: Возвращает новый массив из тип указано, преобразуя элементы из arr по мере необходимости. Аргумент fortran определяет порядок выходного массива.

int PyArray_CastTo(PyArrayObject *выход, PyArrayObject *в)#

Начиная с версии 1.6, эта функция просто вызывает PyArray_CopyInto, который обрабатывает приведение типов.

Приведение элементов массива в в массив выход. Выходной массив должен быть доступен для записи, иметь целое кратное количество элементов входного массива (можно разместить более одной копии в out) и иметь тип данных, который является одним из встроенных типов. Возвращает 0 при успехе и -1 при возникновении ошибки.

int PyArray_CanCastSafely(int fromtype, int totype)#: Возвращает ненулевое значение, если массив типа данных fromtype может быть приведён к массиву типа данных totype без потери информации. Исключением является то, что 64-битные целые числа могут быть приведены к 64-битным значениям с плавающей точкой, даже если это может привести к потере точности для больших целых чисел, чтобы не распространять использование long doubles без явных запросов. Гибкие типы массивов не проверяются по их длинам с помощью этой функции.

int PyArray_CanCastTo(PyArray_Descr *fromtype, PyArray_Descr *totype)#

PyArray_CanCastTypeTo заменяет эту функцию в NumPy 1.6 и более поздних версиях.

Эквивалентно PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).

int PyArray_CanCastTypeTo(PyArray_Descr *fromtype, PyArray_Descr *totype, NPY_CASTING приведение типов)#: Возвращает ненулевое значение, если массив типа данных fromtype (который может включать гибкие типы) можно безопасно привести к массиву типа данных totype (который может включать гибкие типы) в соответствии с правилом приведения приведение типовЕсли предоставлено, одно выше наибольшего (знакового) целого числа для выборки из распределения (см. выше поведение, если NPY_SAFE_CASTING, это в основном обертка вокруг PyArray_CanCastSafely, но для гибких типов, таких как строки или юникод, он выдает результаты с учетом их размеров. Целочисленные и вещественные типы могут быть приведены к строковому или юникодному типу только с помощью NPY_SAFE_CASTING если строка или тип unicode достаточно велик, чтобы вместить максимальное значение целочисленного/вещественного типа, из которого выполняется приведение.

int PyArray_CanCastArrayTo(PyArrayObject *arr, PyArray_Descr *totype, NPY_CASTING приведение типов)#: Возвращает ненулевое значение, если arr может быть приведен к totype согласно правилу приведения, указанному в приведение типов. Если arr является скаляром массива, его значение учитывается, и ненулевое значение также возвращается, когда значение не переполнится или не будет усечено до целого числа при преобразовании в меньший тип.

PyArray_Descr *PyArray_MinScalarType(PyArrayObject *arr)#

Примечание

С принятием NEP 50 в NumPy 2 эта функция не используется внутренне. В настоящее время она предоставляется для обратной совместимости, но ожидается, что в конечном итоге будет устаревшей.

Если arr является массивом, возвращает его дескриптор типа данных, но если arr является скаляром массива (имеет 0 измерений), он находит тип данных наименьшего размера, в который значение может быть преобразовано без переполнения или усечения до целого числа.

Эта функция не будет понижать комплексные числа до вещественных или что-либо до логических значений, но будет понижать знаковое целое число до беззнакового целого числа, когда скалярное значение положительно.

PyArray_Descr *PyArray_PromoteTypes(PyArray_Descr *type1, PyArray_Descr *type2)#: Находит тип данных наименьшего размера и вида, к которому type1 и type2 могут быть безопасно преобразованы. Эта функция симметрична и ассоциативна. Строковый или юникодный результат будет иметь подходящий размер для хранения максимального значения входных типов, преобразованного в строку или юникод.

PyArray_Descr *PyArray_ResultType(npy_intp narrs, PyArrayObject **arrs, npy_intp ndtypes, PyArray_Descr **dtypes)#

Это применяет продвижение типов ко всем входным массивам и объектам dtype, используя правила NumPy для комбинирования скаляров и массивов, чтобы определить выходной тип для операции с заданным набором операндов. Это тот же тип результата, который производят универсальные функции.

См. документацию numpy.result_type для более подробной информации об алгоритме повышения типа.

int PyArray_ObjectType(PyObject *op, int mintype)#

Эта функция заменена на PyArray_ResultType.

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

PyArrayObject **PyArray_ConvertToCommonType(PyObject *op, int *n)#

Функциональность, предоставляемая этим, в значительной степени заменена итератором NpyIter введен в 1.6, с флагом NPY_ITER_COMMON_DTYPE или с тем же параметром dtype для всех операндов.

Преобразование последовательности объектов Python, содержащихся в op равен нулю, используется размер буфера по умолчанию, в противном случае он указывает, какой размер буфера использовать. Рекомендуются буферы, размер которых является степенью двойки, например 4096 или 8192. PyArray_ResultType. Длина последовательности возвращается в n, и n -длинный массив PyArrayObject указатели являются возвращаемым значением (или NULL если возникает ошибка). Возвращаемый массив должен быть освобождён вызывающей стороной этой процедуры (используя PyDataMem_FREE ) и все объекты массивов в нем DECREF ‘d, иначе произойдет утечка памяти. Пример шаблонного кода ниже демонстрирует типичное использование:

mps = PyArray_ConvertToCommonType(obj, &n);
if (mps==NULL) return NULL;
{code}
<before return>
for (i=0; i<n; i++) Py_DECREF(mps[i]);
PyDataMem_FREE(mps);
{return}

char *PyArray_Zero(PyArrayObject *arr)#: Указатель на вновь созданную память размером arr ->itemsize, который содержит представление 0 для этого типа. Возвращаемый указатель, ret, должна быть освобождена используя PyDataMem_FREE (ret), когда он больше не нужен.

char *PyArray_One(PyArrayObject *arr)#: Указатель на вновь созданную память размером arr ->itemsize, который содержит представление 1 для этого типа. Возвращенный указатель, ret, должна быть освобождена используя PyDataMem_FREE (ret), когда он больше не нужен.

int PyArray_ValidType(int typenum)#: Возвращает NPY_TRUE if typenum представляет допустимый номер типа (встроенный, пользовательский или символьный код). В противном случае эта функция возвращает NPY_FALSE.

Пользовательские типы данных#

void PyArray_InitArrFuncs(PyArray_ArrFuncs *f)#: Инициализировать все указатели функций и члены в NULL.

int PyArray_RegisterDataType(PyArray_DescrProto *dtype)#

Примечание

Начиная с NumPy 2.0 этот API считается устаревшим, новый DType API более мощный и предоставляет дополнительную гибкость. API может быть в конечном итоге устаревшим, но поддержка продолжается на данный момент.

Компиляция для NumPy 1.x и 2.x

NumPy 2.x требует передачи PyArray_DescrProto типизированная структура вместо PyArray_Descr. Это необходимо для разрешения изменений. Чтобы код мог выполняться и компилироваться как на 1.x, так и на 2.x, вам нужно изменить тип вашей структуры на PyArray_DescrProto и добавить:

/* Allow compiling on NumPy 1.x */
#if NPY_ABI_VERSION < 0x02000000
#define PyArray_DescrProto PyArray_Descr
#endif

для совместимости с версией 1.x. Кроме того, структура будет не больше не будет фактическим дескриптором, только его номер типа будет обновлён. После успешной регистрации вы должны получить фактический dtype с помощью:

int type_num = PyArray_RegisterDataType(&my_descr_proto);
if (type_num < 0) {
    /* error */
}
PyArray_Descr *my_descr = PyArray_DescrFromType(type_num);

С этими двумя изменениями код должен компилироваться и работать как на 1.x, так и на 2.x или более поздних версиях.

В маловероятном случае, если вы выделяете структуру dtype в куче, вам следует освободить ее снова в NumPy 2, так как создается копия. Структура не является допустимым объектом Python, поэтому не используйте Py_DECREF на нем.

Зарегистрировать тип данных как новый пользовательский тип данных для массивов. Тип должен иметь большинство своих записей заполненными. Это не всегда проверяется, и ошибки могут вызывать сегфолты. В частности, член typeobj dtype структура должна быть заполнена типом Python, который имеет фиксированный размер элемента, соответствующий члену elsize dtype. Также f член должен иметь необходимые функции: nonzero, copyswap, copyswapn, getitem, setitem и cast (некоторые функции cast могут быть NULL если поддержка не требуется). Чтобы избежать путаницы, вы должны выбрать уникальный символьный код типа, но это не принудительно и не используется внутри.

Возвращается определенный пользователем номер типа, который однозначно идентифицирует тип. Указатель на новую структуру затем может быть получен из PyArray_DescrFromType используя возвращённый номер типа. Возвращается -1, если произошла ошибка. Если это dtype уже зарегистрирован (проверяется только по адресу указателя), то возвращает ранее назначенный номер типа.

Количество пользовательских DTypes, известных numpy, хранится в NPY_NUMUSERTYPES, статическая глобальная переменная, которая является публичной в C API. Доступ к этому символу по своей природе не потокобезопасный. Если по какой-то причине вам нужно использовать этот API в многопоточном контексте, вам потребуется добавить собственную блокировку, NumPy не гарантирует, что новые типы данных могут быть добавлены потокобезопасным образом.

int PyArray_RegisterCastFunc(PyArray_Descr *descr, int totype, PyArray_VectorUnaryFunc *castfunc)#

Регистрирует низкоуровневую функцию приведения, castfunc, чтобы преобразовать из типа данных, descr, к заданному номеру типа данных, totype. Любая старая функция приведения перезаписывается. 0 возвращается при успехе или -1 при неудаче.

тип PyArray_VectorUnaryFunc#: Тип указателя функции для низкоуровневых функций приведения типов.

int PyArray_RegisterCanCast(PyArray_Descr *descr, int totype, NPY_SCALARKIND скаляр)#: Зарегистрировать номер типа данных, totype, как преобразуемый из объекта типа данных, descr, заданного скаляр вид. Используйте скаляр = NPY_NOSCALAR чтобы зарегистрировать, что массив типа данных descr может быть безопасно приведён к типу данных, чей type_number равен totype. Возвращаемое значение равно 0 при успехе или -1 при неудаче.

Специальные функции для NPY_OBJECT#

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

При работе с массивами или буферами, заполненными объектами, NumPy пытается гарантировать, что такие буферы заполнены None перед чтением любых данных. Однако могут существовать пути выполнения кода, где массив инициализируется только до NULL. NumPy сам принимает NULL в качестве псевдонима для None, но может assert не-NULL при компиляции в режиме отладки.

Поскольку NumPy ещё не согласован в инициализации с None, пользователи должен ожидать значение NULL при работе с буферами, созданными NumPy. Пользователи должен также убедитесь, что передаёте полностью инициализированные буферы в NumPy, поскольку NumPy может сделать это строгим требованием в будущем.

В настоящее время существует намерение гарантировать, что NumPy всегда инициализирует массивы объектов перед их чтением. Любая неудача в этом будет рассматриваться как ошибка. В будущем пользователи смогут полагаться на ненулевые значения при чтении из любого массива, хотя исключения для записи во вновь созданные массивы могут остаться (например, для выходных массивов в коде ufunc). По состоянию на NumPy 1.23 известны пути кода, где правильное заполнение не выполняется.

int PyArray_INCREF(PyArrayObject *op)#: Используется для массива, op, который содержит любые объекты Python. Он увеличивает счётчик ссылок каждого объекта в массиве в соответствии с типом данных op. Возвращается -1, если происходит ошибка, в противном случае возвращается 0.

void PyArray_Item_INCREF(char *ptr, PyArray_Descr *dtype)#: Функция для INCREF всех объектов в местоположении ptr в соответствии с типом данных dtype. Если ptr является началом структурированного типа с объектом в любом смещении, тогда это (рекурсивно) увеличит счётчик ссылок всех объектоподобных элементов в структурированном типе.

int PyArray_XDECREF(PyArrayObject *op)#: Используется для массива, op, который содержит любые объекты Python. Он уменьшает счетчик ссылок каждого объекта в массиве в соответствии с типом данных op. Нормальное возвращаемое значение — 0. Возвращается -1, если возникает ошибка.

void PyArray_Item_XDECREF(char *ptr, PyArray_Descr *dtype)#: Функция для XDECREF всех объектоподобных элементов в местоположении ptr как записано в типе данных, dtype. Это работает рекурсивно, так что если dtype сам имеет поля с типами данных, содержащими объектоподобные элементы; все объектоподобные поля будут XDECREF 'd.

int PyArray_SetWritebackIfCopyBase(PyArrayObject *arr, PyArrayObject *основание)#

Предварительное условие: arr является копией base (хотя возможно с другими шагами, порядком и т.д.). Устанавливает NPY_ARRAY_WRITEBACKIFCOPY флаг и arr->base, и установить base в READONLY. Вызовите PyArray_ResolveWritebackIfCopy перед вызовом Py_DECREF чтобы скопировать любые изменения обратно в base и сбросить флаг READONLY.

Возвращает 0 при успехе, -1 при неудаче.

Флаги массива#

The flags атрибут PyArrayObject Структура содержит важную информацию об используемой массивом памяти (на которую указывает член data). Эта информация о флагах должна сохраняться точно, иначе могут возникнуть странные результаты и даже сегфолты.

Существует 6 (бинарных) флагов, описывающих область памяти, используемую буфером данных. Эти константы определены в arrayobject.h и определение позиции бита флага. Python предоставляет удобный интерфейс на основе атрибутов, а также словарный интерфейс для получения (и, если уместно, установки) этих флагов.

Области памяти всех видов могут быть указаны ndarray, что требует этих флагов. Если вы получаете произвольный PyArrayObject в C-коде, вам нужно знать об установленных флагах. Если вам нужно гарантировать определенный тип массива (например, NPY_ARRAY_C_CONTIGUOUS и NPY_ARRAY_BEHAVED), затем передайте эти требования в функцию PyArray_FromAny.

В версиях 1.6 и более ранних NumPy следующие флаги не имели макроса _ARRAY_ в их пространстве имен. Такая форма имен констант устарела в версии 1.7.

Базовые флаги массива#

ndarray может иметь сегмент данных, который не является простым непрерывным блоком хорошо организованной памяти, которой можно манипулировать. Он может быть не выровнен по границам слов (очень важно на некоторых платформах). Его данные могут быть в другом порядке байтов, чем распознает машина. Он может быть недоступен для записи. Он может быть в порядке Fortran-contiguous. Флаги массива используются для указания того, что можно сказать о данных, связанных с массивом.

NPY_ARRAY_C_CONTIGUOUS#: Область данных находится в порядке C-стиля с непрерывным расположением (последний индекс изменяется быстрее всего).

NPY_ARRAY_F_CONTIGUOUS#: Область данных находится в порядке, непрерывном в стиле Fortran (первый индекс изменяется быстрее всего).

Примечание

Массивы могут быть одновременно C-стиля и Fortran-стиля непрерывными. Это очевидно для одномерных массивов, но также может быть верно для массивов более высокой размерности.

Даже для непрерывных массивов шаг для заданного измерения arr.strides[dim] может быть произвольный if arr.shape[dim] == 1 или массив не имеет элементов. Он делает не обычно считают, что self.strides[-1] == self.itemsize для C-стиля смежных массивов или self.strides[0] == self.itemsize для массивов с непрерывностью в стиле Fortran истинно. Правильный способ доступа к itemsize массива из C API является PyArray_ITEMSIZE(arr).

Смотрите также

Внутренняя организация памяти ndarray

NPY_ARRAY_OWNDATA#: Область данных принадлежит этому массиву. Никогда не устанавливайте вручную, вместо этого создайте PyObject обёртывая данные и установив базовый объект массива на этот объект. Пример см. в тесте в test_mem_policy.

NPY_ARRAY_ALIGNED#: Область данных и все элементы массива выровнены соответствующим образом.

NPY_ARRAY_WRITEABLE#

Область данных может быть записана.

Обратите внимание, что эти 3 флага определены так, что новый, хорошо ведущий себя массив имеет эти флаги установленными в true.

NPY_ARRAY_WRITEBACKIFCOPY#

Область данных представляет собой (корректную) копию, информацию которой следует передать обратно в оригинал, когда PyArray_ResolveWritebackIfCopy вызывается.

Это специальный флаг, который устанавливается, если этот массив представляет копию, созданную потому, что пользователь потребовал определённые флаги в PyArray_FromAny и пришлось создать копию другого массива (и пользователь запросил установку этого флага в такой ситуации). Атрибут base затем указывает на "некорректный" массив (который установлен как read_only). PyArray_ResolveWritebackIfCopy скопирует его содержимое обратно в "некорректный" массив (при необходимости с приведением типов) и сбросит "некорректный" массив в NPY_ARRAY_WRITEABLE. Если "некорректный" массив не был NPY_ARRAY_WRITEABLE для начала, затем PyArray_FromAny вернул бы ошибку, потому что NPY_ARRAY_WRITEBACKIFCOPY было бы невозможно.

PyArray_UpdateFlags (obj, flags) обновит obj->flags для flags который может быть любым из NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, или NPY_ARRAY_WRITEABLE.

Комбинации флагов массива#

NPY_ARRAY_BEHAVED#: NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY#: NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO#: NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT#: NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY#: NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_ARRAY#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_FARRAY#: NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY

NPY_ARRAY_INOUT_FARRAY#: NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY

NPY_ARRAY_UPDATE_ALL#: NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Константы, подобные флагам#

Эти константы используются в PyArray_FromAny (и его макроформы) для указания желаемых свойств нового массива.

NPY_ARRAY_FORCECAST#: Привести к желаемому типу, даже если это невозможно без потери информации.

NPY_ARRAY_ENSURECOPY#: Убедитесь, что результирующий массив является копией оригинала.

NPY_ARRAY_ENSUREARRAY#: Убедитесь, что результирующий объект является фактически ndarray, а не подклассом.

Эти константы используются в PyArray_CheckFromAny (и его макроформы) для указания желаемых свойств нового массива.

NPY_ARRAY_NOTSWAPPED#: Убедитесь, что возвращаемый массив имеет дескриптор типа данных в порядке байтов машины, переопределяя любые спецификации в dtype аргумент. Обычно требование порядка байтов определяется dtype аргумент. Если этот флаг установлен и аргумент dtype не указывает на дескриптор типа данных в машинном порядке байтов (или равен NULL и объект уже является массивом с дескриптором типа данных, который не в машинном порядке байтов), то создается новый дескриптор типа данных и используется с полем порядка байтов, установленным в native.

NPY_ARRAY_BEHAVED_NS#: NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES#: Убедитесь, что возвращаемый массив имеет шаги, кратные размеру элемента.

Проверка флагов#

Для всех этих макросов arr должен быть экземпляром (подкласса) PyArray_Type.

int PyArray_CHKFLAGS(const PyArrayObject *arr, int флаги)#: Первый параметр, arr, должен быть ndarray или подклассом. Параметр, флаги, должен быть целым числом, состоящим из битовых комбинаций возможных флагов, которые может иметь массив: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_OWNDATA, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_WRITEBACKIFCOPY.

int PyArray_IS_C_CONTIGUOUS(const PyArrayObject *arr)#: Вычисляет true, если arr является C-стиль смежным.

int PyArray_IS_F_CONTIGUOUS(const PyArrayObject *arr)#: Вычисляет true, если arr является непрерывным в стиле Fortran.

int PyArray_ISFORTRAN(const PyArrayObject *arr)#: Вычисляет true, если arr является Fortran-стиль смежным и не C-стиль смежности. PyArray_IS_F_CONTIGUOUS является правильным способом проверки на смежность в стиле Fortran.

int PyArray_ISWRITEABLE(const PyArrayObject *arr)#: Оценивает true, если область данных arr может быть записано в

int PyArray_ISALIGNED(const PyArrayObject *arr)#: Оценивает true, если область данных arr правильно выровнен на машине.

int PyArray_ISBEHAVED(const PyArrayObject *arr)#: Оценивает true, если область данных arr выровнен и доступен для записи и в машинном порядке байтов согласно его дескриптору.

int PyArray_ISBEHAVED_RO(const PyArrayObject *arr)#: Оценивает true, если область данных arr выровнен и находится в машинном порядке байтов.

int PyArray_ISCARRAY(const PyArrayObject *arr)#: Оценивает true, если область данных arr является C-стиль смежным, и PyArray_ISBEHAVED (arr) истинно.

int PyArray_ISFARRAY(const PyArrayObject *arr)#: Оценивает true, если область данных arr является непрерывным в стиле Fortran и PyArray_ISBEHAVED (arr) истинно.

int PyArray_ISCARRAY_RO(const PyArrayObject *arr)#: Оценивает true, если область данных arr является C-стиль смежным, выровненным и в порядке байтов машины.

int PyArray_ISFARRAY_RO(const PyArrayObject *arr)#: Оценивает true, если область данных arr является Fortran-стилем непрерывным, выровненным и в порядке байтов машины .

int PyArray_ISONESEGMENT(const PyArrayObject *arr)#: Оценивает true, если область данных arr состоит из одного (C-стиль или Fortran-стиль) непрерывного сегмента.

void PyArray_UpdateFlags(PyArrayObject *arr, int flagmask)#: The NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_ALIGNED, и NPY_ARRAY_F_CONTIGUOUS флаги массива могут быть "вычислены" из самого объекта массива. Эта процедура обновляет один или несколько из этих флагов arr как указано в flagmask выполнив необходимые вычисления.

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

Важно поддерживать флаги обновленными (используя PyArray_UpdateFlags может помочь) всякий раз, когда выполняется манипуляция с массивом, которая может привести к их изменению. Последующие вычисления в NumPy, которые зависят от состояния этих флагов, не повторяют вычисление для их обновления.

int PyArray_FailUnlessWriteable(PyArrayObject *obj, const char *имя)#

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

имя это имя массива, используемое для выдачи более понятных сообщений об ошибках. Это может быть что-то вроде "назначение назначения", "выходной массив" или даже просто "массив".

ArrayMethod API#

Циклы ArrayMethod предназначены как универсальный механизм для написания циклов по массивам, включая циклы ufunc и преобразования. Публичный API определён в numpy/dtype_api.h заголовок. См. PyArrayMethod_Context и PyArrayMethod_Spec для документации по C структурам, доступным в ArrayMethod API.

Слоты и определения типов#

Они используются для определения, какую функцию реализует слот ArrayMethod. См. Слоты и определения типов ниже для документации по функциям, которые должны быть реализованы для каждого слота.

NPY_METH_resolve_descriptors#

typedef NPY_CASTING (PyArrayMethod_ResolveDescriptors)(struct PyArrayMethodObject_tag *метод, PyArray_DTypeMeta *const *dtypes, PyArray_Descr *const *given_descrs, PyArray_Descr **loop_descrs, npy_intp *view_offset)#

Функция, используемая для установки дескрипторов операции на основе дескрипторов операндов. Например, операция ufunc с двумя входными операндами и одним выходным операндом, которая вызывается без out установленное в Python API, resolve_descriptors будет передан дескриптор для двух операндов и определит правильный дескриптор для использования на выходе на основе выходного DType, установленного для ArrayMethod. Если out установлен, тогда выходной дескриптор будет передан также и не должен быть переопределен.

The метод является указателем на базовое приведение или цикл ufunc. В будущем мы можем сделать эту структуру публичной, но сейчас это непрозрачный указатель, и метод не может быть исследован. dtypes является nargs массив длины PyArray_DTypeMeta указатели, given_descrs является nargs массив длины входных дескрипторов экземпляров (выходные дескрипторы могут быть NULL, если пользователь не предоставил выход), и loop_descrs является nargs массив длины дескрипторов, который должен быть заполнен реализацией разрешения дескрипторов. view_offset в настоящее время представляет интерес только для преобразований типов и обычно может игнорироваться. Когда преобразование не требует никаких операций, это может быть обозначено установкой view_offset в 0. При ошибке вы должны вернуть (NPY_CASTING)-1 с установленной ошибкой.

NPY_METH_strided_loop#

NPY_METH_contiguous_loop#

NPY_METH_unaligned_strided_loop#

NPY_METH_unaligned_contiguous_loop#

Одномерные страйдовые циклы, реализующие поведение (либо ufunc, либо приведение). В большинстве случаев, NPY_METH_strided_loop является общей и единственной версией, которую нужно реализовать. NPY_METH_contiguous_loop может быть дополнительно реализован как более легковесная/быстрая версия и используется, когда все входные и выходные данные являются непрерывными.

Для работы с возможно невыровненными данными NumPy должен уметь копировать невыровненные данные в выровненные. При реализации нового DType 'cast' или копирование для него должно реализовывать NPY_METH_unaligned_strided_loop. В отличие от обычных версий, этот цикл не должен предполагать, что данные доступны выровненным образом. Эти циклы должны копировать каждое значение перед доступом или сохранением:

type_in in_value;
type_out out_value
memcpy(&value, in_data, sizeof(type_in));
out_value = in_value;
memcpy(out_data, &out_value, sizeof(type_out)

в то время как обычный цикл может просто использовать:

*(type_out *)out_data = *(type_in)in_data;

Невыровненные циклы в настоящее время используются только в преобразованиях типов и никогда не выбираются в универсальных функциях (универсальные функции создают временную копию для обеспечения выровненных входных данных). Эти идентификаторы слотов игнорируются, когда NPY_METH_get_loop определяется, где вместо этого любой цикл, возвращаемый get_loop используется функция.

NPY_METH_contiguous_indexed_loop#: Специализированный вариант внутреннего цикла для ускорения общих ufunc.at вычисления.

typedef int (PyArrayMethod_StridedLoop)(PyArrayMethod_Context *контекст, char *const *данные, const npy_intp *измерения, const npy_intp *strides, NpyAuxData *вспомогательные данные)#: Реализация цикла ArrayMethod. Все идентификаторы слотов цикла, перечисленные выше, должны предоставлять PyArrayMethod_StridedLoop реализация. контекст является структурой, содержащей контекст для операции цикла - в частности, дескрипторы входных данных. The данные являются массивом указателей на начало буферов входного и выходного массивов. измерения являются размерностями цикла для операции. strides являются nargs массив длины шагов для каждого ввода. The вспомогательные данные это необязательный набор вспомогательных данных, который можно передать в цикл - полезно для включения и отключения необязательного поведения или сокращения шаблонного кода, позволяя похожим ufuncs использовать общие реализации циклов или выделять пространство, которое сохраняется при нескольких вызовах циклов с шагом.

NPY_METH_get_loop#: Позволяет более детально контролировать выбор цикла. Принимает реализацию PyArrayMethod_GetLoop, которая в свою очередь возвращает реализацию strided loop. Если NPY_METH_get_loop определён, другие идентификаторы слотов цикла игнорируются, если указаны.

typedef int (PyArrayMethod_GetLoop)(PyArrayMethod_Context *контекст, int aligned, int move_references, const npy_intp *strides, PyArrayMethod_StridedLoop **out_loop, NpyAuxData **out_transferdata, NPY_ARRAYMETHOD_FLAGS *флаги);#: Устанавливает цикл для использования в операции во время выполнения. контекст является контекстом выполнения для операции. aligned указывает, является ли доступ к данным для цикла выровненным (1) или невыровненным (0). move_references указывает, следует ли копировать встроенные ссылки в данных. strides являются шагами для входного массива, out_loop является указателем, который должен быть заполнен указателем на реализацию цикла. out_transferdata может быть опционально заполнен, чтобы позволить передавать дополнительный пользовательский контекст в операцию. флаги должен быть заполнен флагами ArrayMethod, релевантными для операции. Это необходимо, например, чтобы указать, требует ли внутренний цикл удержания GIL Python.

NPY_METH_get_reduction_initial#

typedef int (PyArrayMethod_GetReductionInitial)(PyArrayMethod_Context *контекст, npy_bool reduction_is_empty, char *начальный)#

Запросить у ArrayMethod начальное значение для использования в редукции. контекст является контекстом ArrayMethod, в основном для доступа к входным дескрипторам. reduction_is_empty указывает, является ли редукция пустой. Когда это так, возвращаемое значение может отличаться. В этом случае это "значение по умолчанию", которое может отличаться от "тождественного" значения, обычно используемого. Например:

0.0 8.1 sum([]). Но -0.0 является правильной идентичностью в противном случае, так как сохраняет знак для sum([-0.0]).
Мы не используем тождество для объекта, а возвращаем значение по умолчанию 0 и 1 для пустого sum([], dtype=object) и prod([], dtype=object). Это позволяет np.sum(np.array(["a", "b"], dtype=object)) для работы.
-inf или INT_MIN для max является тождеством, но по крайней мере INT_MIN не является хорошим по умолчанию когда нет элементов.

начальный является указателем на данные для начального значения, которые должны быть заполнены. Возвращает -1, 0 или 1, указывая на ошибку, отсутствие начального значения и успешное заполнение начального значения. Ошибки не должны выдаваться, когда начальное значение неверно, поскольку NumPy может вызывать это даже тогда, когда это не строго необходимо.

Флаги#

перечисление NPY_ARRAYMETHOD_FLAGS#

Эти флаги позволяют включать и отключать пользовательское поведение во время выполнения для циклов ArrayMethod. Например, если ufunc не может вызвать ошибки с плавающей запятой, то NPY_METH_NO_FLOATINGPOINT_ERRORS флаг должен быть установлен для ufunc при его регистрации.

перечислитель NPY_METH_REQUIRES_PYAPI#: Указывает, что метод должен удерживать GIL. Если этот флаг не установлен, GIL освобождается перед вызовом цикла.

перечислитель NPY_METH_NO_FLOATINGPOINT_ERRORS#: Указывает, что метод не может генерировать ошибки с плавающей запятой, поэтому проверка ошибок с плавающей запятой после завершения цикла может быть пропущена.

перечислитель NPY_METH_SUPPORTS_UNALIGNED#: Указывает, что метод поддерживает невыровненный доступ.

перечислитель NPY_METH_IS_REORDERABLE#: Указывает, что результат многократного применения цикла (например, в операции редукции) не зависит от порядка применения.

перечислитель NPY_METH_RUNTIME_FLAGS#: Флаги, которые можно изменить во время выполнения.

Определения типов#

Определения типов для функций, которые могут реализовать пользователи API ArrayMethod, описаны ниже.

typedef int (PyArrayMethod_TraverseLoop)(void *traverse_context, const PyArray_Descr *descr, char *данные, npy_intp размер, npy_intp шаг, NpyAuxData *вспомогательные данные)#

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

В настоящее время это используется для очистки массива через NPY_DT_get_clear_loop Хук API DType и заполнение нулями через NPY_DT_get_fill_zero_loop Хук API DType. Они наиболее полезны для обработки массивов, хранящих встроенные ссылки на объекты Python или данные, выделенные в куче.

The descr является дескриптором для массива, данные является указателем на буфер массива, размер это одномерный размер буфера массива, шаг это шаг, и вспомогательные данные является дополнительными необязательными данными для цикла.

The traverse_context передается, потому что в будущем нам может потребоваться передать состояние интерпретатора или подобное, но мы не хотим передавать полный контекст (с указателями на типы данных, метод, вызывающий объект, которые не имеют смысла для функции обхода). Мы предполагаем, что этот контекст можно просто передать в будущем (для структурированных типов данных).

typedef int (PyArrayMethod_GetTraverseLoop)(void *traverse_context, const PyArray_Descr *descr, int aligned, npy_intp fixed_stride, PyArrayMethod_TraverseLoop **out_loop, NpyAuxData **out_auxdata, NPY_ARRAYMETHOD_FLAGS *флаги)#

Упрощенная функция get_loop, специфичная для обхода dtype

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

API-функции и определения типов#

Эти функции являются частью основного API массивов numpy и были добавлены вместе с остальным API ArrayMethod.

int PyUFunc_AddLoopFromSpec(PyObject *универсальная функция (ufunc), PyArrayMethod_Spec *спецификация)#: Добавить цикл напрямую к ufunc из заданной спецификации ArrayMethod. основная функция регистрации ufunc. Это добавляет новую реализацию/цикл к ufunc. Она заменяет PyUFunc_RegisterLoopForType.

тип PyUFunc_LoopSlot#

Структура, используемая для добавления нескольких циклов к ufunc из спецификаций ArrayMethod. Используется в PyUFunc_AddLoopsFromSpecs.

struct PyUFunc_LoopSlot#

const char *имя#

Имя ufunc для добавления цикла, в форме, подобной точкам входа, (module ':')? (object '.')* name, с numpy модуль по умолчанию. Примеры: sin, strings.str_len, numpy.strings:str_len.

PyArrayMethod_Spec *спецификация#

Спецификация ArrayMethod, используемая для создания цикла.

int PyUFunc_AddLoopsFromSpecs(PyUFunc_LoopSlot *слоты)#

Новое в версии 2.4.

Добавить несколько циклов к ufuncs из спецификаций ArrayMethod. Это также обрабатывает регистрацию методов для функций, подобных ufunc sort и argsort. См. Сортировка и аргсортировка подробности.

The slots аргумент должен быть NULL-терминированным массивом PyUFunc_LoopSlot (см. выше), которые дают имя ufunc и спецификацию, необходимую для создания цикла.

int PyUFunc_AddPromoter(PyObject *универсальная функция (ufunc), PyObject *DType_tuple, PyObject *промоутер)#: Обратите внимание, что в настоящее время выходные типы данных всегда NULL если они также не являются частью сигнатуры. Это деталь реализации и может измениться в будущем. Однако, в общем случае, промоутерам не нужны выходные типы данных. Зарегистрируйте нового промоутера для ufunc. Первый аргумент — это ufunc, с которым регистрируется промоутер. Второй аргумент — это кортеж Python, содержащий DTypes или None, соответствующие количеству входов и выходов для ufunc. Последний аргумент — это промоутер, функция, хранящаяся в PyCapsule. Она получает операцию и запрошенные сигнатуры DType и может изменять её для попытки нового поиска соответствующего цикла/промоутера.

typedef int (: BUG: Исправление утечки счетчика ссылок в str(scalar).)(PyObject *универсальная функция (ufunc), PyArray_DTypeMeta *const op_dtypes[], PyArray_DTypeMeta *const сигнатура[], PyArray_DTypeMeta *new_op_dtypes[])#: Тип функции-промоутера, который должен быть обёрнут в PyCapsule с именем "numpy._ufunc_promoter". Ему передаются операция и запрошенные сигнатуры DType, и он может изменять сигнатуры для поиска нового цикла или промоутера, который может выполнить операцию путём приведения входных данных к "повышенным" DType.

int PyUFunc_GiveFloatingpointErrors(const char *имя, int fpe_errors)#

Проверяет ошибку с плавающей запятой после выполнения операции с плавающей запятой таким образом, чтобы учитывать сигнализацию об ошибке, настроенную через numpy.errstate. Принимает имя операции для использования в сообщении об ошибке и целочисленный флаг, который является одним из NPY_FPE_DIVIDEBYZERO, NPY_FPE_OVERFLOW, NPY_FPE_UNDERFLOW, NPY_FPE_INVALID чтобы указать, какую ошибку проверять.

Возвращает -1 при неудаче (было вызвано исключение) и 0 при успехе.

int PyUFunc_AddWrappingLoop(PyObject *ufunc_obj, PyArray_DTypeMeta *new_dtypes[], PyArray_DTypeMeta *обёрнутые типы данных[], PyArrayMethod_TranslateGivenDescriptors *translate_given_descrs, PyArrayMethod_TranslateLoopDescriptors *translate_loop_descrs)#: Позволяет создать довольно легковесную обертку вокруг существующего цикла ufunc. Основная идея предназначена для единиц измерения, так как в настоящее время это несколько ограничено тем, что не позволяет использовать цикл из другого ufunc.

typedef int (PyArrayMethod_TranslateGivenDescriptors)(int nin, int nout, PyArray_DTypeMeta *обёрнутые типы данных[], PyArray_Descr *given_descrs[], PyArray_Descr *new_descrs[]);#

Функция для преобразования заданных дескрипторов (переданных в resolve_descriptors) и переводит их для обернутого цикла. Новые дескрипторы ДОЛЖНЫ быть просматриваемыми со старыми, NULL должен поддерживаться (для выходных аргументов) и обычно должен передаваться дальше.

Результат этой функции будет использоваться для создания представлений аргументов, как если бы они были преобразованными типами данных, и не использует приведение. Это означает, что этот механизм в основном полезен для типов данных, которые «оборачивают» другую реализацию типа данных. Например, единичный тип данных может использовать это для обертывания существующего типа данных с плавающей точкой без необходимости повторной реализации низкоуровневой логики универсальных функций. В примере с единицами resolve_descriptors будет обрабатывать вычисление выходной единицы измерения из входной единицы.

typedef int (PyArrayMethod_TranslateLoopDescriptors)(int nin, int nout, PyArray_DTypeMeta *new_dtypes[], PyArray_Descr *given_descrs[], PyArray_Descr *original_descrs[], PyArray_Descr *loop_descrs[]);#: Функция для преобразования фактических дескрипторов циклов (как возвращено оригинальным resolve_descriptors функция) для тех, которые выходной массив должен использовать. Эта функция должна возвращать «просматриваемые» типы, она не должна изменять их каким-либо образом, который нарушил бы логику внутреннего цикла. Не должна поддерживать NULL.

Пример обёртки цикла#

Предположим, вы хотите обернуть float64 реализация умножения для WrappedDoubleDType. Вы бы добавили обёртывающий цикл примерно так:

PyArray_DTypeMeta *orig_dtypes[3] = {
    &WrappedDoubleDType, &WrappedDoubleDType, &WrappedDoubleDType};
PyArray_DTypeMeta *wrapped_dtypes[3] = {
     &PyArray_Float64DType, &PyArray_Float64DType, &PyArray_Float64DType}

PyObject *mod = PyImport_ImportModule("numpy");
if (mod == NULL) {
    return -1;
}
PyObject *multiply = PyObject_GetAttrString(mod, "multiply");
Py_DECREF(mod);

if (multiply == NULL) {
    return -1;
}

int res = PyUFunc_AddWrappingLoop(
    multiply, orig_dtypes, wrapped_dtypes, &translate_given_descrs
    &translate_loop_descrs);

Py_DECREF(multiply);

Обратите внимание, что это также требует определения двух функций выше этого кода:

static int
translate_given_descrs(int nin, int nout,
                       PyArray_DTypeMeta *NPY_UNUSED(wrapped_dtypes[]),
                       PyArray_Descr *given_descrs[],
                       PyArray_Descr *new_descrs[])
{
    for (int i = 0; i < nin + nout; i++) {
        if (given_descrs[i] == NULL) {
            new_descrs[i] = NULL;
        }
        else {
            new_descrs[i] = PyArray_DescrFromType(NPY_DOUBLE);
        }
    }
    return 0;
}

static int
translate_loop_descrs(int nin, int NPY_UNUSED(nout),
                      PyArray_DTypeMeta *NPY_UNUSED(new_dtypes[]),
                      PyArray_Descr *given_descrs[],
                      PyArray_Descr *original_descrs[],
                      PyArray_Descr *loop_descrs[])
{
    // more complicated parametric DTypes may need to
    // to do additional checking, but we know the wrapped
    // DTypes *have* to be float64 for this example.
    loop_descrs[0] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[0]);
    loop_descrs[1] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[1]);
    loop_descrs[2] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[2]);
}

Сортировка и аргсортировка#

Методы сортировки и аргсортировки для типов данных могут быть зарегистрированы с использованием API ArrayMethod. Это делается путем добавления спецификации ArrayMethod с именем "sort" или "argsort" соответственно. Спецификация должна иметь nin=1 и nout=1 для sort и argsort. Сортировка выполняется на месте, поэтому мы обеспечиваем, чтобы data[0] == data[1]. Сортировка по индексам возвращает новый массив индексов, поэтому вывод должен быть NPY_INTP тип.

The context переданный в цикл содержит parameters поле, которое для этих операций является PyArrayMethod_SortParameters * struct. Этот struct содержит flags поле, которое является побитовым ИЛИ NPY_SORTKIND значения, указывающие тип сортировки (то есть, является ли она устойчивой и/или нисходящей). Если страйд-цикл зависит от флагов, хороший способ справиться с этим — определить NPY_METH_get_loopи не устанавливать другие слоты цикла.

struct PyArrayMethod_SortParameters#

NPY_SORTKIND флаги#: Флаги, передаваемые операции сортировки. Это побитовое ИЛИ NPY_SORTKIND значения, указывающие тип сортировки для выполнения.

Эти спецификации могут быть зарегистрированы с помощью PyUFunc_AddLoopsFromSpecs наряду с другими циклами универсальных функций.

API для вызова методов массива#

Преобразование#

PyObject *PyArray_GetField(PyArrayObject *self, PyArray_Descr *dtype, int смещение)#: Эквивалентно ndarray.getfield (self, dtype, смещение). Эта функция крадет ссылку to PyArray_Descr и возвращает новый массив заданного dtype используя данные в текущем массиве по указанному смещение в байтах. смещение плюс itemsize нового типа массива должен быть меньше self->descr->elsize или возникает ошибка. Используются та же форма и шаги, что и у исходного массива. Поэтому эта функция имеет эффект возврата поля из структурированного массива. Но её также можно использовать для выбора конкретных байтов или групп байтов из любого типа массива.

int PyArray_SetField(PyArrayObject *self, PyArray_Descr *dtype, int смещение, PyObject *val)#: Эквивалентно ndarray.setfield (self, val, dtype, смещение ). Установите поле, начиная с смещение в байтах и заданного dtype to val. смещение плюс dtype ->elsize должен быть меньше чем self ->descr->elsize или возникает ошибка. В противном случае, val аргумент преобразуется в массив и копируется в указанное поле. При необходимости элементы val повторяются для заполнения целевого массива. Однако количество элементов в целевом массиве должно быть целым кратным количеству элементов в val.

PyObject *PyArray_Byteswap(PyArrayObject *self, npy_bool inplace)#: Эквивалентно ndarray.byteswap (self, inplace). Возвращает массив, чей блок данных переставлен байтами. Если inplace не равно нулю, то выполнить байтовый обмен на месте и вернуть ссылку на self. В противном случае, создать копию с байтовым обменом и оставить self неизменным.

PyObject *PyArray_NewCopy(PyArrayObject *старый, NPY_ORDER порядок)#: Эквивалентно ndarray.copy (self, fortran). Создать копию старый массив. Возвращаемый массив всегда выровнен и доступен для записи, с данными, интерпретируемыми так же, как старый массив. Если порядок является NPY_CORDER, тогда возвращается массив в стиле C с непрерывным расположением элементов. Если порядок является NPY_FORTRANORDER, тогда возвращается массив с непрерывным расположением в стиле Fortran. Если порядок NPY_ANYORDER, тогда возвращаемый массив является Fortran-стиль непрерывным только если старый был; в противном случае он является C-стиль непрерывным.

PyObject *PyArray_ToList(PyArrayObject *self)#: Эквивалентно ndarray.tolist (self). Возвращает вложенный список Python из self.

PyObject *PyArray_ToString(PyArrayObject *self, NPY_ORDER порядок)#: Эквивалентно ndarray.tobytes (self, порядок). Возвращает байты этого массива в виде строки Python.

PyObject *PyArray_ToFile(PyArrayObject *self, FILE *fp, char *sep, char *формат)#: Записать содержимое self в файловый указатель fp в стиле C непрерывным образом. Записывайте данные как двоичные байты, если sep является ли строка "" или NULL. В противном случае, запишите содержимое self в виде текста с использованием sep строка в качестве разделителя элементов. Каждый элемент будет выведен в файл. Если формат строка не является NULL или "", то это строка формата оператора print в Python, показывающая, как элементы должны быть записаны.

int PyArray_Dump(PyObject *self, PyObject *файл, int protocol)#: Сериализовать объект в self к заданному файл (либо строка или файловый объект Python). Если файл является строкой Python, она считается именем файла, который затем открывается в бинарном режиме. Данный protocol используется (если protocol отрицательно, или используется наивысшее доступное). Это простая обертка вокруг cPickle.dump(self, файл, protocol).

PyObject *PyArray_Dumps(PyObject *self, int protocol)#: Сериализовать объект в self в строку Python и вернуть её. Используйте Pickle protocol предоставлен (или наивысший доступный, если protocol отрицательно).

int PyArray_FillWithScalar(PyArrayObject *arr, PyObject *obj)#: Заполнить массив, arr, с заданным скалярным объектом, obj. Объект сначала преобразуется в тип данных arr, а затем скопирован в каждую позицию. Возвращается -1, если возникает ошибка, иначе возвращается 0.

PyObject *PyArray_View(PyArrayObject *self, PyArray_Descr *dtype, PyTypeObject *ptype)#

Эквивалентно ndarray.view (self, dtype). Возвращает новое представление массива self как возможно другой тип данных, dtype, и различные подклассы массивов ptype.

Если dtype является NULL, тогда возвращаемый массив будет иметь тот же тип данных, что и self. Новый тип данных должен быть совместим с размером self. Либо размеры элементов должны быть идентичны, либо self должен быть односегментным, и общее количество байтов должно быть одинаковым. В последнем случае размеры возвращаемого массива будут изменены в последнем (или первом для массивов в стиле Fortran) измерении. Область данных возвращаемого массива и исходного массива точно одинакова.

Манипуляция формой#

PyObject *PyArray_Newshape(PyArrayObject *self, PyArray_Dims *newshape, NPY_ORDER порядок)#: Результатом будет новый массив (указывающий на ту же область памяти, что и self если возможно), но имея форму, заданную newshape. Если новая форма несовместима с шагами selfтогда будет возвращена копия массива с новой указанной формой.

PyObject *PyArray_Reshape(PyArrayObject *self, PyObject *shape)#: Эквивалентно ndarray.reshape (self, shape), где shape является последовательностью. Преобразует shape в PyArray_Dims структура и вызовы PyArray_Newshape внутренне. Для обратной совместимости – не рекомендуется

PyObject *PyArray_Squeeze(PyArrayObject *self)#: Эквивалентно ndarray.squeeze (self). Возвращает новое представление self со всеми измерениями длины 1, удаленными из формы.

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

матричные объекты всегда двумерные. Поэтому, PyArray_Squeeze не влияет на массивы подкласса матрицы.

PyObject *PyArray_SwapAxes(PyArrayObject *self, int a1, int a2)#: Эквивалентно ndarray.swapaxes (self, a1, a2). Возвращаемый массив является новым представлением данных в self с заданными осями, a1 и a2, поменяны местами.

PyObject *PyArray_Resize(PyArrayObject *self, PyArray_Dims *newshape, int refcheck, NPY_ORDER fortran)#: Эквивалентно ndarray.resize (self, newshape, refcheck). Эта функция работает только с массивами с одним сегментом. Она изменяет форму self на месте и перераспределит память для self if newshape имеет другое общее количество элементов, чем старая форма. Если необходимо перераспределение, то self должен владеть своими данными, иметь self - >base==NULL, иметь self - >weakrefs==NULL, и (если refcheck не равен 0) не быть ссылаемым никаким другим массивом. Аргумент fortran может быть NPY_ANYORDER, NPY_CORDER, или NPY_FORTRANORDER. В настоящее время не имеет эффекта. В конечном итоге может использоваться для определения того, как операция изменения размера должна рассматривать данные при построении массива с другой размерностью. Возвращает None при успехе и NULL при ошибке.

PyObject *PyArray_Transpose(PyArrayObject *self, PyArray_Dims *переставить)#: Эквивалентно ndarray.transpose (self, переставить). Переставьте оси объекта ndarray self в соответствии со структурой данных переставить и верните результат. Если переставить является NULL, тогда результирующий массив имеет перевернутые оси. Например, если self имеет форму \(10\times20\times30\), и переставить .ptr имеет форму (0,2,1), форма результата \(10\times30\times20.\) Если переставить является NULL, форма результата \(30\times20\times10.\)

PyObject *PyArray_Flatten(PyArrayObject *self, NPY_ORDER порядок)#: Эквивалентно ndarray.flatten (self, порядок). Возвращает одномерную копию массива. Если порядок является NPY_FORTRANORDER элементы сканируются в порядке Фортрана (первое измерение изменяется быстрее всего). Если порядок является NPY_CORDER, элементы self сканируются в порядке C (последнее измерение изменяется быстрее всего). Если порядок NPY_ANYORDER, тогда результат PyArray_ISFORTRAN (self) используется для определения порядка сглаживания.

PyObject *PyArray_Ravel(PyArrayObject *self, NPY_ORDER порядок)#: Эквивалентно self.ravel(порядок). Такая же базовая функциональность, как PyArray_Flatten (self, порядок) за исключением случаев, если порядок равно 0 и self является C-стиль смежным, форма изменяется, но копирование не выполняется.

Выбор и манипуляция элементами#

PyObject *PyArray_TakeFrom(PyArrayObject *self, PyObject *индексы, int ось, PyArrayObject *ret, NPY_CLIPMODE clipmode)#: Эквивалентно ndarray.take (self, индексы, ось, ret, clipmode) кроме ось =None в Python получается установкой ось = NPY_MAXDIMS в C. Извлечь элементы из self, указанные целочисленными индексы вдоль заданной ось. Аргумент clipmode может быть NPY_RAISE, NPY_WRAP, или NPY_CLIP чтобы указать, что делать с индексами вне границ. ret аргумент может указать выходной массив вместо создания его внутри функции.

PyObject *PyArray_PutTo(PyArrayObject *self, PyObject *values, PyObject *индексы, NPY_CLIPMODE clipmode)#: Эквивалентно self.put(values, индексы, clipmode ). Поместите values в self в соответствующей (сведённой) индексы. Если values слишком мал, он будет повторяться по мере необходимости.

PyObject *PyArray_PutMask(PyArrayObject *self, PyObject *values, PyObject *маска)#: Разместить values в self везде, где соответствующие позиции (используя сглаженный контекст) в маска истинны. The маска и self массивы должны иметь одинаковое общее количество элементов. Если values слишком мал, он будет повторяться по необходимости.

PyObject *PyArray_Repeat(PyArrayObject *self, PyObject *op, int ось)#: Эквивалентно ndarray.repeat (self, op, ось). Скопируйте элементы self, op раз вдоль заданной ось. Либо op является скалярным целым числом или последовательностью длины self ->размерности[ ось ] указывает, сколько раз повторять каждый элемент вдоль оси.

PyObject *PyArray_Choose(PyArrayObject *self, PyObject *op, PyArrayObject *ret, NPY_CLIPMODE clipmode)#

Эквивалентно ndarray.choose (self, op, ret, clipmode). Создать новый массив, выбирая элементы из последовательности массивов в op на основе целочисленных значений в self. Массивы должны быть транслируемы к одной форме, и записи в self должно быть между 0 и len(op). Выходные данные помещаются в ret если только это не NULL в этом случае создаётся новый выход. clipmode аргумент определяет поведение, когда записи в self не находятся между 0 и len(op).

NPY_RAISE#: вызвать ValueError;

NPY_WRAP#: оборачивать значения < 0, добавляя len(op) и значения >=len(op) вычитая len(op) пока они не окажутся в допустимом диапазоне;

NPY_CLIP#: все значения обрезаются до области [0, len(op).

PyObject *PyArray_Sort(PyArrayObject *self, int ось, NPY_SORTKIND kind)#

Верните массив с элементами self отсортированы вдоль axis. Массив сортируется с использованием алгоритма, свойства которого задаются значением kind, целое число/перечисление, указывающее требования алгоритма сортировки. Если self* ->descr является типом данных с определенными полями, тогда self->descr->names используется для определения порядка сортировки. При сравнении, где первое поле равно, будет использоваться второе поле и так далее. Чтобы изменить порядок сортировки структурированного массива, создайте новый тип данных с другим порядком имён и создайте представление массива с этим новым типом данных.

Это функция на уровне C, вызываемая методом ndarray ndarray.sort, хотя с другим значением kind – см. NPY_SORTKIND ниже.

PyObject *PyArray_ArgSort(PyArrayObject *self, int ось, NPY_SORTKIND kind)#

Вернуть массив индексов, таких что выбор этих индексов вдоль заданной axis вернёт отсортированную версию self. Массив сортируется с использованием алгоритма, свойства которого задаются kind, целое число/перечисление, задающее требования используемого алгоритма сортировки. Если self->descr является типом данных с определенными полями, тогда self->descr->names используется для определения порядка сортировки. При сравнении, где первое поле равно, будет использоваться второе поле и так далее. Чтобы изменить порядок сортировки структурированного массива, создайте новый тип данных с другим порядком имён и создайте представление массива с этим новым типом данных.

Это функция на уровне C, вызываемая методом ndarray ndarray.argsort, хотя с другим значением kind – см. NPY_SORTKIND ниже.

PyObject *PyArray_LexSort(PyObject *sort_keys, int ось)#

Для заданной последовательности массивов (sort_keys) той же формы, возвращает массив индексов (аналогично PyArray_ArgSort (…)) который сортирует массивы лексикографически. Лексикографическая сортировка указывает, что когда два ключа равны, порядок определяется сравнением последующих ключей. Сортировка слиянием (которая оставляет равные записи неподвижными) должна быть определена для типов. Сортировка выполняется путём сортировки индексов сначала с использованием первого sort_key а затем используя второй sort_key и так далее. Это эквивалентно lexsort(sort_keys, ось) Команда Python. Из-за способа работы сортировки слиянием обязательно понять порядок, в котором sort_keys должен быть в (обратном порядке от того, который вы бы использовали при сравнении двух элементов).

Если эти массивы собраны в структурированный массив, то PyArray_Sort (...) также может использоваться для прямой сортировки массива.

PyObject *PyArray_SearchSorted(PyArrayObject *self, PyObject *values, NPY_SEARCHSIDE сторона, PyObject *perm)#

Эквивалентно ndarray.searchsorted (self, values, сторона, perm). Предполагая self является 1-d массивом в порядке возрастания, тогда вывод представляет собой массив индексов той же формы, что и values таким образом, что если элементы в values были вставлены перед индексами, порядок self будет сохранён. Проверка того, находится ли self в порядке возрастания, не выполняется.

The сторона аргумент указывает, должен ли возвращаемый индекс быть индексом первого подходящего местоположения (если NPY_SEARCHLEFT) или последнего (если NPY_SEARCHRIGHT).

The sorter аргумент, если не NULL, должен быть 1D массив целочисленных индексов той же длины, что и self, которая сортирует его по возрастанию. Обычно это результат вызова PyArray_ArgSort (…) Для нахождения требуемых точек вставки используется двоичный поиск.

int PyArray_Partition(PyArrayObject *self, PyArrayObject *ktharray, int ось, NPY_SELECTKIND which)#: Эквивалентно ndarray.partition (self, ktharray, ось, kind). Разделяет массив так, что значения элемента с индексом ktharray находятся в позициях, в которых они были бы, если массив полностью отсортирован, и помещает все элементы меньше k-го перед ним, а все элементы равные или больше после k-го элемента. Порядок всех элементов внутри разделов не определён. Если self->descr — это тип данных с определенными полями, тогда self->descr->names используется для определения порядка сортировки. Сравнение, в котором первое поле равно, будет использовать второе поле и так далее. Чтобы изменить порядок сортировки структурированного массива, создайте новый тип данных с другим порядком имен и создайте представление массива с этим новым типом данных. Возвращает 0 при успехе и -1 при неудаче.

PyObject *PyArray_ArgPartition(PyArrayObject *op, PyArrayObject *ktharray, int ось, NPY_SELECTKIND which)#: Эквивалентно ndarray.argpartition (self, ktharray, ось, kind). Возвращает массив индексов, таких что выбор этих индексов вдоль заданной axis вернет разделенную версию self.

PyObject *PyArray_Diagonal(PyArrayObject *self, int смещение, int axis1, int axis2)#: Эквивалентно ndarray.diagonal (self, смещение, axis1, axis2 ). Вернуть смещение диагоналей 2-мерных массивов, определенных axis1 и axis2.

npy_intp PyArray_CountNonzero(PyArrayObject *self)#: Подсчитывает количество ненулевых элементов в объекте массива self.

PyObject *PyArray_Nonzero(PyArrayObject *self)#: Эквивалентно ndarray.nonzero (self). Возвращает кортеж индексов массивов, которые выбирают элементы self которые не равны нулю. Если (nd= PyArray_NDIM ( self ))==1, то возвращается один массив индексов. Массивы индексов имеют тип данных NPY_INTP. Если возвращается кортеж (nd \(\neq\) 1), тогда его длина равна nd.

PyObject *PyArray_Compress(PyArrayObject *self, PyObject *условие, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.compress (self, условие, ось ). Возвращает элементы вдоль ось соответствующие элементам условие которые истинны.

Вычисление#

Совет

Передать в NPY_RAVEL_AXIS для axis, чтобы достичь того же эффекта, который получается при передаче axis=None в Python (рассматривая массив как 1-d массив).

Примечание

Аргумент out указывает, куда поместить результат. Если out равен NULL, то выходной массив создается, в противном случае результат помещается в out, который должен иметь правильный размер и тип. Новая ссылка на выходной массив всегда возвращается, даже когда out не равен NULL. Вызывающая сторона несет ответственность Py_DECREF out, если не NULL, иначе произойдет утечка памяти.

PyObject *PyArray_ArgMax(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.argmax (self, ось). Возвращает индекс наибольшего элемента self вдоль ось.

PyObject *PyArray_ArgMin(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.argmin (self, ось). Возвращает индекс наименьшего элемента self вдоль ось.

PyObject *PyArray_Max(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.max (self, ось). Возвращает наибольший элемент self вдоль заданной ось. Когда результат — один элемент, возвращает скаляр numpy вместо ndarray.

PyObject *PyArray_Min(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.min (self, ось). Возвращает наименьший элемент self вдоль заданной ось. Когда результат — один элемент, возвращает скаляр numpy вместо ndarray.

PyObject *PyArray_Ptp(PyArrayObject *self, int ось, PyArrayObject *выход)#: Возвращает разницу между наибольшим элементом self вдоль ось и наименьший элемент self вдоль ось. Когда результат — один элемент, возвращает скаляр numpy вместо ndarray.

Примечание

Аргумент rtype указывает тип данных, над которым должно происходить сокращение. Это важно, если тип данных массива недостаточно "большой" для обработки вывода. По умолчанию все целочисленные типы данных делаются как минимум такими же большими, как NPY_LONG для ufuncs «add» и «multiply» (которые лежат в основе функций mean, sum, cumsum, prod и cumprod).

PyObject *PyArray_Mean(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.mean (self, ось, rtype). Возвращает среднее значение элементов вдоль заданной ось, используя перечисленный тип rtype в качестве типа данных для суммирования. Поведение суммирования по умолчанию получается с использованием NPY_NOTYPE для rtype.

PyObject *PyArray_Trace(PyArrayObject *self, int смещение, int axis1, int axis2, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.trace (self, смещение, axis1, axis2, rtype). Возвращает сумму (используя rtype как тип данных суммирования) по смещение диагональные элементы двумерных массивов, определённых axis1 и axis2 переменные. Положительное смещение выбирает диагонали выше главной диагонали. Отрицательное смещение выбирает диагонали ниже главной диагонали.

PyObject *PyArray_Clip(PyArrayObject *self, PyObject *min, PyObject *max)#: Эквивалентно ndarray.clip (self, min, max). Обрезать массив, self, так что значения больше max зафиксированы на max и значения меньше min зафиксированы на min.

PyObject *PyArray_Conjugate(PyArrayObject *self, PyArrayObject *выход)#

Эквивалентно ndarray.conjugate (self). Возвращает комплексное сопряжение self. Если self не имеет комплексного типа данных, то возвращается self со ссылкой.

Параметры:

self – Входной массив.
выход – Выходной массив. Если предоставлен, результат помещается в этот массив.

Возвращает:

Комплексно сопряжённое от self.

PyObject *PyArray_Round(PyArrayObject *self, int decimals, PyArrayObject *выход)#: Эквивалентно ndarray.round (self, decimals, выход). Возвращает массив с элементами, округлёнными до ближайшего десятичного знака. Десятичный знак определяется как \(10^{-\textrm{decimals}}\) цифра, чтобы отрицательные decimals вызывает округление до ближайших 10, 100 и т.д. Если out — NULL, затем создаётся выходной массив, в противном случае выход размещается в выход который должен быть правильного размера и типа.

PyObject *PyArray_Std(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.std (self, ось, rtype). Возвращает стандартное отклонение, используя данные вдоль ось преобразовано в тип данных rtype.

PyObject *PyArray_Sum(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.sum (self, ось, rtype). Возвращает одномерные векторные суммы элементов в self вдоль ось. Выполнить суммирование после преобразования данных в тип данных rtype.

PyObject *PyArray_CumSum(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.cumsum (self, ось, rtype). Возвращает кумулятивные одномерные суммы элементов в self вдоль ось. Выполните суммирование после преобразования данных в тип данных rtype.

PyObject *PyArray_Prod(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.prod (self, ось, rtype). Возвращает 1-d произведения элементов в self вдоль ось. Выполняет произведение после преобразования данных в тип данных rtype.

PyObject *PyArray_CumProd(PyArrayObject *self, int ось, int rtype, PyArrayObject *выход)#: Эквивалентно ndarray.cumprod (self, ось, rtype). Возвращает 1-мерные кумулятивные произведения элементов в self вдоль axis. Выполнить произведение после преобразования данных в тип данных rtype.

PyObject *PyArray_All(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.all (self, ось). Возвращает массив с элементами True для каждого 1-мерного подмассива self определено axis в котором все элементы равны True.

PyObject *PyArray_Any(PyArrayObject *self, int ось, PyArrayObject *выход)#: Эквивалентно ndarray.any (self, ось). Возвращает массив с элементами True для каждого 1-мерного подмассива self определено ось в котором любой из элементов является True.

Функции#

Функции массивов#

int PyArray_AsCArray(PyObject **op, void *ptr, npy_intp *dims, int nd, PyArray_Descr *typedescr)#

Иногда полезно обращаться к многомерному массиву как к многомерному массиву в стиле C, чтобы алгоритмы могли быть реализованы с использованием синтаксиса C a[i][j][k]. Эта процедура возвращает указатель, ptr, который имитирует этот тип массива в стиле C, для 1-, 2- и 3-мерных ndarrays.

Параметры:

op – Адрес любого объекта Python. Этот объект Python будет заменён эквивалентным, хорошо себя ведущим, C-стильным непрерывным ndarray заданного типа данных, указанного последними двумя аргументами. Убедитесь, что кража ссылки таким образом на входной объект оправдана.
ptr – Адрес переменной (ctype* для 1-d, ctype** для 2-d или ctype*** для 3-d), где ctype — эквивалентный C-тип для типа данных. При возврате, ptr будет доступен как 1-мерный, 2-мерный или 3-мерный массив.
dims – Выходной массив, содержащий форму объекта массива. Этот массив задаёт границы для любого цикла, который будет выполняться.
nd – Размерность массива (1, 2 или 3).
typedescr – A PyArray_Descr структура, указывающая желаемый тип данных (включая требуемый порядок байтов). Вызов украдёт ссылку на параметр.

Примечание

Эмуляция C-стиля массива не завершена для 2D и 3D массивов. Например, эмулированные массивы указателей не могут быть переданы в подпрограммы, ожидающие конкретные, статически определённые 2D и 3D массивы. Для передачи в функции, требующие такие входные данные, необходимо статически определить требуемый массив и скопировать данные.

int PyArray_Free(PyObject *op, void *ptr)#: Должен вызываться с теми же объектами и адресами памяти, возвращёнными из PyArray_AsCArray (…). Эта функция очищает память, которая иначе была бы утеряна.

PyObject *PyArray_Concatenate(PyObject *obj, int ось)#: Объединить последовательность объектов в obj вместе вдоль ось в единый массив. Если размерности или типы несовместимы, возникает ошибка.

PyObject *PyArray_InnerProduct(PyObject *obj1, PyObject *obj2)#: Вычислить произведение-сумму по последним измерениям obj1 и obj2. Ни один массив не сопряжён.

PyObject *PyArray_MatrixProduct(PyObject *obj1, PyObject *obj)#: Вычисляет произведение-сумму по последнему измерению obj1 и предпоследнее измерение obj2. Для двумерных массивов это матричное произведение. Ни один массив не сопряжён.

PyObject *PyArray_MatrixProduct2(PyObject *obj1, PyObject *obj, PyArrayObject *выход)#: То же, что и PyArray_MatrixProduct, но сохраняет результат в выход. Выходной массив должен иметь правильную форму, тип и быть C-непрерывным, иначе будет вызвано исключение.

PyArrayObject *PyArray_EinsteinSum(char *индексы, npy_intp nop, PyArrayObject **op_in, PyArray_Descr *dtype, NPY_ORDER порядок, NPY_CASTING приведение типов, PyArrayObject *выход)#

Применяет соглашение суммирования Эйнштейна к предоставленным операндам массива, возвращая новый массив или помещая результат в выходСтрока в индексы представляет собой список букв индексов, разделенных запятыми. Количество операндов указано в nop, и op_in является массивом, содержащим эти операнды. Тип данных вывода может быть принудительно задан с помощью dtype, порядок вывода можно принудительно задать с помощью порядок (NPY_KEEPORDER рекомендуется), и когда dtype указан, приведение типов указывает, насколько разрешительным должно быть преобразование данных.

См. einsum функцию для получения дополнительных сведений.

PyObject *PyArray_Correlate(PyObject *op1, PyObject *op2, int mode)#

Вычислить 1-d корреляцию 1-d массивов op1 и op2 . Корреляция вычисляется в каждой выходной точке путем умножения op1 сдвинутой версией op2 и суммирование результата. В результате сдвига необходимые значения вне определённого диапазона op1 и op2 интерпретируются как нули. Режим определяет, сколько сдвигов возвращать: 0 — возвращать только сдвиги, которые не требовали предположения нулевых значений; 1 — возвращать объект того же размера, что и op1, 2 - возвращать все возможные сдвиги (принимается любое перекрытие).

Примечания

Это не вычисляет обычную корреляцию: если op2 больше op1, аргументы меняются местами, и для комплексных массивов никогда не берётся сопряжённое значение. См. PyArray_Correlate2 для обычной корреляции в обработке сигналов.

PyObject *PyArray_Correlate2(PyObject *op1, PyObject *op2, int mode)#

Обновлённая версия PyArray_Correlate, которая использует обычное определение корреляции для одномерных массивов. Корреляция вычисляется в каждой выходной точке путем умножения op1 сдвинутой версией op2 и суммирование результата. В результате сдвига необходимые значения вне определённого диапазона op1 и op2 интерпретируются как ноль. Режим определяет, сколько сдвигов возвращать: 0 — возвращать только сдвиги, которые не требовали предположения нулевых значений; 1 — возвращать объект того же размера, что и op1, 2 - возвращать все возможные сдвиги (принимается любое перекрытие).

Примечания

Вычислите z следующим образом:

z[k] = sum_n op1[n] * conj(op2[n+k])

PyObject *PyArray_Where(PyObject *условие, PyObject *x, PyObject *y)#: Если оба x и y являются NULL, затем вернуть PyArray_Nonzero (условие). В противном случае, оба x и y должен быть указан, и возвращаемый объект имеет форму, подобную условие и имеет элементы x и y где условие соответственно True или False.

Другие функции#

npy_bool PyArray_CheckStrides(int elsize, int nd, npy_intp numbytes, npy_intp const *dims, npy_intp const *newstrides)#: Определить, если newstrides является массивом шагов, согласованным с памятью nd -мерный массив с формой dims и размер элемента, elsize. newstrides проверяется, будет ли прыжок на указанное количество байтов в каждом направлении когда-либо означать прыжок более чем numbytes который является предполагаемым размером доступного сегмента памяти. Если numbytes равно 0, тогда эквивалент numbytes вычисляется в предположении nd, dims, и elsize ссылается на массив с одним сегментом. Возвращает NPY_TRUE if newstrides приемлемо, иначе вернуть NPY_FALSE.

npy_intp PyArray_MultiplyList(npy_intp const *seq, int n)#

int PyArray_MultiplyIntList(int const *seq, int n)#: Обе эти процедуры умножают n -длинный массив, seq, из целых чисел и возвращает результат. Проверка переполнения не выполняется.

int PyArray_CompareLists(npy_intp const *l1, npy_intp const *l2, int n)#: Даны два n -длинные массивы целых чисел, l1, и l2, возвращает 1, если списки идентичны; в противном случае возвращает 0.

Вспомогательные данные с объектной семантикой#

тип NpyAuxData#

При работе с более сложными типами данных, которые состоят из других типов данных, таких как структурированный dtype, создание внутренних циклов, манипулирующих типами данных, требует передачи дополнительных данных. NumPy поддерживает эту идею через структурированный NpyAuxData, устанавливая несколько соглашений, чтобы это было возможно.

Определение NpyAuxData похоже на определение класса в C++, но семантику объекта приходится отслеживать вручную, поскольку API написан на C. Вот пример функции, которая удваивает элемент, используя функцию копирования элемента как примитив.

typedef struct {
    NpyAuxData base;
    ElementCopier_Func *func;
    NpyAuxData *funcdata;
} eldoubler_aux_data;

void free_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *d = (eldoubler_aux_data *)data;
    /* Free the memory owned by this auxdata */
    NPY_AUXDATA_FREE(d->funcdata);
    PyArray_free(d);
}

NpyAuxData *clone_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        return NULL;
    }

    /* Raw copy of all data */
    memcpy(ret, data, sizeof(eldoubler_aux_data));

    /* Fix up the owned auxdata so we have our own copy */
    ret->funcdata = NPY_AUXDATA_CLONE(ret->funcdata);
    if (ret->funcdata == NULL) {
        PyArray_free(ret);
        return NULL;
    }

    return (NpyAuxData *)ret;
}

NpyAuxData *create_element_doubler_aux_data(
                            ElementCopier_Func *func,
                            NpyAuxData *funcdata)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        PyErr_NoMemory();
        return NULL;
    }
    memset(&ret, 0, sizeof(eldoubler_aux_data));
    ret->base->free = &free_element_doubler_aux_data;
    ret->base->clone = &clone_element_doubler_aux_data;
    ret->func = func;
    ret->funcdata = funcdata;

    return (NpyAuxData *)ret;
}

тип NpyAuxData_FreeFunc#: Тип указателя на функцию для функций освобождения NpyAuxData.

тип NpyAuxData_CloneFunc#: Тип указателя на функцию для функций клонирования NpyAuxData. Эти функции никогда не должны устанавливать исключение Python при ошибке, потому что они могут вызываться из многопоточного контекста.

void NPY_AUXDATA_FREE(NpyAuxData *вспомогательные данные)#: Макрос, который вызывает функцию освобождения auxdata соответствующим образом, ничего не делает, если auxdata равен NULL.

NpyAuxData *NPY_AUXDATA_CLONE(NpyAuxData *вспомогательные данные)#: Макрос, который вызывает функцию клонирования вспомогательных данных соответствующим образом, возвращая глубокую копию вспомогательных данных.

Итераторы массивов#

Начиная с NumPy 1.6.0, эти итераторы массивов заменены новым итератором массивов, NpyIter.

Итератор массива — это простой способ быстрого и эффективного доступа к элементам N-мерного массива, как показано в пример которая предоставляет более подробное описание этого полезного подхода к перебору массива из C.

PyObject *PyArray_IterNew(PyObject *arr)#: Возвращает объект итератора массива из массива, arr. Это эквивалентно arr. flat. Объект итератора массива упрощает перебор N-мерного непрерывного массива в стиле C.

PyObject *PyArray_IterAllButAxis(PyObject *arr, int *ось)#: Возвращает итератор массива, который будет перебирать все оси, кроме указанной в. Параметр имеет то же значение, что и в функциях редукции, таких как *axisВозвращённый итератор нельзя использовать с PyArray_ITER_GOTO1D. Этот итератор можно использовать для написания чего-то похожего на то, что делают ufuncs, где цикл по наибольшей оси выполняется отдельной подпрограммой. Если *axis отрицательно, тогда *axis будет установлена на ось с наименьшим шагом, и эта ось будет использована.

PyObject *PyArray_BroadcastToShape(PyObject *arr, npy_intp const *измерения, int nd)#: Возвращает итератор массива, который транслируется для итерации как массив формы, заданной измерения и nd.

int PyArrayIter_Check(PyObject *op)#: Вычисляет true, если op является итератором массива (или экземпляром подкласса типа итератора массива).

void PyArray_ITER_RESET(PyObject *итератор)#: Сбросить итератор в начало массива.

void PyArray_ITER_NEXT(PyObject *итератор)#: Увеличить индекс и член dataptr в итератор чтобы указывать на следующий элемент массива. Если массив не является (C-style) непрерывным, также увеличивайте N-мерные координаты массива.

void *PyArray_ITER_DATA(PyObject *итератор)#: Указатель на текущий элемент массива.

void PyArray_ITER_GOTO(PyObject *итератор, npy_intp *назначение)#: Установить итератор члены index, dataptr и coordinates в местоположение в массиве, указанное N-мерным c-массивом, назначение, который должен иметь размер не менее итератор ->nd_m1+1.

void PyArray_ITER_GOTO1D(PyObject *итератор, npy_intp index)#: Установить итератор index и dataptr к местоположению в массиве, указанному целым числом index который указывает на элемент в C-стиле сглаженного массива.

int PyArray_ITER_NOTDONE(PyObject *итератор)#: Возвращает TRUE, пока итератор не прошел через все элементы, в противном случае возвращает FALSE.

Трансляция (множественные итераторы)#

PyObject *PyArray_MultiIterNew(int число, ...)#: Упрощённый интерфейс для трансляции. Эта функция принимает количество массивов для трансляции, а затем число дополнительный ( PyObject * ) аргументы. Эти аргументы преобразуются в массивы, и создаются итераторы. PyArray_Broadcast затем вызывается на результирующем мульти-итераторном объекте. Результирующий, транслированный мульти-итераторный объект затем возвращается. Транслированная операция может затем быть выполнена с использованием одного цикла и с помощью PyArray_MultiIter_NEXT (..)

void PyArray_MultiIter_RESET(PyObject *multi)#: Сбросить все итераторы в начало в объекте с несколькими итераторами, multi.

void PyArray_MultiIter_NEXT(PyObject *multi)#: Продвинуть каждый итератор в объекте мульти-итератора, multi, к его следующему (расширенному) элементу.

void *PyArray_MultiIter_DATA(PyObject *multi, int i)#: Возвращает указатель на данные i \(^{\textrm{th}}\) итератор в объекте мульти-итератора.

void PyArray_MultiIter_NEXTi(PyObject *multi, int i)#: Переместить указатель только для i \(^{\textrm{th}}\) Продвинутые инструменты отладки

void PyArray_MultiIter_GOTO(PyObject *multi, npy_intp *назначение)#: Продвинуть каждый итератор в объекте мульти-итератора, multi, к заданному \(N\) -мерный назначение где \(N\) — это количество измерений в транслируемом массиве.

void PyArray_MultiIter_GOTO1D(PyObject *multi, npy_intp index)#: Продвинуть каждый итератор в объекте мульти-итератора, multi, в соответствующее местоположение index в сглаженный распространённый массив.

int PyArray_MultiIter_NOTDONE(PyObject *multi)#: Возвращает TRUE, пока мульти-итератор не прошел через все элементы (транслированного результата), иначе возвращает FALSE.

npy_intp PyArray_MultiIter_SIZE(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает общий размер после трансляции для объекта мульти-итератора.

int PyArray_MultiIter_NDIM(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает количество измерений в транслируемом результате объекта multi-iterator.

npy_intp PyArray_MultiIter_INDEX(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает текущий (одномерный) индекс в результат вещания объекта multi-iterator.

int PyArray_MultiIter_NUMITER(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает количество итераторов, представленных объектом мульти-итератора.

void **PyArray_MultiIter_ITERS(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает массив объектов-итераторов, содержащих итераторы для массивов, которые должны быть транслированы вместе. При возврате итераторы настроены для трансляции.

npy_intp *PyArray_MultiIter_DIMS(PyArrayMultiIterObject *multi)#: Новое в версии 1.26.0.

Возвращает указатель на размеры/форму результата вещания объекта multi-iterator.

int PyArray_Broadcast(PyArrayMultiIterObject *mit)#: Эта функция инкапсулирует правила трансляции. mit контейнер уже должен содержать итераторы для всех массивов, которые нужно транслировать. При возврате эти итераторы будут скорректированы так, что итерация по каждому одновременно выполнит трансляцию. Возвращается отрицательное число, если возникает ошибка.

int PyArray_RemoveSmallest(PyArrayMultiIterObject *mit)#: Эта функция принимает объект мультиитератора, который был ранее "транслирован", находит измерение с наименьшей "суммой шагов" в транслированном результате и адаптирует все итераторы, чтобы не итерировать по этому измерению (эффективно делая их длиной 1 в этом измерении). Соответствующее измерение возвращается, если только mit -> если nd равно 0, то возвращается -1. Эта функция полезна для построения подпрограмм, подобных ufunc, которые правильно транслируют свои входные данные, а затем вызывают одномерную версию подпрограммы с шагом как внутренний цикл. Эта одномерная версия обычно оптимизирована для скорости, и по этой причине цикл должен выполняться по оси, которая не потребует больших скачков шага.

Итератор окрестности#

Итераторы окрестностей являются подклассами объекта-итератора и могут использоваться для итерации по окрестности точки. Например, вы можете захотеть итерироваться по каждому вокселю 3D-изображения и для каждого такого вокселя итерироваться по гиперкубу. Итератор окрестности автоматически обрабатывает границы, что делает написание такого кода гораздо проще, чем ручная обработка границ, ценой небольшого снижения производительности.

PyObject *PyArray_NeighborhoodIterNew(PyArrayIterObject *iter, npy_intp границы, int mode, PyArrayObject *fill_value)#

Эта функция создает новый итератор окрестности из существующего итератора. Окрестность будет вычислена относительно позиции, на которую в данный момент указывает iter, границы определяют форму итератора соседства, а аргумент mode — режим обработки границ.

The границы аргумент ожидается как массивы размером (2 * iter->ao->nd), такие что диапазон bound[2*i]->bounds[2*i+1] определяет диапазон для обхода по измерению i (оба граничных значения включены в обходимые координаты). Границы должны быть упорядочены для каждого измерения (bounds[2*i] <= bounds[2*i+1]).

Режим должен быть одним из:

NPY_NEIGHBORHOOD_ITER_ZERO_PADDING#: Нулевое заполнение. Значения за пределами границ будут равны 0.

NPY_NEIGHBORHOOD_ITER_ONE_PADDING#: Один отступ, значения за пределами границ будут равны 1.

NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING#: Постоянное заполнение. Значения за пределами границ будут такими же, как первый элемент в fill_value.

NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING#: Зеркальное заполнение. Значения за пределами границ будут такими, как если бы элементы массива были отражены. Например, для массива [1, 2, 3, 4], x[-2] будет 2, x[-2] будет 1, x[4] будет 4, x[5] будет 1, и т.д.

NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING#: Циклическое заполнение. Значения за пределами границ будут такими, как если бы массив повторялся. Например, для массива [1, 2, 3, 4], x[-2] будет 3, x[-1] будет 4, x[4] будет 1, x[5] будет 2 и т.д.

Если режим — постоянное заполнение (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING), fill_value должен указывать на объект массива, который содержит значение заполнения (первый элемент будет значением заполнения, если массив содержит более одного элемента). В других случаях fill_value может быть NULL.

Итератор хранит ссылку на iter
Возвращает NULL при неудаче (в этом случае счётчик ссылок итератора не изменяется)
сам iter может быть итератором окрестности: это может быть полезно, например, для автоматической обработки границ
объект, возвращаемый этой функцией, должен быть безопасен для использования в качестве обычного итератора
Если позиция итератора изменена, любой последующий вызов PyArrayNeighborhoodIter_Next является неопределённым поведением, и необходимо вызвать PyArrayNeighborhoodIter_Reset.
Если позиция итератора не является началом данных и базовые данные для итератора непрерывны, итератор будет указывать на начало данных вместо позиции, на которую указывает итератор. Чтобы избежать этой ситуации, итератор следует переместить в требуемую позицию только после создания итератора, и необходимо вызвать PyArrayNeighborhoodIter_Reset.

PyArrayIterObject *iter;
PyArrayNeighborhoodIterObject *neigh_iter;
iter = PyArray_IterNew(x);

/*For a 3x3 kernel */
bounds = {-1, 1, -1, 1};
neigh_iter = (PyArrayNeighborhoodIterObject*)PyArray_NeighborhoodIterNew(
     iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL);

for(i = 0; i < iter->size; ++i) {
     for (j = 0; j < neigh_iter->size; ++j) {
             /* Walk around the item currently pointed by iter->dataptr */
             PyArrayNeighborhoodIter_Next(neigh_iter);
     }

     /* Move to the next point of iter */
     PyArrayIter_Next(iter);
     PyArrayNeighborhoodIter_Reset(neigh_iter);
}

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject *iter)#: Сбросить позицию итератора в первую точку окрестности. Это должно вызываться всякий раз, когда изменяется аргумент iter, переданный в PyArray_NeighborhoodIterObject (см. пример)

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject *iter)#: После этого вызова iter->dataptr указывает на следующую точку окрестности. Вызов этой функции после посещения всех точек окрестности не определён.

Скаляры массива#

PyObject *PyArray_Return(PyArrayObject *arr)#

Эта функция крадет ссылку на arr.

Эта функция проверяет, является ли arr является 0-мерным массивом и, если да, возвращает соответствующий скаляр массива. Его следует использовать всякий раз, когда могут быть возвращены 0-мерные массивы в Python.

PyObject *PyArray_Scalar(void *данные, PyArray_Descr *dtype, PyObject *основание)#

Возвращает объект скаляра массива заданного dtype by копирование из памяти, на которую указывает данные. основание ожидается, что это будет объект массива, который является владельцем данных. основание требуется, если dtype является void скаляр, или если NPY_USE_GETITEM флаг установлен и известно, что getitem метод использует arr аргумент без проверки, является ли он NULL. В противном случае основание может быть NULL.

Если данные не в собственном порядке байтов (как указано dtype->byteorder) тогда эта функция поменяет порядок байтов данных, поскольку скаляры массивов всегда в правильном порядке байтов машины.

PyObject *PyArray_ToScalar(void *данные, PyArrayObject *arr)#: Возвращает объект скаляра массива типа и размера элемента, указанного объектом массива arr скопировано из памяти, на которую указывает данные и обмен, если данные в arr не в машинном порядке байтов.

PyObject *PyArray_FromScalar(PyObject *скаляр, PyArray_Descr *outcode)#: Возвращает 0-мерный массив типа, определяемого outcode из скаляр который должен быть объектом-скаляром массива. Если outcode если NULL, то тип определяется из скаляр.

void PyArray_ScalarAsCtype(PyObject *скаляр, void *ctypeptr)#: Вернуть в ctypeptr указатель на фактическое значение в скаляре массива. Проверка ошибок отсутствует, поэтому скаляр должен быть объектом-скаляром массива, и ctypeptr должен иметь достаточно места для хранения правильного типа. Для типов с гибким размером указатель на данные копируется в память ctypeptr, для всех остальных типов фактические данные копируются по адресу, указанному ctypeptr.

int PyArray_CastScalarToCtype(PyObject *скаляр, void *ctypeptr, PyArray_Descr *outcode)#

Возвращает данные (приведённые к типу данных, указанному outcode) из скаляра массива, скалярв память, на которую указывает ctypeptr (который должен быть достаточно большим для обработки входящей памяти).

Возвращает -1 при неудаче и 0 при успехе.

PyObject *PyArray_TypeObjectFromType(int тип)#: Возвращает объект скалярного типа по номеру типа, тип . Эквивалентно PyArray_DescrFromType (тип)->typeobj за исключением подсчёта ссылок и проверки ошибок. Возвращает новую ссылку на объект типа при успехе или NULL при неудаче.

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject **arr)#

Устаревший способ запроса специального продвижения для скалярных значений. Он больше не используется в самом NumPy и ожидается, что будет устаревшим в будущем.

Новые DTypes могут определять правила продвижения, специфичные для скаляров Python.

int PyArray_CanCoerceScalar(char thistype, char neededtype, NPY_SCALARKIND скаляр)#

Устаревший способ запроса специального продвижения для скалярных значений. Он больше не используется в самом NumPy и ожидается, что будет устаревшим в будущем.

Используйте PyArray_ResultType для аналогичных целей.

Дескрипторы типов данных#

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

Объекты типов данных должны иметь подсчёт ссылок, поэтому будьте внимательны к действиям на ссылку типа данных при различных вызовах C-API. Стандартное правило заключается в том, что когда объект типа данных возвращается, это новая ссылка. Функции, которые принимают PyArray_Descr* объекты и возвращаемые массивы заимствуют ссылки на тип данных своих входных данных, если не указано иное. Поэтому вы должны владеть ссылкой на любой объект типа данных, используемый в качестве входных данных для такой функции.

int PyArray_DescrCheck(PyObject *obj)#: Вычисляется как истина, если obj является объектом типа данных ( PyArray_Descr* ).

PyArray_Descr *PyArray_DescrNew(PyArray_Descr *obj)#: Возвращает новый объект типа данных, скопированный из obj (ссылка на поля просто обновляется, чтобы новый объект указывал на тот же словарь полей, если он есть).

PyArray_Descr *PyArray_DescrNewFromType(int typenum)#: Создать новый объект типа данных из встроенного (или зарегистрированного пользователем) типа данных, указанного typenum. Все встроенные типы не должны изменять свои поля. Это создаёт новую копию PyArray_Descr структуру, чтобы вы могли заполнить её соответствующим образом. Эта функция особенно необходима для гибких типов данных, которым требуется новый член elsize, чтобы быть значимыми при построении массива.

PyArray_Descr *PyArray_DescrNewByteorder(PyArray_Descr *obj, char newendian)#

Создать новый объект типа данных с порядком байтов, установленным в соответствии с newendian. Все упомянутые объекты типов данных (в subdescr и fields членах объекта типа данных) также изменяются (рекурсивно).

Значение newendian является одним из этих макросов:

NPY_IGNORE#
NPY_SWAP#
NPY_NATIVE#
NPY_LITTLE#
NPY_BIG#: Если порядок байтов NPY_IGNORE при встрече оставляется без изменений. Если newendian NPY_SWAP, то все порядки байтов меняются местами. Другие допустимые значения newendian: NPY_NATIVE, NPY_LITTLE, и NPY_BIG которые все приводят к тому, что возвращаемый дескриптор типа данных (и все его ссылочные дескрипторы типов данных) имеют соответствующий порядок байтов.

PyArray_Descr *PyArray_DescrFromObject(PyObject *op, PyArray_Descr *mintype)#: Определить подходящий объект типа данных из объекта op (который должен быть "вложенным" объектом последовательности) и минимальный дескриптор типа данных mintype (который может быть NULL ). Похоже по поведению на array(op).dtype. Не путайте эту функцию с PyArray_DescrConverter. Эта функция по сути просматривает все объекты в (вложенной) последовательности и определяет тип данных на основе найденных элементов.

PyArray_Descr *PyArray_DescrFromScalar(PyObject *скаляр)#: Возвращает объект типа данных из объекта скаляра массива. Проверка того, что скаляр является скаляром массива. Если не удается определить подходящий тип данных, то тип данных NPY_OBJECT возвращается по умолчанию.

PyArray_Descr *PyArray_DescrFromType(int typenum)#: Возвращает объект типа данных, соответствующий typenum. typenum может быть одним из перечисленных типов, символьным кодом для одного из перечисленных типов или пользовательским типом. Если вы хотите использовать массив переменного размера, то вам нужно flexible typenum и установить результаты elsize параметр до желаемого размера. Типный номер является одним из NPY_TYPES.

int PyArray_DescrConverter(PyObject *obj, PyArray_Descr **dtype)#: Преобразовать любой совместимый объект Python, obj, в объект типа данных в dtype. Большое количество объектов Python может быть преобразовано в объекты типа данных. См. Объекты типа данных (dtype) для полного описания. Эта версия конвертера преобразует объекты None в NPY_DEFAULT_TYPE объект типа данных. Эта функция может использоваться с кодом символа “O&” в PyArg_ParseTuple обработка.

int PyArray_DescrConverter2(PyObject *obj, PyArray_Descr **dtype)#: Преобразовать любой совместимый объект Python, obj, в объект типа данных в dtype. Эта версия конвертера преобразует None объекты так, чтобы возвращаемый тип данных был NULL. Эта функция также может использоваться с символом “O&” в обработке PyArg_ParseTuple.

int PyArray_DescrAlignConverter(PyObject *obj, PyArray_Descr **dtype)#: Как PyArray_DescrConverter за исключением того, что он выравнивает объекты, подобные C-структурам, по границам слов, как это сделал бы компилятор.

int PyArray_DescrAlignConverter2(PyObject *obj, PyArray_Descr **dtype)#: Как PyArray_DescrConverter2 за исключением того, что он выравнивает объекты, подобные C-структурам, по границам слов, как это сделал бы компилятор.

Продвижение и проверка типов данных#

PyArray_DTypeMeta *PyArray_CommonDType(const PyArray_DTypeMeta *dtype1, const PyArray_DTypeMeta *dtype2)#: Эта функция определяет общий тип данных DType. Обратите внимание, что общий DType не будет object (если только один из типов данных не object). Аналогично numpy.result_type, но работает с классами, а не с экземплярами.

PyArray_DTypeMeta *PyArray_PromoteDTypeSequence(npy_intp длина, PyArray_DTypeMeta **dtypes_in)#

Повышает список DTypes друг с другом таким образом, чтобы гарантировать стабильные результаты даже при изменении порядка. Эта функция умнее и часто может возвращать успешные и однозначные результаты, когда common_dtype(common_dtype(dt1, dt2), dt3) зависел бы от порядка операций или завершался неудачей. Тем не менее, типы данных должны стремиться гарантировать, что их реализация общего типа данных является ассоциативной и коммутативной! (В основном, беззнаковые и знаковые целые числа таковыми не являются.)

Для гарантированной согласованности результатов DTypes должны реализовывать общий DType «транзитивно». Если A продвигает B и B продвигает C, то A обычно также должен продвигать C; где «продвигает» означает реализует продвижение. (Есть некоторые исключения для абстрактных DTypes)

В целом этот подход всегда работает, пока наиболее общий тип данных либо строго больше, либо совместим со всеми другими типами данных. Например, повышение float16 с любым другим числом с плавающей точкой, целым или беззнаковым целым снова дает число с плавающей точкой.

PyArray_Descr *PyArray_GetDefaultDescr(const PyArray_DTypeMeta *DType)#: Для данного класса DType возвращает экземпляр по умолчанию (дескриптор). Это проверяет наличие singleton сначала и только затем вызывает default_descr функцию, если необходимо.

Пользовательские типы данных#

Добавлено в версии 2.0.

Эти функции позволяют определять пользовательские гибкие типы данных вне NumPy. См. NEP 42 для получения дополнительных сведений о причинах и дизайне новой системы DType. См. репозиторий numpy-user-dtypes для ряда примеров DTypes. Также см. PyArray_DTypeMeta и PyArrayDTypeMeta_Spec для документации по PyArray_DTypeMeta и PyArrayDTypeMeta_Spec.

int PyArrayInitDTypeMeta_FromSpec(PyArray_DTypeMeta *Dtype, PyArrayDTypeMeta_Spec *спецификация)#: Инициализирует новый DType. В настоящее время это должен быть статический тип Python C, объявленный как PyArray_DTypeMeta и не PyTypeObject. Кроме того, он должен быть подклассом np.dtype и установить его тип в PyArrayDTypeMeta_Type (перед вызовом PyType_Ready), который имеет дополнительные поля по сравнению с обычным PyTypeObject. См. примеры в numpy-user-dtypes репозиторий для использования с параметрическими и непараметрическими типами данных.

Флаги#

Флаги, которые могут быть установлены на PyArrayDTypeMeta_Spec для инициализации DType.

NPY_DT_ABSTRACT#: Указывает, что DType является абстрактным "базовым" DType в иерархии DType и не должен напрямую инстанцироваться.

NPY_DT_PARAMETRIC#: Указывает, что DType является параметрическим и не имеет уникального синглтонного экземпляра.

NPY_DT_NUMERIC#: Указывает, что DType представляет числовое значение.

Идентификаторы слотов и определения типов функций API#

Эти ID соответствуют слотам в API DType и используются для идентификации реализаций каждого слота из элементов slots член массива PyArrayDTypeMeta_Spec struct.

NPY_DT_discover_descr_from_pyobject#

typedef PyArray_Descr *(PyArrayDTypeMeta_DiscoverDescrFromPyobject)(PyArray_DTypeMeta *cls, PyObject *obj)#: Используется во время вывода типа данных для нахождения правильного типа данных для данного объекта PyObject. Должен возвращать экземпляр дескриптора, подходящий для хранения данных в переданном объекте Python. obj является объектом Python для проверки и cls является классом DType для создания дескриптора.

NPY_DT_default_descr#

typedef PyArray_Descr *(PyArrayDTypeMeta_DefaultDescriptor)(PyArray_DTypeMeta *cls)#: Возвращает экземпляр дескриптора по умолчанию для DType. Должен быть определен для параметрических типов данных. Непараметрические типы данных по умолчанию возвращают синглтон.

NPY_DT_common_dtype#

typedef PyArray_DTypeMeta *(PyArrayDTypeMeta_CommonDType)(PyArray_DTypeMeta *dtype1, PyArray_DTypeMeta *dtype2)#: Для двух входных DTypes определяет подходящий «общий» DType, который может хранить значения для обоих типов. Возвращает Py_NotImplemented если такой тип не существует.

NPY_DT_common_instance#

typedef PyArray_Descr *(PyArrayDTypeMeta_CommonInstance)(PyArray_Descr *dtype1, PyArray_Descr *dtype2)#: Для двух входных дескрипторов определяет подходящий "общий" дескриптор, который может хранить значения для обоих экземпляров. Возвращает NULL при ошибке.

NPY_DT_ensure_canonical#

typedef PyArray_Descr *(PyArrayDTypeMeta_EnsureCanonical)(PyArray_Descr *dtype)#: Возвращает «каноническое» представление для экземпляра дескриптора. Понятие канонического дескриптора обобщает концепцию порядка байтов, поскольку канонический дескриптор всегда имеет собственный порядок байтов. Если дескриптор уже канонический, эта функция возвращает новую ссылку на входной дескриптор.

NPY_DT_setitem#

typedef int (PyArrayDTypeMeta_SetItem)(PyArray_Descr*, PyObject*, char*)#: Реализует скалярное присваивание для элемента массива с заданным PyObject.

NPY_DT_getitem#

typedef PyObject *(PyArrayDTypeMeta_GetItem)(PyArray_Descr*, char*)#: Реализует скалярное получение элемента для элемента массива. Должен возвращать скаляр Python.

NPY_DT_get_clear_loop#: Если определено, устанавливает цикл обхода, который очищает данные в массиве. Это наиболее полезно для массивов ссылок, которые должны очищать записи массива перед сборкой мусора. Реализует PyArrayMethod_GetTraverseLoop.

NPY_DT_get_fill_zero_loop#: Если определено, устанавливает цикл обхода, который заполняет массив "нулевыми" значениями, которые могут иметь специфичное для DType значение. Это вызывается внутри numpy.zeros для массивов, которым необходимо записать пользовательское значение-метку, представляющее ноль, если по какой-то причине массив, заполненный нулями, недостаточен. Реализует PyArrayMethod_GetTraverseLoop.

NPY_DT_finalize_descr#

typedef PyArray_Descr *(PyArrayDTypeMeta_FinalizeDescriptor)(PyArray_Descr *dtype)#: Если определено, функция, которая вызывается для 'финализации' экземпляра дескриптора после создания массива. Одно из применений этой функции — принудительное создание новых массивов с новым экземпляром дескриптора, независимо от того, какой входной дескриптор предоставлен пользователем.

NPY_DT_get_constant#

typedef int (PyArrayDTypeMeta_GetConstant)(PyArray_Descr *descr, int constant_id, void *выход)#

Если определено, позволяет DType раскрывать постоянные значения, такие как машинные ограничения, специальные значения (бесконечность, NaN) и характеристики чисел с плавающей точкой. descr является экземпляром дескриптора, constant_id является одним из NPY_CONSTANT_* макросы, и выход это указатель на неинициализированную память, куда должно быть записано постоянное значение. Память, на которую указывает выход может быть невыровненным и неинициализированным. Возвращает 1 при успехе, 0 если константа недоступна, или -1 с установленной ошибкой.

Постоянные идентификаторы:

Следующие идентификаторы констант определены для получения значений, специфичных для типа данных:

Базовые константы (доступно для всех числовых типов):

NPY_CONSTANT_zero#: Нулевое значение для dtype.

NPY_CONSTANT_one#: Единственное значение для dtype.

NPY_CONSTANT_minimum_finite#: Минимальное конечное значение, представимое данным типом данных. Для типов с плавающей запятой это наиболее отрицательное конечное значение (например, -FLT_MAX).

NPY_CONSTANT_maximum_finite#: Максимальное конечное значение, представимое типом данных.

Специальные значения с плавающей запятой:

NPY_CONSTANT_inf#: Положительная бесконечность (только для типов с плавающей точкой).

NPY_CONSTANT_ninf#: Отрицательная бесконечность (только для типов с плавающей точкой).

NPY_CONSTANT_nan#: Не-число (только для типов с плавающей запятой).

Характеристики чисел с плавающей запятой (значения собственного типа dtype):

NPY_CONSTANT_finfo_radix#: Основание (база) представления с плавающей запятой. Для всех типов с плавающей запятой это 2.

NPY_CONSTANT_finfo_eps#: Машинный эпсилон: разница между 1.0 и следующим представимым значением, большим 1.0. Соответствует макросам C, таким как FLT_EPSILON, DBL_EPSILON.

Примечание

Для long double в формате IBM double-double (PowerPC) это определяется как 0x1p-105L (2^-105) на основе ~106 бит точности мантиссы.

NPY_CONSTANT_finfo_epsneg#: Разница между 1.0 и следующим представимым значением меньше 1.0. Обычно eps / radix для двоичных типов с плавающей запятой.

NPY_CONSTANT_finfo_smallest_normal#: Наименьшее положительное нормализованное число с плавающей запятой. Соответствует C-макросам, таким как FLT_MIN, DBL_MINЭто наименьшее значение с ведущим битом 1 в мантиссе.

NPY_CONSTANT_finfo_smallest_subnormal#: Наименьшее положительное субнормальное (денормализованное) число с плавающей точкой. Соответствует макросам C, таким как FLT_TRUE_MIN, DBL_TRUE_MIN. Это наименьшее представимое положительное значение с ведущими нулевыми битами в мантиссе.

Характеристики чисел с плавающей запятой (целые значения, тип npy_intp):

Эти константы возвращают целочисленные метаданные о представлении чисел с плавающей запятой. Они помечены 1 << 16 бит, указывающий, что они возвращают npy_intp значения, а не нативный тип dtype.

NPY_CONSTANT_finfo_nmant#: Количество битов мантиссы (без учета неявного старшего бита). Например, IEEE 754 binary64 (double) имеет 52 явных бита мантиссы, поэтому возвращается 52. Соответствует MANT_DIG - 1 из стандартных макросов C.

NPY_CONSTANT_finfo_min_exp#: Минимальное значение экспоненты. Это минимальное отрицательное целое число, такое что основание, возведенное в степень на единицу меньше этого числа, является нормализованным числом с плавающей запятой. Соответствует MIN_EXP - 1 из стандартных макросов C (например, FLT_MIN_EXP - 1).

NPY_CONSTANT_finfo_max_exp#: Максимальное значение экспоненты. Это максимальное положительное целое число, такое что основание, возведённое в степень на единицу меньше этого числа, является представимым конечным числом с плавающей запятой. Соответствует MAX_EXP из стандартных макросов C (например, FLT_MAX_EXP).

NPY_CONSTANT_finfo_decimal_digits#: Количество десятичных знаков точности. Соответствует DIG из C стандартных макросов (например, FLT_DIG, DBL_DIG).

Слоты PyArray_ArrFuncs#

В дополнение к вышеуказанным слотам, следующие слоты открыты для разрешения заполнения PyArray_ArrFuncs структура, прикрепленная к экземплярам дескриптора . Обратите внимание, что в будущем они будут заменены на соответствующие слоты API DType, но пока мы раскрыли устаревшие PyArray_ArrFuncs слоты.

NPY_DT_PyArray_ArrFuncs_getitem#: Позволяет установить getitem для каждого типа данных. Обратите внимание, что это не обязательно определять, если не используется версия по умолчанию, вызывающая функцию, определённую с помощью NPY_DT_getitem ID не подходит. Эта версия будет немного быстрее, чем использование NPY_DT_getitem за счёт иногда необходимости обработки входного массива NULL.

NPY_DT_PyArray_ArrFuncs_setitem#: Позволяет установить per-dtype setitem. Обратите внимание, что это не обязательно определять, если не используется версия по умолчанию, вызывающая функцию, определенную с помощью NPY_DT_setitem ID непригоден по какой-либо причине.

NPY_DT_PyArray_ArrFuncs_compare#: Вычисляет сравнение для numpy.sort, реализует PyArray_CompareFunc.

NPY_DT_PyArray_ArrFuncs_argmax#: Вычисляет argmax для numpy.argmax, реализует PyArray_ArgFunc.

NPY_DT_PyArray_ArrFuncs_argmin#: Вычисляет argmin для numpy.argmin, реализует PyArray_ArgFunc.

NPY_DT_PyArray_ArrFuncs_dotfunc#: Вычисляет скалярное произведение для numpy.dot, реализует PyArray_DotFunc.

NPY_DT_PyArray_ArrFuncs_scanfunc#: Форматированная функция ввода для numpy.fromfile, реализует PyArray_ScanFunc.

NPY_DT_PyArray_ArrFuncs_fromstr#: Функция парсинга строк для numpy.fromstring, реализует PyArray_FromStrFunc.

NPY_DT_PyArray_ArrFuncs_nonzero#: Вычисляет ненулевую функцию для numpy.nonzero, реализует PyArray_NonzeroFunc.

NPY_DT_PyArray_ArrFuncs_fill#: Функция заполнения массива для numpy.ndarray.fill, реализует PyArray_FillFunc.

NPY_DT_PyArray_ArrFuncs_fillwithscalar#: Функция для заполнения массива скалярным значением для numpy.ndarray.fill, реализует PyArray_FillWithScalarFunc.

NPY_DT_PyArray_ArrFuncs_sort#: Массив PyArray_SortFunc длиной NPY_NSORTS. Если установлено, позволяет определять пользовательские реализации сортировки для каждого из алгоритмов сортировки, реализованных в numpy.

NPY_DT_PyArray_ArrFuncs_argsort#: Массив PyArray_ArgSortFunc длиной NPY_NSORTS. Если установлено, позволяет определять пользовательские реализации сортировки для каждого из алгоритмов сортировки, реализованных в numpy.

Макросы и статические встроенные функции#

Эти макросы и статические встроенные функции предоставляются для написания более понятного и идиоматичного кода при работе с PyArray_DTypeMeta экземпляров.

NPY_DTYPE(descr)#: Возвращает PyArray_DTypeMeta * указатель на DType данного экземпляра дескриптора.

статический встроенный PyArray_DTypeMeta *NPY_DT_NewRef(PyArray_DTypeMeta *o)#: Возвращает PyArray_DTypeMeta * указатель на новую ссылку на DType.

Утилиты преобразования#

Для использования с `PyArg_ParseTuple`#

Все эти функции могут использоваться в PyArg_ParseTuple (…) с описателем формата "O&" для автоматического преобразования любого объекта Python в требуемый C-объект. Все эти функции возвращают NPY_SUCCEED если успешно и NPY_FAIL если нет. Первый аргумент всех этих функций — это объект Python. Второй аргумент — это адрес C-типа для преобразования объекта Python.

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

Обязательно поймите, какие шаги следует предпринять для управления памятью при использовании этих функций преобразования. Эти функции могут требовать освобождения памяти и/или изменения счётчиков ссылок определённых объектов в зависимости от вашего использования.

int PyArray_Converter(PyObject *obj, PyObject **адрес)#: Преобразовать любой объект Python в PyArrayObject. Если PyArray_Check (obj) имеет значение TRUE, то его счётчик ссылок увеличивается, и ссылка помещается в адрес. Если obj не является массивом, затем преобразуйте его в массив с помощью PyArray_FromAny . Независимо от того, что возвращается, вы должны DECREF объект, возвращенный этой процедурой в адрес когда вы закончили с ним.

int PyArray_OutputConverter(PyObject *obj, PyArrayObject **адрес)#: Это конвертер по умолчанию для выходных массивов, передаваемых функциям. Если obj является Py_None или NULL, затем *address будет NULL но вызов будет успешным. Если PyArray_Check ( obj) имеет значение TRUE, тогда он возвращается в *address без увеличения его счетчика ссылок.

int PyArray_IntpConverter(PyObject *obj, PyArray_Dims *seq)#: Преобразовать любую последовательность Python, obj, меньше, чем NPY_MAXDIMS в C-массив npy_intp. Объект Python также может быть одним числом. seq переменная является указателем на структуру с членами ptr и len. При успешном возврате, seq ->ptr содержит указатель на память, которую необходимо освободить, вызвав PyDimMem_FREE, чтобы избежать утечки памяти. Ограничение на размер памяти позволяет удобно использовать этот конвертер для последовательностей, предназначенных для интерпретации как формы массивов.

int PyArray_BufferConverter(PyObject *obj, PyArray_Chunk *buf)#: Преобразовать любой объект Python, obj, с (односегментным) интерфейсом буфера к переменной с членами, которые детализируют использование объектом его фрагмента памяти. buf переменная является указателем на структуру с членами base, ptr, len и flags. Переменная PyArray_Chunk структура бинарно совместима с буферным объектом Python (через его член len на 32-битных платформах и его член ptr на 64-битных платформах). При возврате член base устанавливается в obj (или его основы, если obj уже является объектом буфера, указывающим на другой объект). Если вам нужно удерживать память, обязательно INCREF базовый член. Блок памяти указывается на buf ->ptr member и имеет длину buf ->len. Флаг член buf является NPY_ARRAY_ALIGNED с NPY_ARRAY_WRITEABLE флаг установлен, если obj имеет доступный для записи буферный интерфейс.

int PyArray_AxisConverter(PyObject *obj, int *ось)#: Преобразовать объект Python, obj, представляющий аргумент оси в правильное значение для передачи функциям, принимающим целочисленную ось. В частности, если obj равно None, ось установлено в NPY_RAVEL_AXIS который корректно интерпретируется функциями C-API, принимающими аргументы оси.

int PyArray_BoolConverter(PyObject *obj, npy_bool *значение)#: Преобразовать любой объект Python, obj, в NPY_TRUE или NPY_FALSEи поместить результат в значение.

int PyArray_ByteorderConverter(PyObject *obj, char *endian)#: Преобразуйте строки Python в соответствующий символ порядка байтов: ‘>’, ‘<’, ‘s’, ‘=’ или ‘|’.

int PyArray_SortkindConverter(PyObject *obj, NPY_SORTKIND *sort)#: Преобразование строк Python в один из NPY_QUICKSORT (начинается с 'q' или 'Q'), NPY_HEAPSORT (начинается с 'h' или 'H'), NPY_MERGESORT (начинается с 'm' или 'M') или NPY_STABLESORT (начинается с 't' или 'T'). NPY_MERGESORT и NPY_STABLESORT являются псевдонимами друг друга для обратной совместимости и могут ссылаться на один из нескольких стабильных алгоритмов сортировки в зависимости от типа данных.

int PyArray_SearchsideConverter(PyObject *obj, NPY_SEARCHSIDE *сторона)#: Преобразование строк Python в один из NPY_SEARCHLEFT (начинается с 'l' или 'L'), или NPY_SEARCHRIGHT (начинается с 'r' или 'R').

int PyArray_OrderConverter(PyObject *obj, NPY_ORDER *порядок)#: Преобразует строки Python 'C', 'F', 'A' и 'K' в NPY_ORDER перечисление NPY_CORDER, NPY_FORTRANORDER, NPY_ANYORDER, и NPY_KEEPORDER.

int PyArray_CastingConverter(PyObject *obj, NPY_CASTING *приведение типов)#: Преобразуйте строки Python 'no', 'equiv', 'safe', 'same_kind' и 'unsafe' в NPY_CASTING перечисление NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, и NPY_UNSAFE_CASTING.

int PyArray_ClipmodeConverter(PyObject *object, NPY_CLIPMODE *val)#: Преобразует строки Python 'clip', 'wrap' и 'raise' в NPY_CLIPMODE перечисление NPY_CLIP, NPY_WRAP, и NPY_RAISE.

int PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE *режимы, int n)#: Преобразует либо последовательность clipmodes, либо одиночный clipmode в массив C из NPY_CLIPMODE значения. Количество режимов обрезки n должны быть известны до вызова этой функции. Эта функция предоставлена для помощи функциям, позволяющим использовать разный clipmode для каждого измерения.

Другие преобразования#

int PyArray_PyIntAsInt(PyObject *op)#

Преобразует все виды объектов Python (включая массивы и скаляры массивов) в стандартное целое число. При ошибке возвращается -1 и устанавливается исключение. Вам может быть полезен макрос:

#define error_converting(x) (((x) == -1) && PyErr_Occurred())

npy_intp PyArray_PyIntAsIntp(PyObject *op)#: Преобразует все виды объектов Python (включая массивы и скаляры массивов) в целое число (размером с указатель платформы). При ошибке возвращается -1 и устанавливается исключение.

int PyArray_IntpFromSequence(PyObject *seq, npy_intp *vals, int maxvals)#: Преобразовать любую последовательность Python (или одиночное число Python), переданную как seq до (включительно) maxvals целочисленные значения размером с указатель и помещает их в vals массив. Последовательность может быть меньше, чем maxvals так как возвращается количество преобразованных объектов.

Включение и импорт C API#

Для использования NumPy C-API обычно необходимо включить numpy/ndarrayobject.h заголовок и numpy/ufuncobject.h для некоторой функциональности, связанной с ufunc (arrayobject.h является псевдонимом для ndarrayobject.h).

Эти два заголовка экспортируют наиболее релевантную функциональность. В общем случае любой проект, использующий API NumPy, должен импортировать NumPy с помощью одной из функций PyArray_ImportNumPyAPI() или import_array(). В некоторых местах функциональность, требующая import_array() не нужен, потому что вам нужны только определения типов. В этом случае достаточно включить numpy/ndarratypes.h.

Для типичного проекта Python несколько файлов на C или C++ будут скомпилированы в один общий объект (Python C-модуль) и PyArray_ImportNumPyAPI() должен вызываться внутри инициализации своего модуля.

Когда у вас есть один C-файл, он будет состоять из:

#include "numpy/ndarrayobject.h"

PyMODINIT_FUNC PyInit_my_module(void)
{
    if (PyArray_ImportNumPyAPI() < 0) {
        return NULL;
    }
    /* Other initialization code. */
}

Однако, большинство проектов будут иметь дополнительные C-файлы, которые все связываются вместе в один модуль Python. В этом случае вспомогательные C-файлы обычно не имеют канонического места, где PyArray_ImportNumPyAPI должен вызываться (хотя это нормально и быстро вызывать его часто).

Чтобы решить это, NumPy предоставляет следующий шаблон, в котором основной файл модифицируется для определения PY_ARRAY_UNIQUE_SYMBOL перед include:

/* Main module file */
#define PY_ARRAY_UNIQUE_SYMBOL MyModule
#include "numpy/ndarrayobject.h"

PyMODINIT_FUNC PyInit_my_module(void)
{
    if (PyArray_ImportNumPyAPI() < 0) {
        return NULL;
    }
    /* Other initialization code. */
}

в то время как другие файлы используют:

/* Second file without any import */
#define NO_IMPORT_ARRAY
#define PY_ARRAY_UNIQUE_SYMBOL MyModule
#include "numpy/ndarrayobject.h"

Вы, конечно, можете добавить определения в локальный заголовочный файл, используемый повсюду. Просто убедитесь, что основной файл _не_ определяет NO_IMPORT_ARRAY.

Для numpy/ufuncobject.h та же логика применяется, но механизм уникального символа #define PY_UFUNC_UNIQUE_SYMBOL (оба могут совпадать).

Кроме того, вы, вероятно, захотите добавить #define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION чтобы избежать предупреждений о возможном использовании старого API.

Примечание

Если вы сталкиваетесь с нарушениями доступа, убедитесь, что API NumPy был правильно импортирован и символ PyArray_API не является NULL. При работе в отладчике фактическое имя этого символа будет PY_ARRAY_UNIQUE_SYMBOL``+``PyArray_API, так, например, MyModulePyArray_API в вышеуказанном. (Например, даже printf("%p\n", PyArray_API); непосредственно перед сбоем.)

Детали механизма и динамическая компоновка#

Основная часть механизма заключается в том, что без NumPy необходимо определить void **PyArray_API таблица для поиска всех функций. В зависимости от настройки макросов, это проходит разными путями в зависимости от того, NO_IMPORT_ARRAY и PY_ARRAY_UNIQUE_SYMBOL определены:

функция использует BLAS, когда это возможно static void **PyArray_API, поэтому он виден только в пределах единицы компиляции/файла, использующего #include .
Если только PY_ARRAY_UNIQUE_SYMBOL определен (он может быть пустым), то он объявляется как нестатический void ** позволяя использовать его другими файлами, которые связаны.
Если NO_IMPORT_ARRAY определен, таблица объявляется как extern void **, что означает, что он должен быть связан с файлом, который не использует NO_IMPORT_ARRAY.

The PY_ARRAY_UNIQUE_SYMBOL Механизм дополнительно изменяет имена, чтобы избежать конфликтов.

Изменено в версии NumPy: 2.1 изменил заголовки, чтобы избежать совместного использования таблицы вне одного общего объекта/dll (это всегда было так в Windows). Пожалуйста, смотрите NPY_API_SYMBOL_ATTRIBUTE подробности.

Для использования C-API из другого модуля расширения, import_array функция должна быть вызвана. Если модуль расширения самодостаточен в одном файле .c, то это всё, что нужно сделать. Однако, если модуль расширения включает несколько файлов, где требуется C-API, то необходимо выполнить дополнительные шаги.

int PyArray_ImportNumPyAPI(void)#: Гарантирует, что C-API NumPy импортирован и пригоден к использованию. Возвращает 0 при успехе и -1 с установленной ошибкой, если NumPy не удалось импортировать. Хотя предпочтительно вызывать его один раз при инициализации модуля, эта функция очень легковесна при многократном вызове.

Новое в версии 2.0: Эта функция обратно перенесена в npy_2_compat.h заголовок.

import_array(void)#: Эта функция должна вызываться в секции инициализации модуля, который будет использовать C-API. Она импортирует модуль, где хранится таблица указателей на функции, и направляет правильную переменную на неё. Этот макрос включает return NULL; при ошибке, так что PyArray_ImportNumPyAPI() предпочтительнее для пользовательской проверки ошибок. Вы также можете увидеть использование _import_array() (функция, а не макрос, но вы можете захотеть вызвать лучшую ошибку, если она не сработает) и вариации import_array1(ret) который настраивает возвращаемое значение.

PY_ARRAY_UNIQUE_SYMBOL#

NPY_API_SYMBOL_ATTRIBUTE#

Новое в версии 2.1.

Дополнительный символ, который можно использовать для совместного использования, например, видимости за пределами границ общего объекта. По умолчанию NumPy добавляет атрибут скрытой видимости C (если доступен): void __attribute__((visibility("hidden"))) **PyArray_API;. Вы можете изменить это, определив NPY_API_SYMBOL_ATTRIBUTE, что приведёт к: void NPY_API_SYMBOL_ATTRIBUTE **PyArray_API; (с дополнительным изменением имен через уникальный символ).

Добавление пустого #define NPY_API_SYMBOL_ATTRIBUTE будет иметь то же поведение, что и NumPy 1.x.

Примечание

Windows никогда не имел общей видимости, хотя вы можете использовать этот макрос для её достижения. Мы обычно не рекомендуем совместное использование за пределами общих границ, поскольку импорт API массивов включает проверки версий NumPy.

NO_IMPORT_ARRAY#

Определение NO_IMPORT_ARRAY перед ndarrayobject.h include указывает, что импорт NumPy C API обрабатывается в другом файле, и механизм include не будет добавлен здесь. У вас должен быть один файл без NO_IMPORT_ARRAY определено.

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include 

С другой стороны, coolhelper.c будет содержать в начале:

#define NO_IMPORT_ARRAY
#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include 

Вы также можете поместить общие две последние строки в локальный заголовочный файл расширения, если убедитесь, что NO_IMPORT_ARRAY определен перед включением этого файла.

Внутри эти #defines работают следующим образом:

Если ни один из них не определён, C-API объявляется как static void**, поэтому он виден только в пределах единицы компиляции, которая #includes numpy/arrayobject.h.
Если PY_ARRAY_UNIQUE_SYMBOL определено через #define, но NO_IMPORT_ARRAY не является, C-API объявлен как void**, чтобы он также был виден другим единицам компиляции.
Если NO_IMPORT_ARRAY определено с помощью #define, независимо от того, PY_ARRAY_UNIQUE_SYMBOL то есть C-API объявлен как extern void**, поэтому ожидается, что он будет определен в другой единице компиляции.
Всякий раз, когда PY_ARRAY_UNIQUE_SYMBOL если #определено, это также изменяет имя переменной, содержащей C-API, которая по умолчанию равна PyArray_API, к тому, чем определен макрос.

Проверка версии API#

Поскольку расширения Python используются не так, как обычные библиотеки на большинстве платформ, некоторые ошибки не могут быть автоматически обнаружены во время сборки или даже выполнения. Например, если вы создаёте расширение, используя функцию, доступную только для numpy >= 1.3.0, и затем импортируете это расширение с numpy 1.2, вы не получите ошибку импорта (но почти наверняка столкнётесь с ошибкой сегментации при вызове функции). Поэтому предоставляется несколько функций для проверки версий numpy. Макросы NPY_VERSION и NPY_FEATURE_VERSION соответствует версии numpy, использованной для сборки расширения, тогда как версии, возвращаемые функциями PyArray_GetNDArrayCVersion и PyArray_GetNDArrayCFeatureVersion соответствует версии numpy во время выполнения.

Правила совместимости ABI и API можно резюмировать следующим образом:

Всякий раз, когда NPY_VERSION != PyArray_GetNDArrayCVersion()расширение должно быть перекомпилировано (несовместимость ABI).
NPY_VERSION == PyArray_GetNDArrayCVersion() и NPY_FEATURE_VERSION <= PyArray_GetNDArrayCFeatureVersion() означает обратно совместимые изменения.

Несовместимость ABI автоматически обнаруживается в каждой версии numpy. Обнаружение несовместимости API было добавлено в numpy 1.4.0. Если вы хотите поддерживать много разных версий numpy с одним двоичным файлом расширения, вы должны собрать свое расширение с самой низкой NPY_FEATURE_VERSION насколько возможно.

NPY_VERSION#: Текущая версия объекта ndarray (проверьте, определена ли эта переменная, чтобы гарантировать numpy/arrayobject.h заголовок используется).

NPY_FEATURE_VERSION#: Текущая версия C-API.

беззнаковый int PyArray_GetNDArrayCVersion(void)#: Это просто возвращает значение NPY_VERSION. NPY_VERSION изменяется при несовместимых изменениях на уровне ABI. Поскольку он находится в C-API, однако, сравнение вывода этой функции со значением, определенным в текущем заголовке, дает способ проверить, изменился ли C-API, требуя перекомпиляции модулей расширений, которые используют C-API. Это автоматически проверяется в функции import_array.

беззнаковый int PyArray_GetNDArrayCFeatureVersion(void)#: Это просто возвращает значение NPY_FEATURE_VERSION. NPY_FEATURE_VERSION изменяется при каждом изменении API (например, при добавлении функции). Изменённое значение не всегда требует перекомпиляции.

Управление памятью#

char *PyDataMem_NEW(size_t nbytes)#

void PyDataMem_FREE(char *ptr)#

char *PyDataMem_RENEW(void *ptr, size_t newbytes)#: Функции для выделения, освобождения и перераспределения памяти. Они используются внутри для управления памятью данных массива, если не переопределены.

npy_intp *PyDimMem_NEW(int nd)#

void PyDimMem_FREE(char *ptr)#

npy_intp *PyDimMem_RENEW(void *ptr, size_t newnd)#: Макросы для выделения, освобождения и перераспределения памяти для размерностей и шагов.

void *PyArray_malloc(size_t nbytes)#

void PyArray_free(void *ptr)#

void *PyArray_realloc(npy_intp *ptr, size_t nbytes)#

Эти макросы используют различные распределители памяти в зависимости от константы NPY_USE_PYMEM. Системный malloc используется, когда NPY_USE_PYMEM равно 0, если NPY_USE_PYMEM равно 1, тогда используется аллокатор памяти Python.

NPY_USE_PYMEM#

int PyArray_ResolveWritebackIfCopy(PyArrayObject *obj)#

Если obj->flags имеет NPY_ARRAY_WRITEBACKIFCOPY, эта функция очищает флаги, DECREF s obj->base и делает его доступным для записи, и устанавливает obj->base в NULL. Затем копирует obj->data to obj->base->data, и возвращает состояние ошибки операции копирования. Это противоположно PyArray_SetWritebackIfCopyBase. Обычно это вызывается один раз, когда вы закончили работу с obj, непосредственно перед Py_DECREF(obj). Она может вызываться несколько раз или с NULL входные данные. См. также PyArray_DiscardWritebackIfCopy.

Возвращает 0, если ничего не было сделано, -1 при ошибке и 1, если действие было выполнено.

Поддержка многопоточности#

Эти макросы имеют смысл только если NPY_ALLOW_THREADS возвращает True во время компиляции модуля расширения. В противном случае эти макросы эквивалентны пробелам. Python использует единую глобальную блокировку интерпретатора (GIL) для каждого процесса Python, так что только один поток может выполняться одновременно (даже на машинах с несколькими процессорами). При вызове скомпилированной функции, вычисление которой может занять время (и которая не имеет побочных эффектов для других потоков, таких как обновление глобальных переменных), GIL следует освободить, чтобы другие потоки Python могли выполняться во время проведения трудоемких вычислений. Это можно сделать с помощью двух групп макросов. Как правило, если один макрос из группы используется в блоке кода, все они должны использоваться в том же блоке кода. NPY_ALLOW_THREADS истинно (определяется как 1) если не указана опция сборки -Ddisable-threading установлено в true - в этом случае NPY_ALLOW_THREADS ложно (0).

NPY_ALLOW_THREADS#

Группа 1#

Эта группа используется для вызова кода, который может занять некоторое время, но не использует никаких вызовов Python C-API. Таким образом, GIL должен быть освобожден во время его вычисления.

NPY_BEGIN_ALLOW_THREADS#: Эквивалентно Py_BEGIN_ALLOW_THREADS за исключением того, что использует NPY_ALLOW_THREADS чтобы определить, заменяется ли макрос пробелами или нет.

NPY_END_ALLOW_THREADS#: Эквивалентно Py_END_ALLOW_THREADS за исключением того, что использует NPY_ALLOW_THREADS чтобы определить, заменяется ли макрос пробелами или нет.

NPY_BEGIN_THREADS_DEF#: Разместить в области объявления переменных. Этот макрос настраивает переменную, необходимую для хранения состояния Python.

NPY_BEGIN_THREADS#: Разместить непосредственно перед кодом, который не требует интерпретатора Python (без вызовов Python C-API). Этот макрос сохраняет состояние Python и освобождает GIL.

NPY_END_THREADS#: Разместите сразу после кода, который не требует интерпретатора Python. Этот макрос захватывает GIL и восстанавливает состояние Python из сохранённой переменной.

void NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype)#: Полезно для освобождения GIL только если dtype не содержит произвольных объектов Python, которые могут потребовать интерпретатор Python во время выполнения цикла.

void NPY_END_THREADS_DESCR(PyArray_Descr *dtype)#: Полезно для восстановления GIL в ситуациях, когда он был освобождён с использованием формы BEGIN этого макроса.

void NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)#: Полезно для освобождения GIL только если loop_size превышает минимальный порог, в настоящее время установленный на 500. Должен соответствовать с NPY_END_THREADS чтобы вернуть GIL.

Группа 2#

Эта группа используется для повторного получения GIL Python после его освобождения. Например, предположим, что GIL был освобожден (с использованием предыдущих вызовов), а затем некоторый путь в коде (возможно, в другой подпрограмме) требует использования Python C-API, тогда эти макросы полезны для получения GIL. Эти макросы выполняют по сути обратное действие предыдущим трем (получают LOCK, сохраняя его состояние), а затем снова освобождают его с сохраненным состоянием.

NPY_ALLOW_C_API_DEF#: Разместить в области объявления переменных для настройки необходимой переменной.

NPY_ALLOW_C_API#: Размещать перед кодом, который должен вызывать Python C-API (когда известно, что GIL уже освобождён).

NPY_DISABLE_C_API#: Разместить после кода, который должен вызывать Python C-API (для повторного освобождения GIL).

Совет

Никогда не используйте точки с запятой после макросов поддержки потоков.

Приоритет#

NPY_PRIORITY#: Приоритет по умолчанию для массивов.

NPY_SUBTYPE_PRIORITY#: Приоритет подтипа по умолчанию.

NPY_SCALAR_PRIORITY#: Приоритет скаляра по умолчанию (очень маленький)

double PyArray_GetPriority(PyObject *obj, double def)#: Возвращает __array_priority__ атрибут (преобразованный в double) из obj или def если атрибут с таким именем не существует. Быстрые возвраты, избегающие поиска атрибута, предоставляются для объектов типа PyArray_Type.

Буферы по умолчанию#

NPY_BUFSIZE#: Размер по умолчанию для настраиваемых пользователем внутренних буферов.

NPY_MIN_BUFSIZE#: Минимальный размер пользовательских внутренних буферов.

NPY_MAX_BUFSIZE#: Максимальный размер, разрешённый для пользовательских буферов.

Другие константы#

NPY_NUM_FLOATTYPE#: Количество типов с плавающей запятой

NPY_MAXDIMS#: Максимальное количество измерений, которое может использовать NumPy. Установлено на 64 и было 32 до NumPy 2.

Примечание

Мы рекомендуем избегать NPY_MAXDIMS. Будущая версия NumPy может пожелать удалить любые ограничения размерности (и, следовательно, константу). Ограничение было создано, чтобы NumPy мог использовать стековые аллокации внутри для рабочего пространства.

Если ваш алгоритм имеет разумное максимальное количество измерений, вы можете проверить и использовать его локально.

NPY_MAXARGS#: Максимальное количество аргументов-массивов, которое можно использовать в некоторых функциях. До NumPy 2 это было 32, а теперь 64. Чтобы продолжить использовать это как проверку совместимости количества аргументов с универсальными функциями, этот макрос теперь зависит от времени выполнения.

Примечание

Мы не рекомендуем любое использование NPY_MAXARGS который не привязан явно к проверке известных ограничений NumPy.

NPY_FALSE#: Определено как 0 для использования с Bool.

NPY_TRUE#: Определено как 1 для использования с Bool.

NPY_FAIL#: Возвращаемое значение неудачных функций преобразователя, которые вызываются с использованием синтаксиса "O&" в PyArg_ParseTuple-подобные функции.

NPY_SUCCEED#: Возвращаемое значение успешных функций-конвертеров, которые вызываются с использованием синтаксиса "O&" в PyArg_ParseTuple-подобные функции.

NPY_RAVEL_AXIS#: Некоторые функции NumPy (в основном C-точки входа для функций Python) имеют axis аргумент. Этот макрос может быть передан для axis=None.

Примечание

Этот макрос зависит от версии NumPy во время выполнения. Значение теперь является минимальным целым числом. Однако в NumPy 1.x NPY_MAXDIMS был использован (в то время установлен на 32).

Различные макросы#

int PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)#: Вычисляется как True, если массивы a1 и a2 имеют одинаковую форму.

PyArray_MAX(a, b)#: Возвращает максимум a и b. Если (a) или (b) являются выражениями, они вычисляются дважды.

PyArray_MIN(a, b)#: Возвращает минимум a и b. Если (a) или (b) являются выражениями, они вычисляются дважды.

void PyArray_DiscardWritebackIfCopy(PyArrayObject *obj)#: Если obj->flags имеет NPY_ARRAY_WRITEBACKIFCOPY, эта функция очищает флаги, DECREF s obj->base и делает его доступным для записи, и устанавливает obj->base в NULL. В отличие от PyArray_ResolveWritebackIfCopy не предпринимается попыток скопировать данные из obj->base. Это отменяет PyArray_SetWritebackIfCopyBase. Обычно это вызывается после ошибки, когда вы закончили работу с obj, непосредственно перед Py_DECREF(obj). Он может вызываться несколько раз или с NULL ввод.

Перечисленные типы#

перечисление NPY_SORTKIND#

Специальный тип переменной, который может принимать различные значения для указания используемого алгоритма сортировки. Эти типы алгоритмов не обрабатывались строго в течение некоторого времени, а скорее рассматривались как стабильные/нестабильные. В NumPy 2.4 они заменены требованиями (см. ниже), но сделано это обратно совместимым образом. Эти значения продолжат работать, за исключением того, что NPY_HEAPSORT будет делать то же самое, что и NPY_QUICKSORT.

перечислитель NPY_QUICKSORT#

перечислитель NPY_HEAPSORT#

перечислитель NPY_MERGESORT#

перечислитель NPY_STABLESORT#: Используется как псевдоним для NPY_MERGESORT и наоборот.

перечислитель NPY_NSORTS#: Определено как количество видов. Оно фиксировано на трёх из-за необходимости обратной совместимости, и, как следствие, NPY_MERGESORT и NPY_STABLESORT являются псевдонимами друг друга и могут ссылаться на один из нескольких стабильных алгоритмов сортировки в зависимости от типа данных.

В NumPy 2.4 названия алгоритмов заменены требованиями. Вы всё ещё можете использовать старые значения, перекомпиляция не требуется, но они переинтерпретируются так, что

NPY_QUICKSORT и NPY_HEAPSORT -> NPY_SORT_DEFAULT
NPY_MERGESORT и NPY_STABLE -> NPY_SORT_STABLE

перечислитель NPY_SORT_DEFAULT#: Стандартная сортировка для типа. Для встроенных типов NumPy она может быть стабильной или нет, но будет возрастающей и помещать типы NaN в конец. Обычно выбирается для скорости и/или низкого потребления памяти.

перечислитель NPY_SORT_STABLE#: (Требование) Указывает, что сортировка должна быть стабильной.

перечислитель NPY_SORT_DESCENDING#: (Требование) Указывает, что сортировка должна быть в порядке убывания. Эта функциональность ещё не реализована для типов NumPy и пока не может быть установлена из интерфейса Python.

перечисление NPY_SCALARKIND#

Специальный тип переменной, указывающий количество «видов» скаляров, различаемых при определении правил приведения скаляров. Эта переменная может принимать значения:

перечислитель NPY_NOSCALAR#

перечислитель NPY_BOOL_SCALAR#

перечислитель NPY_INTPOS_SCALAR#

перечислитель NPY_INTNEG_SCALAR#

перечислитель NPY_FLOAT_SCALAR#

перечислитель NPY_COMPLEX_SCALAR#

перечислитель NPY_OBJECT_SCALAR#

перечислитель NPY_NSCALARKINDS#: Определяется как количество скалярных видов (не включая NPY_NOSCALAR).

перечисление NPY_ORDER#

Тип перечисления, указывающий порядок элементов, в котором должен интерпретироваться массив. Когда создаётся совершенно новый массив, обычно только NPY_CORDER и NPY_FORTRANORDER используются, тогда как при предоставлении одного или нескольких входных данных порядок может быть основан на них.

перечислитель NPY_ANYORDER#: Порядок Fortran, если все входные данные в формате Fortran, в противном случае C.

перечислитель NPY_CORDER#: Порядок C.

перечислитель NPY_FORTRANORDER#: Порядок Fortran.

перечислитель NPY_KEEPORDER#: Порядок, максимально близкий к порядку входных данных, даже если входные данные не в порядке C или Fortran.

перечисление NPY_CLIPMODE#

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

перечислитель NPY_RAISE#: По умолчанию для большинства операций вызывает исключение, если индекс выходит за границы.

перечислитель NPY_CLIP#: Обрезает индекс до допустимого диапазона, если он выходит за границы.

перечислитель NPY_WRAP#: Обёртывает индекс в допустимый диапазон, если он выходит за границы.

перечисление NPY_SEARCHSIDE#

Переменный тип, указывающий, должен ли возвращаемый индекс быть индексом первого подходящего местоположения (если NPY_SEARCHLEFT) или последнего (если NPY_SEARCHRIGHT).

перечислитель NPY_SEARCHLEFT#

перечислитель NPY_SEARCHRIGHT#

перечисление NPY_SELECTKIND#

Переменный тип, указывающий на используемый алгоритм выбора.

перечислитель NPY_INTROSELECT#

перечисление NPY_CASTING#

Тип перечисления, указывающий, насколько разрешительными должны быть преобразования данных. Используется итератором, добавленным в NumPy 1.6, и предназначен для более широкого использования в будущей версии.

перечислитель NPY_NO_CASTING#: Разрешать только идентичные типы.

перечислитель NPY_EQUIV_CASTING#: Разрешить идентичные и преобразования с перестановкой байтов.

перечислитель NPY_SAFE_CASTING#: Разрешать только преобразования, которые не приведут к округлению, усечению или иному изменению значений.

перечислитель NPY_SAME_KIND_CASTING#: Разрешить любые безопасные приведения и приведения между типами одного вида. Например, float64 -> float32 разрешено этим правилом.

перечислитель NPY_UNSAFE_CASTING#: Разрешить любое приведение, независимо от того, какая потеря данных может произойти.

NPY_SAME_VALUE_CASTING#: Ошибка, если любые значения изменяются во время приведения. В настоящее время поддерживается только в ndarray.astype(... casting='same_value')

Новое в версии 2.4.

Array API#

Структура массива и доступ к данным#

Доступ к данным#

Создание массивов#

С нуля#

Из других объектов#

Работа с типами#

Общая проверка типа Python#

Аксессоры типа данных#

Проверка типа данных#

Преобразование типов данных#

Пользовательские типы данных#

Специальные функции для NPY_OBJECT#

Флаги массива#

Базовые флаги массива#

Комбинации флагов массива#

Константы, подобные флагам#

Проверка флагов#

ArrayMethod API#

Слоты и определения типов#

Флаги#

Определения типов#

API-функции и определения типов#

Пример обёртки цикла#

Сортировка и аргсортировка#

API для вызова методов массива#

Преобразование#

Манипуляция формой#

Выбор и манипуляция элементами#

Вычисление#

Функции#

Функции массивов#

Другие функции#

Вспомогательные данные с объектной семантикой#

Итераторы массивов#

Трансляция (множественные итераторы)#

Итератор окрестности#

Скаляры массива#

Дескрипторы типов данных#

Продвижение и проверка типов данных#

Пользовательские типы данных#

Флаги#

Идентификаторы слотов и определения типов функций API#

Слоты PyArray_ArrFuncs#

Макросы и статические встроенные функции#

Утилиты преобразования#

Для использования с PyArg_ParseTuple#

Другие преобразования#

Включение и импорт C API#

Детали механизма и динамическая компоновка#

Проверка версии API#

Управление памятью#

Поддержка многопоточности#

Группа 1#

Группа 2#

Приоритет#

Буферы по умолчанию#

Другие константы#

Различные макросы#

Перечисленные типы#

Для использования с `PyArg_ParseTuple`#