超越基础

基本迭代¶

一种常见的算法要求是能够遍历多维数组中的所有元素。数组迭代器对象使它易于以适用于任何维数数组的通用方式来完成。自然地，如果您知道将要使用的维数，则始终可以编写嵌套的for循环来完成迭代。但是，如果您想编写适用于任何尺寸的代码，则可以使用数组迭代器。访问数组的.flat属性时，将返回数组迭代器对象。

基本用法是调用PyArray_IterNew（array），其中array是ndarray对象（或其子类之一）。返回的对象是一个数组迭代器对象（由ndarray的.flat属性返回的对象相同）。通常将此对象强制转换为PyArrayIterObject *，以便可以访问其成员。唯一需要的成员是iter->size包含数组的总大小iter->index，包含数组的当前1-d索引以及iter->dataptr指向数组当前元素的数据的指针。有时，访问iter->ao指向基础ndarray对象的指针也很有用。

在数组的当前元素处处理完数据后，可以使用宏PyArray_ITER_NEXT（iter）获得数组的下一个元素 。迭代始终以C样式的连续方式进行（最后一个索引变化最快）。的 PyArray_ITER_GOTO（iter，destination）可以用来跳到一个特定点的阵列，其中在destination是npy_intp数据类型与空间的阵列来处理底层数组中维度中的至少数。有时使用PyArray_ITER_GOTO1D（iter，index）很有用，它将跳到由的值给定的1-d索引index。但是，以下示例给出了最常见的用法。

PyObject *obj; /* assumed to be some ndarray object */
PyArrayIterObject *iter;
...
iter = (PyArrayIterObject *)PyArray_IterNew(obj);
if (iter == NULL) goto fail;   /* Assume fail has clean-up code */
while (iter->index < iter->size) {
    /* do something with the data at it->dataptr */
    PyArray_ITER_NEXT(it);
}
...

您也可以使用PyArrayIter_Check（obj），以确保你有一个迭代器对象和PyArray_ITER_RESET（iter）重置一个iterator对象返回数组的开头。

在这一点上应该强调的是，如果您的数组已经是连续的，则可能不需要数组迭代器（使用数组迭代器可以，但是比您可以编写的最快的代码要慢）。数组迭代器的主要目的是用任意步长封装N维数组上的迭代。在NumPy源代码本身的许多很多地方都使用了它们。如果您已经知道数组是连续的（Fortran或C），则只需将element-size添加到正在运行的指针变量中，将非常有效地引导您遍历数组。换句话说，在连续情况下（假设为双精度），这样的代码对于您来说可能会更快。

npy_intp size;
double *dptr;  /* could make this any variable type */
size = PyArray_SIZE(obj);
dptr = PyArray_DATA(obj);
while(size--) {
   /* do something with the data at dptr */
   dptr++;
}

遍历除一个轴以外的所有轴¶

一种常见的算法是遍历数组的所有元素，并通过发出函数调用对每个元素执行某些功能。由于函数调用可能很耗时，因此加快这种算法的一种方法是编写函数，使其获取数据向量，然后编写迭代，以便一次对整个数据维度执行函数调用。这增加了每个函数调用完成的工作量，从而将函数调用的开销减少到总时间的一小部分。即使在不调用函数的情况下执行循环的内部操作，也可能有利于在元素数量最多的维度上执行内部循环，以利用使用流水线技术来增强基本操作的微处理器可利用的速度增强功能。

的PyArray_IterAllButAxis（array，&dim）构造被修改，使得它不会遍历尺寸表示在昏暗的迭代器对象。该迭代器对象上的唯一限制，就是PyArray_Iter_GOTO1D（it，ind）宏不能使用（如果你通过这个对象在Python这样扁平索引不会工作-所以你不应该这样做）。请注意，从该例程返回的对象通常仍转换为PyArrayIterObject *。完成的所有操作都是修改返回的迭代器的步幅和尺寸，以模拟对array […，0，…]进行迭代，其中在维度上放置了0 。如果dim为负，则找到并使用具有最大轴的尺寸。

遍历多个阵列¶

很多时候，希望同时迭代几个数组。通用函数就是这种行为的一个例子。如果您要做的只是对具有相同形状的数组进行迭代，那么标准过程就是简单地创建多个迭代器对象。例如，以下代码在假定形状和大小相同的两个数组上进行迭代（实际上obj1至少必须具有与obj2一样多的总元素）：

