数组迭代器 API#
数组迭代器#
数组迭代器封装了 ufuncs 中的许多关键特性，允许用户代码支持输出参数、内存布局保留以及处理错误对齐或类型数据时的缓冲等功能，而无需复杂的编码。
本页介绍了迭代器的 API。迭代器名为 NpyIter，函数名为 NpyIter_*。
有一个数组迭代入门指南，可能对使用此 C API 的用户有所帮助。在许多情况下，在编写 C 迭代代码之前，先在 Python 中创建迭代器来测试想法是个好主意。
迭代示例#
熟悉迭代器的最佳方法是查看它在 NumPy 代码库中的用法。例如，这里是 PyArray_CountNonzero 的稍作调整的版本，该函数用于计算数组中非零元素的数量。
npy_intp PyArray_CountNonzero(PyArrayObject* self)
{
/* Nonzero boolean function */
PyArray_NonzeroFunc* nonzero = PyArray_DESCR(self)->f->nonzero;
NpyIter* iter;
NpyIter_IterNextFunc *iternext;
char** dataptr;
npy_intp nonzero_count;
npy_intp* strideptr,* innersizeptr;
/* Handle zero-sized arrays specially */
if (PyArray_SIZE(self) == 0) {
return 0;
}
/*
* Create and use an iterator to count the nonzeros.
* flag NPY_ITER_READONLY
* - The array is never written to.
* flag NPY_ITER_EXTERNAL_LOOP
* - Inner loop is done outside the iterator for efficiency.
* flag NPY_ITER_NPY_ITER_REFS_OK
* - Reference types are acceptable.
* order NPY_KEEPORDER
* - Visit elements in memory order, regardless of strides.
* This is good for performance when the specific order
* elements are visited is unimportant.
* casting NPY_NO_CASTING
* - No casting is required for this operation.
*/
iter = NpyIter_New(self, NPY_ITER_READONLY|
NPY_ITER_EXTERNAL_LOOP|
NPY_ITER_REFS_OK,
NPY_KEEPORDER, NPY_NO_CASTING,
NULL);
if (iter == NULL) {
return -1;
}
/*
* The iternext function gets stored in a local variable
* so it can be called repeatedly in an efficient manner.
*/
iternext = NpyIter_GetIterNext(iter, NULL);
if (iternext == NULL) {
NpyIter_Deallocate(iter);
return -1;
}
/* The location of the data pointer which the iterator may update */
dataptr = NpyIter_GetDataPtrArray(iter);
/* The location of the stride which the iterator may update */
strideptr = NpyIter_GetInnerStrideArray(iter);
/* The location of the inner loop size which the iterator may update */
innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);
nonzero_count = 0;
do {
/* Get the inner loop data/stride/count values */
char* data = *dataptr;
npy_intp stride = *strideptr;
npy_intp count = *innersizeptr;
/* This is a typical inner loop for NPY_ITER_EXTERNAL_LOOP */
while (count--) {
if (nonzero(data, self)) {
++nonzero_count;
}
data += stride;
}
/* Increment the iterator to the next inner loop */
} while(iternext(iter));
NpyIter_Deallocate(iter);
return nonzero_count;
}
多迭代示例#
这里是一个使用迭代器的复制函数。order 参数用于控制分配结果的内存布局，通常希望使用 NPY_KEEPORDER。
PyObject *CopyArray(PyObject *arr, NPY_ORDER order)
{
NpyIter *iter;
NpyIter_IterNextFunc *iternext;
PyObject *op[2], *ret;
npy_uint32 flags;
npy_uint32 op_flags[2];
npy_intp itemsize, *innersizeptr, innerstride;
char **dataptrarray;
/*
* No inner iteration - inner loop is handled by CopyArray code
*/
flags = NPY_ITER_EXTERNAL_LOOP;
/*
* Tell the constructor to automatically allocate the output.
* The data type of the output will match that of the input.
*/
op[0] = arr;
op[1] = NULL;
op_flags[0] = NPY_ITER_READONLY;
op_flags[1] = NPY_ITER_WRITEONLY | NPY_ITER_ALLOCATE;
/* Construct the iterator */
iter = NpyIter_MultiNew(2, op, flags, order, NPY_NO_CASTING,
op_flags, NULL);
if (iter == NULL) {
return NULL;
}
/*
* Make a copy of the iternext function pointer and
* a few other variables the inner loop needs.
*/
iternext = NpyIter_GetIterNext(iter, NULL);
innerstride = NpyIter_GetInnerStrideArray(iter)[0];
itemsize = NpyIter_GetDescrArray(iter)[0]->elsize;
/*
* The inner loop size and data pointers may change during the
* loop, so just cache the addresses.
*/
innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);
dataptrarray = NpyIter_GetDataPtrArray(iter);
/*
* Note that because the iterator allocated the output,
* it matches the iteration order and is packed tightly,
* so we don't need to check it like the input.
*/
if (innerstride == itemsize) {
do {
memcpy(dataptrarray[1], dataptrarray[0],
itemsize * (*innersizeptr));
} while (iternext(iter));
} else {
/* For efficiency, should specialize this based on item size... */
npy_intp i;
do {
npy_intp size = *innersizeptr;
char *src = dataptrarray[0], *dst = dataptrarray[1];
for(i = 0; i < size; i++, src += innerstride, dst += itemsize) {
memcpy(dst, src, itemsize);
}
} while (iternext(iter));
}
/* Get the result from the iterator object array */
ret = NpyIter_GetOperandArray(iter)[1];
Py_INCREF(ret);
if (NpyIter_Deallocate(iter) != NPY_SUCCEED) {
Py_DECREF(ret);
return NULL;
}
return ret;
}
多索引跟踪示例#
此示例展示了如何使用 NPY_ITER_MULTI_INDEX 标志。为简单起见，我们假设参数是一个二维数组。
int PrintMultiIndex(PyArrayObject *arr) {
NpyIter *iter;
NpyIter_IterNextFunc *iternext;
npy_intp multi_index[2];
iter = NpyIter_New(
arr, NPY_ITER_READONLY | NPY_ITER_MULTI_INDEX | NPY_ITER_REFS_OK,
NPY_KEEPORDER, NPY_NO_CASTING, NULL);
if (iter == NULL) {
return -1;
}
if (NpyIter_GetNDim(iter) != 2) {
NpyIter_Deallocate(iter);
PyErr_SetString(PyExc_ValueError, "Array must be 2-D");
return -1;
}
if (NpyIter_GetIterSize(iter) != 0) {
iternext = NpyIter_GetIterNext(iter, NULL);
if (iternext == NULL) {
NpyIter_Deallocate(iter);
return -1;
}
NpyIter_GetMultiIndexFunc *get_multi_index =
NpyIter_GetGetMultiIndex(iter, NULL);
if (get_multi_index == NULL) {
NpyIter_Deallocate(iter);
return -1;
}
do {
get_multi_index(iter, multi_index);
printf("multi_index is [%" NPY_INTP_FMT ", %" NPY_INTP_FMT "]\n",
multi_index[0], multi_index[1]);
} while (iternext(iter));
}
if (!NpyIter_Deallocate(iter)) {
return -1;
}
return 0;
}
当使用一个 2x3 数组调用时，上面的示例会打印出
multi_index is [0, 0]
multi_index is [0, 1]
multi_index is [0, 2]
multi_index is [1, 0]
multi_index is [1, 1]
multi_index is [1, 2]
迭代器数据类型#
迭代器的布局是内部细节，用户代码只能看到一个不完整的结构体。
-
type NpyIter#
这是迭代器的不透明指针类型。只能通过迭代器 API 访问其内容。
-
type NpyIter_Type#
这是将迭代器暴露给 Python 的类型。目前，没有暴露任何 API 来提供对 Python 创建的迭代器值的访问。如果在 Python 中创建迭代器，则必须在 Python 中使用，反之亦然。此类 API 很可能在未来的版本中创建。
-
type NpyIter_IterNextFunc#
这是迭代循环的函数指针，由
NpyIter_GetIterNext返回。
-
type NpyIter_GetMultiIndexFunc#
这是获取当前迭代器多索引的函数指针，由
NpyIter_GetGetMultiIndex返回。
构造与销毁#
-
NpyIter *NpyIter_New(PyArrayObject *op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, PyArray_Descr *dtype)#
为给定的 numpy 数组对象
op创建一个迭代器。可在
flags中传递的标志是NpyIter_MultiNew中记载的全局标志和每个操作数标志的任意组合，但NPY_ITER_ALLOCATE除外。任何
NPY_ORDER枚举值都可以传递给order。对于高效迭代，NPY_KEEPORDER是最佳选择，而其他顺序则强制特定的迭代模式。任何
NPY_CASTING枚举值都可以传递给casting。这些值包括NPY_NO_CASTING、NPY_EQUIV_CASTING、NPY_SAFE_CASTING、NPY_SAME_KIND_CASTING和NPY_UNSAFE_CASTING。要允许类型转换发生，还必须启用复制或缓冲。如果
dtype不是NULL，则表示需要该数据类型。如果允许复制，并且数据可转换，它将创建临时副本。如果启用NPY_ITER_UPDATEIFCOPY，它还将在迭代器销毁时通过另一次类型转换将数据复制回去。如果发生错误则返回 NULL，否则返回已分配的迭代器。
要创建一个类似于旧迭代器的迭代器，这应该可行。
iter = NpyIter_New(op, NPY_ITER_READWRITE, NPY_CORDER, NPY_NO_CASTING, NULL);
如果你想用对齐的
double代码编辑一个数组，但顺序不重要，你可以使用这个。dtype = PyArray_DescrFromType(NPY_DOUBLE); iter = NpyIter_New(op, NPY_ITER_READWRITE| NPY_ITER_BUFFERED| NPY_ITER_NBO| NPY_ITER_ALIGNED, NPY_KEEPORDER, NPY_SAME_KIND_CASTING, dtype); Py_DECREF(dtype);
-
NpyIter *NpyIter_MultiNew(npy_intp nop, PyArrayObject **op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, npy_uint32 *op_flags, PyArray_Descr **op_dtypes)#
使用常规 NumPy 广播规则，为
op中提供的nop数组对象创建一个迭代器以进行广播。任何
NPY_ORDER枚举值都可以传递给order。对于高效迭代，NPY_KEEPORDER是最佳选择，而其他顺序则强制特定的迭代模式。当使用NPY_KEEPORDER时，如果你还想确保迭代不会沿某个轴反转，你应该传递标志NPY_ITER_DONT_NEGATE_STRIDES。任何
NPY_CASTING枚举值都可以传递给casting。这些值包括NPY_NO_CASTING、NPY_EQUIV_CASTING、NPY_SAFE_CASTING、NPY_SAME_KIND_CASTING和NPY_UNSAFE_CASTING。要允许类型转换发生，还必须启用复制或缓冲。如果
op_dtypes不是NULL，它为每个op[i]指定一个数据类型或NULL。如果发生错误则返回 NULL，否则返回已分配的迭代器。
可在
flags中传递的、应用于整个迭代器的标志有：
-
NPY_ITER_C_INDEX#
使迭代器跟踪与 C 顺序匹配的扁平索引。此选项不能与
NPY_ITER_F_INDEX一起使用。
-
NPY_ITER_F_INDEX#
使迭代器跟踪与 Fortran 顺序匹配的扁平索引。此选项不能与
NPY_ITER_C_INDEX一起使用。
-
NPY_ITER_MULTI_INDEX#
使迭代器跟踪多索引。这会阻止迭代器合并轴以生成更大的内部循环。如果循环未被缓冲且未跟踪任何索引（可调用
NpyIter_RemoveAxis），则迭代器大小可能为-1，表示迭代器过大。这可能由于复杂的广播而发生，并在设置迭代器范围、移除多索引或获取下一个函数时导致错误。但是，如果移除后大小足够小，可以再次移除轴并正常使用迭代器。
-
NPY_ITER_EXTERNAL_LOOP#
使迭代器跳过最内层循环的迭代，要求迭代器的用户自行处理。
此标志与
NPY_ITER_C_INDEX、NPY_ITER_F_INDEX和NPY_ITER_MULTI_INDEX不兼容。
-
NPY_ITER_DONT_NEGATE_STRIDES#
这仅在为 order 参数指定
NPY_KEEPORDER时影响迭代器。默认情况下，使用NPY_KEEPORDER时，迭代器会反转具有负步长的轴，以便内存以正向遍历。此标志禁用此步骤。如果你想使用轴的底层内存顺序，但不想反转轴，请使用此标志。例如，这与numpy.ravel(a, order='K')的行为相同。
-
NPY_ITER_COMMON_DTYPE#
使迭代器将所有操作数转换为一个共同的数据类型，该数据类型根据 ufunc 类型提升规则计算。必须启用复制或缓冲。
如果共同数据类型是预先知道的，则不要使用此标志。而是为所有操作数设置请求的 dtype。
-
NPY_ITER_REFS_OK#
指示迭代器可以接受并使用带有引用类型（对象数组或包含对象类型的结构化数组）的数组。如果启用此标志，调用者必须确保检查
NpyIter_IterationNeedsAPI(iter)是否为 true，在这种情况下，迭代期间可能不会释放 GIL。如果您正在使用已知 dtype，则 NpyIter_GetTransferFlags 是一种更快、更精确的方法，可以检查迭代器是否因缓冲而需要 API。
-
NPY_ITER_ZEROSIZE_OK#
指示允许大小为零的数组。由于典型的迭代循环不能自然地处理零大小的数组，因此在进入迭代循环之前，您必须检查 IterSize 是否大于零。目前只检查操作数，不检查强制形状。
-
NPY_ITER_REDUCE_OK#
允许可写操作数具有零步长且大小大于一的维度。请注意，此类操作数必须是读/写的。
启用缓冲时，这也会切换到特殊的缓冲模式，该模式会根据需要缩短循环长度，以避免踩踏正在被归约的值。
请注意，如果你想对自动分配的输出进行归约，你必须使用
NpyIter_GetOperandArray获取其引用，然后在执行迭代循环之前将每个值设置为归约单位。在缓冲归约的情况下，这意味着你还必须指定标志NPY_ITER_DELAY_BUFALLOC，然后在初始化分配的操作数后重置迭代器以准备缓冲区。
-
NPY_ITER_RANGED#
启用对完整
iterindex范围[0, NpyIter_IterSize(iter))的子范围迭代支持。使用函数NpyIter_ResetToIterIndexRange来指定迭代范围。此标志只能在启用
NPY_ITER_BUFFERED时与NPY_ITER_EXTERNAL_LOOP一起使用。这是因为如果没有缓冲，内部循环始终是最内层迭代维度的大小，并且允许它被切分将需要特殊处理，这实际上使其更像是缓冲版本。
-
NPY_ITER_BUFFERED#
使迭代器存储缓冲数据，并使用缓冲来满足数据类型、对齐和字节序要求。要缓冲操作数，请勿指定
NPY_ITER_COPY或NPY_ITER_UPDATEIFCOPY标志，因为它们将覆盖缓冲。缓冲对于使用迭代器的 Python 代码特别有用，允许一次处理更大块的数据，以分摊 Python 解释器的开销。如果与
NPY_ITER_EXTERNAL_LOOP一起使用，由于步长的布局方式，调用者的内部循环可能会获得比没有缓冲时更大块的数据。请注意，如果一个操作数被赋予标志
NPY_ITER_COPY或NPY_ITER_UPDATEIFCOPY，则会优先进行复制而非缓冲。当数组被广播从而需要复制元素以获得恒定步长时，仍然会发生缓冲。在正常缓冲中，每个内部循环的大小等于缓冲区大小，如果指定了
NPY_ITER_GROWINNER，则可能更大。如果启用了NPY_ITER_REDUCE_OK并且发生了归约，内部循环可能会根据归约的结构而变小。
-
NPY_ITER_GROWINNER#
启用缓冲时，如果不需要缓冲，此选项允许内部循环的大小增大。如果您正在直接遍历所有数据，而不是为每个内部循环使用小型的缓存友好临时值数组，则此选项最适合使用。
-
NPY_ITER_DELAY_BUFALLOC#
启用缓冲时，此选项会延迟缓冲区的分配，直到调用
NpyIter_Reset或其他重置函数。此标志的存在是为了避免在多线程迭代中复制缓冲迭代器的多个副本时浪费缓冲区数据。此标志的另一个用途是设置归约操作。创建迭代器后，如果迭代器自动分配了归约输出（请务必使用 READWRITE 访问），则其值可以初始化为归约单位。使用
NpyIter_GetOperandArray获取该对象。然后，调用NpyIter_Reset来分配并用其初始值填充缓冲区。
-
NPY_ITER_COPY_IF_OVERLAP#
如果任何写操作数与任何读操作数存在重叠，则通过创建临时副本（如有必要，为写操作数启用 UPDATEIFCOPY）来消除所有重叠。如果存在包含两个数组共有数据的内存地址，则一对操作数存在重叠。
由于精确的重叠检测在维度数量上具有指数级运行时，因此决策基于启发式方法，该方法存在误报（在不寻常情况下不必要的复制），但没有漏报。
如果存在任何读/写重叠，此标志可确保操作结果与所有操作数都被复制时的结果相同。在需要进行复制的情况下，如果没有此标志，计算结果可能会是未定义的！
可在
op_flags[i]中传递的标志，其中0 <= i < nop：
-
NPY_ITER_READWRITE#
-
NPY_ITER_READONLY#
-
NPY_ITER_WRITEONLY#
指示迭代器用户将如何读取或写入
op[i]。每个操作数必须且只能指定这些标志中的一个。对用户提供的操作数使用NPY_ITER_READWRITE或NPY_ITER_WRITEONLY可能会触发WRITEBACKIFCOPY语义。当调用NpyIter_Deallocate时，数据将被写回到原始数组。
-
NPY_ITER_COPY#
如果
op[i]不满足构造函数标志和参数指定的数据类型或对齐要求，则允许创建其副本。
-
NPY_ITER_UPDATEIFCOPY#
触发
NPY_ITER_COPY，并且当一个数组操作数被标记为写入并被复制时，在调用NpyIter_Deallocate时，导致副本中的数据被复制回op[i]。如果操作数被标记为只写且需要复制，则会创建一个未初始化的临时数组，然后在调用
NpyIter_Deallocate时将其复制回op[i]，而不是执行不必要的复制操作。
-
NPY_ITER_NBO#
-
NPY_ITER_ALIGNED#
-
NPY_ITER_CONTIG#
使迭代器为
op[i]提供符合本机字节序、根据 dtype 要求对齐、连续或其任意组合的数据。默认情况下，迭代器生成指向所提供数组的指针，这些数组可能是对齐或不对齐的，并且具有任何字节序。如果未启用复制或缓冲，并且操作数数据不满足约束，则会引发错误。
连续性约束仅适用于内部循环，后续内部循环可能具有任意指针更改。
如果请求的数据类型不是本机字节序，NBO 标志将覆盖它，并将请求的数据类型转换为本机字节序。
-
NPY_ITER_ALLOCATE#
这是用于输出数组的，要求设置标志
NPY_ITER_WRITEONLY或NPY_ITER_READWRITE。如果op[i]为 NULL，则创建一个具有最终广播维度且布局与迭代器的迭代顺序匹配的新数组。当
op[i]为 NULL 时，请求的数据类型op_dtypes[i]也可以为 NULL，在这种情况下，它将从被标记为可读的数组的 dtypes 中自动生成。生成 dtype 的规则与 UFuncs 的规则相同。特别值得注意的是所选 dtype 中字节序的处理。如果只有一个输入，则直接使用输入的 dtype。否则，如果组合了多个输入 dtypes，则输出将采用本机字节序。使用此标志分配后，调用者可以通过调用
NpyIter_GetOperandArray并获取返回的 C 数组中的第 i 个对象来检索新数组。调用者必须对其调用 Py_INCREF 以获取对数组的引用。
-
NPY_ITER_NO_SUBTYPE#
与
NPY_ITER_ALLOCATE一起使用时，此标志禁用为输出分配数组子类型，强制其为纯 ndarray。TODO: 也许引入一个函数
NpyIter_GetWrappedOutput并移除此标志会更好？
-
NPY_ITER_NO_BROADCAST#
确保输入或输出与迭代维度完全匹配。
-
NPY_ITER_ARRAYMASK#
指示此操作数是用于向带有
NPY_ITER_WRITEMASKED标志的操作数写入时选择元素的掩码。只有一个操作数可以应用NPY_ITER_ARRAYMASK标志。带有此标志的操作数的数据类型应为
NPY_BOOL、NPY_MASK，或者是一个所有字段都是有效掩码 dtype 的结构体 dtype。在后一种情况下，它必须与一个被 WRITEMASKED 的结构体操作数匹配，因为它正在为该数组的每个字段指定一个掩码。此标志仅影响从缓冲区写回数组的操作。这意味着，如果操作数同时也是
NPY_ITER_READWRITE或NPY_ITER_WRITEONLY，则执行迭代的代码可以写入此操作数来控制哪些元素保持不变，哪些元素将被修改。当掩码应是输入掩码的组合时，这非常有用。
-
NPY_ITER_WRITEMASKED#
此数组是所有
writemasked操作数的掩码。代码使用writemasked标志，该标志指示只有选定 ARRAYMASK 操作数为 True 的元素才会被写入。通常，迭代器不强制执行此操作，由执行迭代的代码来遵循该约定。当使用
writemasked标志且此操作数被缓冲时，这会改变数据从缓冲区复制到数组的方式。使用掩码复制例程，该例程仅复制缓冲区中那些对应于 ARRAYMASK 操作数中writemask返回 true 的元素。
-
NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE#
在内存重叠检查中，假设启用了
NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE的操作数仅按迭代器顺序访问。这使迭代器能够推断数据依赖性，从而可能避免不必要的复制。
此标志仅在迭代器上启用了
NPY_ITER_COPY_IF_OVERLAP时才有效。
-
NpyIter *NpyIter_AdvancedNew(npy_intp nop, PyArrayObject **op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, npy_uint32 *op_flags, PyArray_Descr **op_dtypes, int oa_ndim, int **op_axes, npy_intp const *itershape, npy_intp buffersize)#
扩展了
NpyIter_MultiNew，增加了几个高级选项，提供了对广播和缓冲的更多控制。如果将 -1/NULL 值传递给
oa_ndim、op_axes、itershape和buffersize，则等效于NpyIter_MultiNew。参数
oa_ndim在不为零或 -1 时，指定将使用自定义广播进行迭代的维度数量。如果提供了该参数，则必须提供op_axes，并且也可以提供itershape。op_axes参数允许您详细控制操作数数组的轴如何匹配并迭代。在op_axes中，您必须提供一个包含nop个指向oa_ndim大小的npy_intp类型数组的指针。如果op_axes中的条目为 NULL，则将应用正常的广播规则。在op_axes[j][i]中，存储的是op[j]的有效轴，或者 -1 表示newaxis。在每个op_axes[j]数组中，轴不得重复。以下示例展示了正常广播如何应用于 3D 数组、2D 数组、1D 数组和标量。注意：在 NumPy 1.8 之前，
oa_ndim == 0用于表示op_axes和itershape未使用。此用法已弃用，应替换为 -1。为了更好的向后兼容性，在这种情况下可以使用NpyIter_MultiNew。int oa_ndim = 3; /* # iteration axes */ int op0_axes[] = {0, 1, 2}; /* 3-D operand */ int op1_axes[] = {-1, 0, 1}; /* 2-D operand */ int op2_axes[] = {-1, -1, 0}; /* 1-D operand */ int op3_axes[] = {-1, -1, -1} /* 0-D (scalar) operand */ int* op_axes[] = {op0_axes, op1_axes, op2_axes, op3_axes};
itershape参数允许您强制迭代器具有特定的迭代形状。它是一个长度为oa_ndim的数组。当条目为负数时，其值由操作数确定。此参数允许自动分配的输出获得不与任何输入维度匹配的额外维度。如果
buffersize为零，则使用默认缓冲区大小，否则它指定要使用的缓冲区大小。建议使用 2 的幂次方的缓冲区，例如 4096 或 8192。如果发生错误则返回 NULL，否则返回已分配的迭代器。
-
NpyIter *NpyIter_Copy(NpyIter *iter)#
复制给定的迭代器。此函数主要用于启用数据的多线程迭代。
TODO：将此内容移至关于多线程迭代的章节。
多线程迭代的推荐方法是：首先，使用标志
NPY_ITER_EXTERNAL_LOOP、NPY_ITER_RANGED、NPY_ITER_BUFFERED、NPY_ITER_DELAY_BUFALLOC，并可能包括NPY_ITER_GROWINNER来创建一个迭代器。为每个线程创建一个此迭代器的副本（第一个迭代器除外）。然后，获取迭代索引范围[0, NpyIter_GetIterSize(iter))并将其拆分为任务，例如使用 TBB 的 parallel_for 循环。当一个线程获得要执行的任务时，它会通过调用NpyIter_ResetToIterIndexRange并迭代整个范围来使用其迭代器副本。在多线程代码或未持有 Python GIL 的代码中使用迭代器时，必须注意仅调用在该上下文中安全的函数。
NpyIter_Copy在没有 Python GIL 的情况下无法安全调用，因为它会增加 Python 引用。通过将errmsg参数作为非 NULL 传递，可以安全地调用Reset*和其他一些函数，以便函数通过它返回错误，而不是设置 Python 异常。必须为每个副本调用
NpyIter_Deallocate。
-
int NpyIter_RemoveAxis(NpyIter *iter, int axis)#
从迭代中移除一个轴。这要求在创建迭代器时设置了
NPY_ITER_MULTI_INDEX标志，并且在启用缓冲或正在跟踪索引时不起作用。此函数还会将迭代器重置为初始状态。例如，这对于设置累加循环很有用。可以首先创建包含所有维度的迭代器，包括累加轴，以便正确创建输出。然后，可以移除累加轴，并以嵌套方式进行计算。
警告：此函数可能会改变迭代器的内部内存布局。任何来自迭代器的缓存函数或指针都必须重新获取！迭代器范围也将被重置。
返回
NPY_SUCCEED或NPY_FAIL。
-
int NpyIter_RemoveMultiIndex(NpyIter *iter)#
如果迭代器正在跟踪多索引，此函数将取消对它们的支持，并执行在不需要多索引时可能的进一步迭代器优化。此函数还会将迭代器重置为初始状态。
警告：此函数可能会改变迭代器的内部内存布局。任何来自迭代器的缓存函数或指针都必须重新获取！
调用此函数后，NpyIter_HasMultiIndex(iter) 将返回 false。
返回
NPY_SUCCEED或NPY_FAIL。
-
int NpyIter_EnableExternalLoop(NpyIter *iter)#
如果调用了
NpyIter_RemoveMultiIndex，你可能需要启用标志NPY_ITER_EXTERNAL_LOOP。此标志不允许与NPY_ITER_MULTI_INDEX一起使用，因此提供此函数以便在调用NpyIter_RemoveMultiIndex后启用该功能。此函数还会将迭代器重置为初始状态。警告：此函数会改变迭代器的内部逻辑。任何来自迭代器的缓存函数或指针都必须重新获取！
返回
NPY_SUCCEED或NPY_FAIL。
-
NPY_ARRAYMETHOD_FLAGS NpyIter_GetTransferFlags(NpyIter *iter)#
2.3 版本新增。
获取 NPY_METH_RUNTIME_FLAGS，它提供了有关缓冲是否需要 Python GIL (NPY_METH_REQUIRES_PYAPI) 或是否可以设置浮点错误 (NPY_METH_NO_FLOATINGPOINT_ERRORS) 的信息。
在 NumPy 2.3 之前，可用的公共函数是
NpyIter_IterationNeedsAPI，该函数仍然可用，并且除了检查缓冲/迭代本身的需求外，还检查对象（或类似）dtypes。通常，应优先使用此函数。
-
int NpyIter_Reset(NpyIter *iter, char **errmsg)#
将迭代器重置回其初始状态，位于迭代范围的开头。
返回
NPY_SUCCEED或NPY_FAIL。如果 errmsg 为非 NULL，则返回NPY_FAIL时不会设置 Python 异常。相反，*errmsg 被设置为错误消息。当 errmsg 为非 NULL 时，可以在不持有 Python GIL 的情况下安全地调用该函数。
-
int NpyIter_ResetToIterIndexRange(NpyIter *iter, npy_intp istart, npy_intp iend, char **errmsg)#
重置迭代器并将其限制在
iterindex范围[istart, iend)。有关如何在多线程迭代中使用此功能的解释，请参见NpyIter_Copy。这要求在迭代器构造函数中传递了标志NPY_ITER_RANGED。如果你想同时重置
iterindex范围和基指针，你可以执行以下操作以避免额外的缓冲区复制（复制此代码时务必添加返回码错误检查）。/* Set to a trivial empty range */ NpyIter_ResetToIterIndexRange(iter, 0, 0); /* Set the base pointers */ NpyIter_ResetBasePointers(iter, baseptrs); /* Set to the desired range */ NpyIter_ResetToIterIndexRange(iter, istart, iend);
返回
NPY_SUCCEED或NPY_FAIL。如果 errmsg 为非 NULL，则返回NPY_FAIL时不会设置 Python 异常。相反，*errmsg 被设置为错误消息。当 errmsg 为非 NULL 时，可以在不持有 Python GIL 的情况下安全地调用该函数。
-
int NpyIter_ResetBasePointers(NpyIter *iter, char **baseptrs, char **errmsg)#
将迭代器重置回其初始状态，但使用
baseptrs中的值作为数据，而不是来自被迭代数组的指针。此函数旨在与op_axes参数一起使用，适用于包含两个或更多迭代器的嵌套迭代代码。返回
NPY_SUCCEED或NPY_FAIL。如果 errmsg 为非 NULL，则返回NPY_FAIL时不会设置 Python 异常。相反，*errmsg 被设置为错误消息。当 errmsg 为非 NULL 时，可以在不持有 Python GIL 的情况下安全地调用该函数。TODO：将以下内容移至关于嵌套迭代器的特殊章节。
为嵌套迭代创建迭代器需要谨慎。所有迭代器操作数必须完全匹配，否则对
NpyIter_ResetBasePointers的调用将无效。这意味着不应随意使用自动复制和输出分配。通过创建一个启用所有转换参数的迭代器，然后使用NpyIter_GetOperandArray函数获取已分配的操作数，并将它们传递给其余迭代器的构造函数，仍然可以使用迭代器的自动数据转换和类型转换功能。警告：为嵌套迭代创建迭代器时，代码不得在不同的迭代器中多次使用同一个维度。如果这样做，嵌套迭代将在迭代期间产生越界指针。
警告：为嵌套迭代创建迭代器时，缓冲只能应用于最内层的迭代器。如果缓冲迭代器用作
baseptrs的源，它将指向一个小的缓冲区而不是数组，并且内部迭代将无效。使用嵌套迭代器的模式如下。
NpyIter *iter1, *iter1; NpyIter_IterNextFunc *iternext1, *iternext2; char **dataptrs1; /* * With the exact same operands, no copies allowed, and * no axis in op_axes used both in iter1 and iter2. * Buffering may be enabled for iter2, but not for iter1. */ iter1 = ...; iter2 = ...; iternext1 = NpyIter_GetIterNext(iter1); iternext2 = NpyIter_GetIterNext(iter2); dataptrs1 = NpyIter_GetDataPtrArray(iter1); do { NpyIter_ResetBasePointers(iter2, dataptrs1); do { /* Use the iter2 values */ } while (iternext2(iter2)); } while (iternext1(iter1));
-
int NpyIter_GotoMultiIndex(npy_intp const *multi_index)#
调整迭代器以指向
multi_index指向的ndim索引。如果未跟踪多索引、索引超出范围或内部循环迭代被禁用，则返回错误。返回
NPY_SUCCEED或NPY_FAIL。
-
int NpyIter_GotoIndex(NpyIter *iter, npy_intp index)#
调整迭代器以指向指定的
index。如果迭代器是使用NPY_ITER_C_INDEX标志构造的，则index是 C 顺序索引；如果迭代器是使用NPY_ITER_F_INDEX标志构造的，则index是 Fortran 顺序索引。如果没有正在跟踪的索引、索引超出范围或内部循环迭代被禁用，则返回错误。返回
NPY_SUCCEED或NPY_FAIL。
-
npy_intp NpyIter_GetIterSize(NpyIter *iter)#
返回正在迭代的元素数量。这是形状中所有维度的乘积。当跟踪多索引时（并且可能调用
NpyIter_RemoveAxis），大小可能为-1，表示迭代器过大。这样的迭代器是无效的，但在调用NpyIter_RemoveAxis后可能变得有效。没有必要检查这种情况。
-
void NpyIter_GetIterIndexRange(NpyIter *iter, npy_intp *istart, npy_intp *iend)#
获取正在迭代的
iterindex子范围。如果未指定NPY_ITER_RANGED，则这始终返回范围[0, NpyIter_IterSize(iter))。
-
int NpyIter_GotoIterIndex(NpyIter *iter, npy_intp iterindex)#
调整迭代器以指向指定的
iterindex。IterIndex 是一个与迭代器的迭代顺序匹配的索引。如果iterindex超出范围、启用缓冲或禁用内部循环迭代，则返回错误。返回
NPY_SUCCEED或NPY_FAIL。
-
npy_bool NpyIter_HasDelayedBufAlloc(NpyIter *iter)#
如果
NPY_ITER_DELAY_BUFALLOC标志已传递给迭代器构造函数，并且尚未调用任一重置函数，则返回 1，否则返回 0。
-
npy_bool NpyIter_HasExternalLoop(NpyIter *iter)#
如果调用者需要处理最内层的 1 维循环，则返回 1；如果迭代器处理所有循环，则返回 0。这由构造函数标志
NPY_ITER_EXTERNAL_LOOP或NpyIter_EnableExternalLoop控制。
-
npy_bool NpyIter_HasMultiIndex(NpyIter *iter)#
如果迭代器是使用
NPY_ITER_MULTI_INDEX标志创建的，则返回 1，否则返回 0。
-
npy_bool NpyIter_HasIndex(NpyIter *iter)#
如果迭代器是使用
NPY_ITER_C_INDEX或NPY_ITER_F_INDEX标志创建的，则返回 1，否则返回 0。
-
npy_bool NpyIter_IsBuffered(NpyIter *iter)#
如果迭代器是使用
NPY_ITER_BUFFERED标志创建的，则返回 1，否则返回 0。
-
npy_bool NpyIter_IsGrowInner(NpyIter *iter)#
如果迭代器是使用
NPY_ITER_GROWINNER标志创建的，则返回 1，否则返回 0。
-
npy_intp *NpyIter_GetAxisStrideArray(NpyIter *iter, int axis)#
获取指定轴的步幅数组。要求迭代器正在跟踪多索引，并且未启用缓冲。
当您希望以某种方式匹配操作数轴，然后使用
NpyIter_RemoveAxis移除它们以手动处理时，可以使用此功能。通过在移除轴之前调用此函数，您可以获得用于手动处理的步幅。出错时返回
NULL。
-
int NpyIter_GetShape(NpyIter *iter, npy_intp *outshape)#
在
outshape中返回迭代器的广播形状。这只能在跟踪多索引的迭代器上调用。返回
NPY_SUCCEED或NPY_FAIL。
-
PyArray_Descr **NpyIter_GetDescrArray(NpyIter *iter)#
这返回一个指向正在迭代对象的
nop数据类型 Descrs 的指针。结果指向iter内部，因此调用者不会获得对 Descrs 的任何引用。此指针可以在迭代循环之前缓存，调用
iternext不会改变它。
-
PyObject **NpyIter_GetOperandArray(NpyIter *iter)#
这返回一个指向正在迭代的
nop操作数 PyObject 的指针。结果指向iter内部，因此调用者不会获得对 PyObject 的任何引用。
-
PyObject *NpyIter_GetIterView(NpyIter *iter, npy_intp i)#
这返回对新 ndarray 视图的引用，该视图是数组
NpyIter_GetOperandArray中第 i 个对象的视图，其维度和步幅与内部优化迭代模式匹配。此视图的 C 顺序迭代等同于迭代器的迭代顺序。例如，如果迭代器是使用单个数组作为其输入创建的，并且可以重新排列其所有轴然后将其折叠成单个步幅迭代，则这将返回一个一维数组的视图。
-
void NpyIter_GetReadFlags(NpyIter *iter, char *outreadflags)#
填充
nop标志。如果op[i]可以读取，则将outreadflags[i]设置为 1；否则设置为 0。
-
void NpyIter_GetWriteFlags(NpyIter *iter, char *outwriteflags)#
填充
nop标志。如果op[i]可以写入，则将outwriteflags[i]设置为 1；否则设置为 0。
-
int NpyIter_CreateCompatibleStrides(NpyIter *iter, npy_intp itemsize, npy_intp *outstrides)#
构建一组步幅，这些步幅与使用
NPY_ITER_ALLOCATE标志创建的输出数组的步幅相同，其中 op_axes 传递为 NULL。这适用于连续打包的数据，但不一定按 C 或 Fortran 顺序。这应与NpyIter_GetShape和NpyIter_GetNDim以及传递给构造函数的NPY_ITER_MULTI_INDEX标志一起使用。此函数的一个用例是匹配迭代器的形状和布局，并附加一个或多个维度。例如，为了为数值梯度生成每个输入值的向量，您可以将 ndim*itemsize 作为 itemsize 传入，然后在末尾添加一个大小为 ndim、步幅为 itemsize 的维度。要执行 Hessian 矩阵，您可以做同样的事情，但添加两个维度，或利用对称性并将其打包成一个具有特定编码的维度。
仅当迭代器正在跟踪多索引且使用了
NPY_ITER_DONT_NEGATE_STRIDES以防止轴以逆序迭代时，才能调用此函数。如果使用此方法创建数组，则每次迭代简单地添加 'itemsize' 将遍历与迭代器匹配的新数组。
返回
NPY_SUCCEED或NPY_FAIL。
-
npy_bool NpyIter_IsFirstVisit(NpyIter *iter, int iop)#
检查迭代器指向的指定归约操作数的元素是否首次被访问。该函数对归约操作数和禁用缓冲的情况返回合理的结果。对于缓冲的非归约操作数，结果可能不正确。
此函数仅适用于 EXTERNAL_LOOP 模式，在该模式未启用时会产生一些错误结果。
如果此函数返回 true，调用者还应检查操作数的内部循环步幅，因为如果该步幅为 0，则只有最内层外部循环的第一个元素是首次被访问。
警告：出于性能原因，未对 'iop' 进行边界检查，未确认 'iop' 确实是归约操作数，也未确认 EXTERNAL_LOOP 模式已启用。这些检查是调用者的责任，应在任何内部循环之外进行。
迭代函数#
-
NpyIter_IterNextFunc *NpyIter_GetIterNext(NpyIter *iter, char **errmsg)#
返回迭代的函数指针。此函数可以计算函数指针的专用版本，而不是将其存储在迭代器结构中。因此，为了获得良好性能，需要将函数指针保存到变量中，而不是在每次循环迭代时检索。
如果出错则返回 NULL。如果 errmsg 非 NULL，则当返回
NPY_FAIL时不会设置 Python 异常。而是将 *errmsg 设置为错误消息。当 errmsg 非 NULL 时，可以在不持有 Python GIL 的情况下安全地调用该函数。典型的循环结构如下。
NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL); char** dataptr = NpyIter_GetDataPtrArray(iter); do { /* use the addresses dataptr[0], ... dataptr[nop-1] */ } while(iternext(iter));
当指定
NPY_ITER_EXTERNAL_LOOP时，典型的内部循环结构如下。NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL); char** dataptr = NpyIter_GetDataPtrArray(iter); npy_intp* stride = NpyIter_GetInnerStrideArray(iter); npy_intp* size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size; npy_intp iop, nop = NpyIter_GetNOp(iter); do { size = *size_ptr; while (size--) { /* use the addresses dataptr[0], ... dataptr[nop-1] */ for (iop = 0; iop < nop; ++iop) { dataptr[iop] += stride[iop]; } } } while (iternext());
请注意，我们正在使用迭代器内部的 dataptr 数组，而不是将值复制到局部临时变量中。这之所以可能，是因为当调用
iternext()时，这些指针将被新值覆盖，而不是增量更新。如果正在使用编译时固定缓冲区（同时设置
NPY_ITER_BUFFERED和NPY_ITER_EXTERNAL_LOOP标志），则内部大小也可以用作信号。当iternext()返回 false 时，大小保证变为零，从而启用以下循环结构。请注意，如果使用此结构，则不应传递NPY_ITER_GROWINNER作为标志，因为它在某些情况下会导致更大的大小。/* The constructor should have buffersize passed as this value */ #define FIXED_BUFFER_SIZE 1024 NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL); char **dataptr = NpyIter_GetDataPtrArray(iter); npy_intp *stride = NpyIter_GetInnerStrideArray(iter); npy_intp *size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size; npy_intp i, iop, nop = NpyIter_GetNOp(iter); /* One loop with a fixed inner size */ size = *size_ptr; while (size == FIXED_BUFFER_SIZE) { /* * This loop could be manually unrolled by a factor * which divides into FIXED_BUFFER_SIZE */ for (i = 0; i < FIXED_BUFFER_SIZE; ++i) { /* use the addresses dataptr[0], ... dataptr[nop-1] */ for (iop = 0; iop < nop; ++iop) { dataptr[iop] += stride[iop]; } } iternext(); size = *size_ptr; } /* Finish-up loop with variable inner size */ if (size > 0) do { size = *size_ptr; while (size--) { /* use the addresses dataptr[0], ... dataptr[nop-1] */ for (iop = 0; iop < nop; ++iop) { dataptr[iop] += stride[iop]; } } } while (iternext());
-
NpyIter_GetMultiIndexFunc *NpyIter_GetGetMultiIndex(NpyIter *iter, char **errmsg)#
返回用于获取迭代器当前多索引的函数指针。如果迭代器未跟踪多索引，则返回 NULL。建议在迭代循环之前将此函数指针缓存到局部变量中。
如果出错则返回 NULL。如果 errmsg 非 NULL，则当返回
NPY_FAIL时不会设置 Python 异常。而是将 *errmsg 设置为错误消息。当 errmsg 非 NULL 时，可以在不持有 Python GIL 的情况下安全地调用该函数。
-
char **NpyIter_GetDataPtrArray(NpyIter *iter)#
这返回一个指向
nop数据指针的指针。如果未指定NPY_ITER_EXTERNAL_LOOP，则每个数据指针指向迭代器的当前数据项。如果未指定内部迭代，则它指向内部循环的第一个数据项。此指针可以在迭代循环之前缓存，调用
iternext不会改变它。此函数可以在不持有 Python GIL 的情况下安全地调用。
-
char **NpyIter_GetInitialDataPtrArray(NpyIter *iter)#
直接获取数据指针数组到数组中（从不进入缓冲区），对应于迭代索引 0。
这些指针与
NpyIter_ResetBasePointers接受的指针不同，因为沿某些轴的方向可能已被反转。此函数可以在不持有 Python GIL 的情况下安全地调用。
-
npy_intp *NpyIter_GetIndexPtr(NpyIter *iter)#
这返回一个指向正在跟踪的索引的指针，如果没有跟踪索引则返回 NULL。只有在构造期间指定了
NPY_ITER_C_INDEX或NPY_ITER_F_INDEX标志之一时才可以使用。
当使用 NPY_ITER_EXTERNAL_LOOP 标志时，代码需要知道执行内部循环的参数。这些函数提供该信息。
-
npy_intp *NpyIter_GetInnerStrideArray(NpyIter *iter)#
返回一个指向
nop步幅数组的指针，每个迭代对象一个，供内部循环使用。此指针可以在迭代循环之前缓存，调用
iternext不会改变它。此函数可以在不持有 Python GIL 的情况下安全地调用。警告：虽然指针可以缓存，但如果迭代器已缓冲，其值可能会改变。
-
npy_intp *NpyIter_GetInnerLoopSizePtr(NpyIter *iter)#
返回一个指向内部循环应执行的迭代次数的指针。
此地址可以在迭代循环之前缓存，调用
iternext不会改变它。该值本身在迭代期间可能会改变，特别是在启用缓冲的情况下。此函数可以在不持有 Python GIL 的情况下安全地调用。
-
void NpyIter_GetInnerFixedStrideArray(NpyIter *iter, npy_intp *out_strides)#
获取一组固定步幅的数组，或在整个迭代过程中不会改变的步幅。对于可能改变的步幅，将值 NPY_MAX_INTP 放入步幅中。
一旦迭代器准备好迭代（如果在
NPY_ITER_DELAY_BUFALLOC后进行重置），调用此函数以获取可用于选择快速内部循环函数的步幅。例如，如果步幅为 0，则意味着内部循环可以始终将值加载到变量中一次，然后在整个循环中使用该变量；如果步幅等于 itemsize，则可以使用该操作数的连续版本。此函数可以在不持有 Python GIL 的情况下安全地调用。
从旧版 NumPy 迭代器转换#
旧版迭代器 API 包含 PyArrayIter_Check、PyArray_Iter* 和 PyArray_ITER_* 等函数。多迭代器数组包括 PyArray_MultiIter*、PyArray_Broadcast 和 PyArray_RemoveSmallest。新的迭代器设计用单个对象和相关 API 替换了所有这些功能。新 API 的一个目标是，现有迭代器的所有用途都应该可以用新迭代器替换，而无需付出巨大努力。在 1.6 版本中，主要例外是邻域迭代器，它在此迭代器中没有相应的功能。
以下是新迭代器函数的使用转换表
迭代器函数 |
|
|
|
不支持（请改用对多个操作数的使用支持。） |
|
需要在 Python 暴露中添加此项 |
|
来自 |
|
|
|
多迭代器函数 |
|
来自 |
|
不支持（始终是步调一致的迭代） |
|
|
|
由 |
|
迭代器标志 |
|
其他函数 |
|
迭代器标志 |