数组迭代器 API#
在 1.6 版本加入.
数组迭代器#
数组迭代器封装了 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.为了高效迭代,:c:type: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.为了高效迭代,:c:data: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#
这仅在为顺序参数指定
NPY_KEEPORDER时影响迭代器.默认情况下,使用NPY_KEEPORDER时,迭代器会反转具有负步长的轴,以便按向前方向遍历内存.这会禁用此步骤.如果您想使用轴的底层内存顺序,但不想反转轴,请使用此标志.例如,这是numpy.ravel(a, order='K')的行为.
-
NPY_ITER_COMMON_DTYPE#
根据ufunc类型提升规则,使迭代器将所有操作数转换为通用数据类型.必须启用复制或缓冲.
如果已知常见数据类型,请不要使用此标志.相反,为所有操作数设置请求的 dtype.
-
NPY_ITER_REFS_OK#
指示带有引用类型（对象数组或包含对象类型的结构化数组）的数组可能在迭代器中被接受和使用.如果启用此标志,调用者必须确保检查
NpyIter_IterationNeedsAPI(iter)是否为真,在这种情况下,它可能不会在迭代期间释放GIL.
-
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#
在 1.7 版本加入.
指示该操作数是用于选择元素的掩码,当写入具有
NPY_ITER_WRITEMASKED标志的操作数时.只有一个操作数可以具有NPY_ITER_ARRAYMASK标志.带有此标志的操作数的数据类型应为
NPY_BOOL、NPY_MASK或一个结构化数据类型,其所有字段均为有效的掩码数据类型.在后一种情况下,它必须与正在 WRITEMASKED 的结构操作数相匹配,因为它为该数组的每个字段指定了一个掩码.此标志仅影响从缓冲区写回数组.这意味着如果操作数也是
NPY_ITER_READWRITE或NPY_ITER_WRITEONLY,进行迭代的代码可以写入此操作数以控制哪些元素将保持不变,哪些元素将被修改.这在掩码应为输入掩码的组合时非常有用.
-
NPY_ITER_WRITEMASKED#
在 1.7 版本加入.
这个数组是所有
writemasked操作数的掩码.代码使用writemasked标志,该标志表示只有选定的 ARRAYMASK 操作数为 True 的元素才会被写入.通常,迭代器不会强制执行这一点,而是由进行迭代的代码来遵守这一承诺.当使用
writemasked标志时,如果此操作数被缓冲,这将改变数据从缓冲区复制到数组的方式.使用掩码复制例程,该例程仅复制缓冲区中writemasked从 ARRAYMASK 操作数的相应元素返回 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]的有效轴,或者是表示newaxis的 -1.在每个op_axes[j]数组中,轴不能重复.以下示例是如何将正常广播应用于 3-D 数组、2-D 数组、1-D 数组和标量.注意:在 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的代码中使用迭代器时,必须注意只调用在该上下文中安全的函数.:c:func:NpyIter_Copy 不能在没有Python GIL的情况下安全调用,因为它会增加Python引用.``Reset*`` 和一些其他函数可以通过传递非NULL的``errmsg``参数安全调用,这样这些函数将通过它返回错误,而不是设置Python异常.
NpyIter_Deallocate必须为每个副本调用.
-
int NpyIter_RemoveAxis(NpyIter *iter, int axis)#
从迭代中移除一个轴.这要求在创建迭代器时设置了
NPY_ITER_MULTI_INDEX,并且如果启用了缓冲或正在跟踪索引,则此功能不适用.此函数还会将迭代器重置为其初始状态.这对于设置一个累积循环非常有用,例如.迭代器可以首先用所有维度（包括累积轴）创建,以便正确创建输出.然后,可以移除累积轴,并以嵌套方式进行计算.
警告:此函数可能会更改迭代器的内部内存布局.迭代器的任何缓存函数或指针必须重新获取!迭代器范围也将被重置.
返回
NPY_SUCCEED或NPY_FAIL.
-
int NpyIter_RemoveMultiIndex(NpyIter *iter)#
如果迭代器正在跟踪一个多索引,这将剥离对它们的支持,并在不需要多索引的情况下进行进一步的迭代器优化.此函数还将迭代器重置为其初始状态.
警告:此函数可能会更改迭代器的内部内存布局.迭代器的任何缓存函数或指针必须重新获取!
调用此函数后,:c:expr: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.
-
int NpyIter_Reset(NpyIter *iter, char **errmsg)#
将迭代器重置回其初始状态,回到迭代范围的开始.
返回
NPY_SUCCEED或NPY_FAIL.如果 errmsg 非空,当返回NPY_FAIL时不会设置 Python 异常.相反,*errmsg 会被设置为错误信息.当 errmsg 非空时,可以安全地在没有持有 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 非空,当返回NPY_FAIL时不会设置 Python 异常.相反,*errmsg 会被设置为错误信息.当 errmsg 非空时,可以安全地在没有持有 Python GIL 的情况下调用该函数.
-
int NpyIter_ResetBasePointers(NpyIter *iter, char **baseptrs, char **errmsg)#
将迭代器重置为其初始状态,但使用
baseptrs中的值作为数据,而不是使用正在迭代的数组的指针.此函数旨在与op_axes参数一起使用,由具有两个或多个迭代器的嵌套迭代代码使用.返回
NPY_SUCCEED或NPY_FAIL.如果 errmsg 非空,当返回NPY_FAIL时不会设置 Python 异常.相反,*errmsg 会被设置为错误信息.当 errmsg 非空时,可以安全地在没有持有 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(NpyIter *iter, 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操作数 PyObjects 的指针.结果指向iter,因此调用者不会获得对 PyObjects 的任何引用.
-
PyObject *NpyIter_GetIterView(NpyIter *iter, npy_intp i)#
这将返回一个对新 ndarray 视图的引用,该视图是数组中第 i 个对象的视图
NpyIter_GetOperandArray,其维度和步长与内部优化的迭代模式匹配. 此视图的 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)#
在 1.7 版本加入.
检查这是否是第一次看到迭代器指向的指定归约操作数的元素.对于归约操作数和禁用缓冲时,该函数返回一个合理的答案.对于缓冲的非归约操作数,答案可能不正确.
此函数仅用于 EXTERNAL_LOOP 模式,当该模式未启用时,会产生一些错误答案.
如果这个函数返回真,调用者还应该检查操作数的内循环步长,因为如果该步长为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,这意味着内循环可以一次性将其值加载到变量中,然后在整个循环中使用该变量,或者如果步幅等于项大小,则可以为该操作数使用连续版本.这个函数可以在不持有Python GIL的情况下安全调用.
从以前的 NumPy 迭代器转换#
旧的迭代器 API 包括 PyArrayIter_Check、PyArray_Iter* 和 PyArray_ITER_* 等函数.多迭代器数组包括 PyArray_MultiIter*、PyArray_Broadcast 和 PyArray_RemoveSmallest.新的迭代器设计用一个对象和相关的 API 取代了所有这些功能.新 API 的一个目标是,所有现有的迭代器使用都应该可以用新的迭代器替换,而无需付出太多努力.在 1.6 中,主要的例外是邻域迭代器,在这个迭代器中没有相应的功能.
以下是使用新迭代器的函数转换表:
Iterator Functions |
|
|
|
**不支持**（请改用对多个操作数的支持.） |
|
需要在Python暴露中添加这个 |
|
来自 |
|
|
|
Multi-iterator Functions |
|
来自 |
|
不支持 (总是锁定步长迭代) |
|
|
|
由 |
|
迭代器标志 |
|
Other Functions |
|
迭代器标志 |