/* It is already assumed that obj1 and obj2
   are ndarrays of the same shape and size.
*/
iter1 = (PyArrayIterObject *)PyArray_IterNew(obj1);
if (iter1 == NULL) goto fail;
iter2 = (PyArrayIterObject *)PyArray_IterNew(obj2);
if (iter2 == NULL) goto fail;  /* assume iter1 is DECREF'd at fail */
while (iter2->index < iter2->size)  {
    /* process with iter1->dataptr and iter2->dataptr */
    PyArray_ITER_NEXT(iter1);
    PyArray_ITER_NEXT(iter2);
}

通过多个数组广播¶

当一个运算涉及多个数组时，您可能希望使用与数学运算（即 ufuncs）相同的广播规则。使用可以轻松完成此操作PyArrayMultiIterObject。这是从Python命令numpy.broadcast返回的对象，它几乎可以从C使用。使用函数 PyArray_MultiIterNew（n，...）（使用n输入对象代替...）。输入对象可以是数组或可以转换为数组的任何对象。返回指向PyArrayMultiIterObject的指针。广播已经完成，它可以调整迭代器，以便前进到每个数组中的下一个元素所需要做的就是为每个输入调用PyArray_ITER_NEXT。这种递增是由PyArray_MultiIter_NEXT（obj）宏自动执行的 （该宏可以将multiterator处理obj为a 或a ）。输入数字中的数据可以使用 （，），总（广播的）大小为（）。以下是使用此功能的示例。PyArrayMultiObject *PyObject *iPyArray_MultiIter_DATAobjiPyArray_MultiIter_SIZEobj

mobj = PyArray_MultiIterNew(2, obj1, obj2);
size = PyArray_MultiIter_SIZE(obj);
while(size--) {
    ptr1 = PyArray_MultiIter_DATA(mobj, 0);
    ptr2 = PyArray_MultiIter_DATA(mobj, 1);
    /* code using contents of ptr1 and ptr2 */
    PyArray_MultiIter_NEXT(mobj);
}

函数PyArray_RemoveSmallest（multi）可用于获取多迭代器对象并调整所有迭代器，以使迭代不会在最大维度上发生（它使该维度的大小为1）。使用指针的循环代码很可能还需要每个迭代器的步幅数据。此信息存储在multi-> iters [i]->步幅中。

在NumPy源代码中使用多重迭代器有几个示例，因为它使N维广播代码的编写非常简单。浏览源代码以获取更多示例。

添加新的数据类型¶

要开始使用新的数据类型，您需要首先定义一个新的Python类型以容纳新数据类型的标量。如果您的新类型具有二进制兼容布局，则从一个数组标量继承是可以接受的。这将使您的新数据类型具有数组标量的方法和属性。新的数据类型必须具有固定的内存大小（如果要定义需要灵活表示的数据类型（如可变精度数字，则使用指向对象的指针作为数据类型））。新的Python类型的对象结构的内存布局必须为PyObject_HEAD，后跟数据类型所需的固定大小的内存。例如，适用于新Python类型的结构为：

typedef struct {
   PyObject_HEAD;
   some_data_type obval;
   /* the name can be whatever you want */
} PySomeDataTypeObject;

定义新的Python类型对象之后，必须定义一个新PyArray_Descr结构，该结构的typeobject成员将包含一个指向刚定义的数据类型的指针。另外，必须在“ .f”成员中定义所需的函数：非零，copyswap，copyswapn，setitem，getitem和cast。您定义的“ .f”成员中的功能越多，新数据类型将越有用。将未使用的函数初始化为NULL非常重要。这可以使用PyArray_InitArrFuncs（f）来实现。

一旦PyArray_Descr创建了一个新结构，并填充了所需的信息和有用的函数 PyArray_RegisterDataType（new_descr）。此调用的返回值是一个整数，为您提供一个唯一的type_number，用于指定您的数据类型。此类型编号应由您的模块存储并可以使用，以便其他模块可以使用它识别您的数据类型（查找用户定义的数据类型编号的另一种机制是根据类型名称进行搜索，与与数据类型相关联的对象PyArray_TypeNumFromName。

注册一个铸造功能¶

您可能希望允许将内置（和其他用户定义的）数据类型自动转换为您的数据类型。为了使之成为可能，您必须使用您希望从中进行转换的数据类型注册一个转换函数。这要求为您要支持的每个转换编写低级转换函数，然后将这些函数注册到数据类型描述符中。低级转换功能具有签名。

void castfunc（ void *  from，void *  至，npy_intp  n，void *  fromarr，void *  toarr ）¶

强制转换n元素的from类型to。要投射的数据位于from指向的连续，正确交换和对齐的内存块中。要投射到的缓冲区也是连续的，正确交换和对齐的。fromarr和toarr参数仅应用于元素大小灵活的数组（字符串，unicode，void）。

Castfunc示例是：

static void
double_to_float(double *from, float* to, npy_intp n,
                void* ignore1, void* ignore2) {
    while (n--) {
          (*to++) = (double) *(from++);
    }
}

然后可以使用以下代码注册为将双精度型转换为浮点型：

doub = PyArray_DescrFromType(NPY_DOUBLE);
PyArray_RegisterCastFunc(doub, NPY_FLOAT,
     (PyArray_VectorUnaryFunc *)double_to_float);
Py_DECREF(doub);

注册强制规则¶

默认情况下，假定所有用户定义的数据类型都不能安全地强制转换为任何内置数据类型。另外，不能将内置数据类型安全地转换为用户定义的数据类型。这种情况限制了用户定义的数据类型参与ufunc使用的强制系统以及在NumPy中进行自动强制的其他时间的能力。可以通过将数据类型注册为可从特定数据类型对象安全地强制转换来进行更改。函数PyArray_RegisterCanCast（from_descr，totype_number，scalarkind）应用于指定可以将数据类型对象from_descr强制转换为类型为totype_number的数据类型。如果您不尝试更改标量强制规则，则将其NPY_NOSCALAR用于scalarkind参数。

如果要允许新数据类型也可以在标量强制规则中共享，则需要在数据类型对象的“ .f”成员中指定scalarkind函数，以返回新数据标量的类型-type应该被视为（该函数可以使用标量的值）。然后，可以注册可以从用户定义的数据类型返回的每种标量类型分别转换为的数据类型。如果您未注册标量强制处理，则所有用户定义的数据类型都将显示为NPY_NOSCALAR。

注册一个ufunc循环¶

您可能还需要为数据类型注册低级ufunc循环，以便可以将数据类型的ndarray无缝应用数学。注册具有完全相同的arg_types签名的新循环，将以无提示方式替换该数据类型的所有先前注册的循环。

在为ufunc注册1-d循环之前，必须先创建ufunc。然后，调用PyUFunc_RegisterLoopForType （…）并提供循环所需的信息。该函数的返回值是0该过程是否成功，-1如果失败则设置错误条件。

创建子类型¶

要创建子类型，必须遵循类似的过程，只是只有不同的行为才需要在类型对象结构中添加新的条目。所有其他条目都可以为NULL，并由PyType_Ready来自父类型的适当函数填充。特别是，要在C中创建子类型，请按照以下步骤操作：

1. 如果需要，创建一个新的C结构来处理您类型的每个实例。典型的C结构为：

   typedef _new_struct {
       PyArrayObject base;
       /* new things here */
   } NewArrayObject;
   

   请注意，完整的PyArrayObject用作第一个条目，以确保新类型的实例的二进制布局与PyArrayObject相同。

2. 用指向新函数的指针填充新的Python类型对象结构，这些指针将覆盖默认行为，同时保留所有应保持不变的函数（或NULL）。tp_name元素应该不同。

3. 用指向（主）父类型对象的指针填充新的类型对象结构的tp_base成员。对于多继承，还应在tp_bases成员中填充一个元组，该元组包含应用于定义继承的所有父对象的顺序。请记住，所有父类型必须具有相同的C结构，多重继承才能正常工作。

4. 调用PyType_Ready（<pointer_to_new_type>）。如果此函数返回负数，则发生故障并且类型未初始化。否则，该类型可以使用了。通常，将对新类型的引用放置在模块字典中很重要，以便可以从Python访问它。

通过阅读PEP 253（可从https://www.python.org/dev/peps/pep-0253获得），可以了解有关在C中创建子类型的更多信息。

ndarray子类型的特定功能¶

数组使用一些特殊的方法和属性，以促进子类型与基本ndarray类型的互操作。