Array iterator#

The array iterator encapsulates many of the key features in ufuncs,allowing user code to support features like output parameters,preservation of memory layouts, and buffering of data with the wrongalignment or type, without requiring difficult coding.

This page documents the API for the iterator.The iterator is namedNpyIter and functions arenamedNpyIter_*.

There is anintroductory guide to array iterationwhich may be of interest for those using this C API. In many instances,testing out ideas by creating the iterator in Python is a good ideabefore writing the C iteration code.

Iteration example#

The best way to become familiar with the iterator is to look at itsusage within the NumPy codebase itself. For example, here is a slightlytweaked version of the code forPyArray_CountNonzero, which counts thenumber of non-zero elements in an array.

npy_intpPyArray_CountNonzero(PyArrayObject*self){/* Nonzero boolean function */PyArray_NonzeroFunc*nonzero=PyArray_DESCR(self)->f->nonzero;NpyIter*iter;NpyIter_IterNextFunc*iternext;char**dataptr;npy_intpnonzero_count;npy_intp*strideptr,*innersizeptr;/* Handle zero-sized arrays specially */if(PyArray_SIZE(self)==0){return0;}/*     * 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_intpstride=*strideptr;npy_intpcount=*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);returnnonzero_count;}

Multi-iteration example#

Here is a copy function using the iterator. Theorder parameteris used to control the memory layout of the allocated result, typicallyNPY_KEEPORDER is desired.

PyObject*CopyArray(PyObject*arr,NPY_ORDERorder){NpyIter*iter;NpyIter_IterNextFunc*iternext;PyObject*op[2],*ret;npy_uint32flags;npy_uint32op_flags[2];npy_intpitemsize,*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){returnNULL;}/*     * 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_intpi;do{npy_intpsize=*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);returnNULL;}returnret;}

Multi index tracking example#

This example shows you how to work with theNPY_ITER_MULTI_INDEX flag. For simplicity, we assume the argument is a two-dimensional array.

intPrintMultiIndex(PyArrayObject*arr){NpyIter*iter;NpyIter_IterNextFunc*iternext;npy_intpmulti_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;}return0;}

When called with a 2x3 array, the above example prints:

multi_indexis[0,0]multi_indexis[0,1]multi_indexis[0,2]multi_indexis[1,0]multi_indexis[1,1]multi_indexis[1,2]

Iterator data types#

The iterator layout is an internal detail, and user code only seesan incomplete struct.

typeNpyIter#

This is an opaque pointer type for the iterator. Access to its contentscan only be done through the iterator API.

typeNpyIter_Type#

This is the type which exposes the iterator to Python. Currently, noAPI is exposed which provides access to the values of a Python-createditerator. If an iterator is created in Python, it must be used in Pythonand vice versa. Such an API will likely be created in a future version.

typeNpyIter_IterNextFunc#

This is a function pointer for the iteration loop, returned byNpyIter_GetIterNext.

typeNpyIter_GetMultiIndexFunc#

This is a function pointer for getting the current iterator multi-index,returned byNpyIter_GetGetMultiIndex.

Construction and destruction#

NpyIter*NpyIter_New(PyArrayObject*op,npy_uint32flags,NPY_ORDERorder,NPY_CASTINGcasting,PyArray_Descr*dtype)#

Creates an iterator for the given numpy array objectop.

Flags that may be passed inflags are any combinationof the global and per-operand flags documented inNpyIter_MultiNew, except forNPY_ITER_ALLOCATE.

Any of theNPY_ORDER enum values may be passed toorder. Forefficient iteration,NPY_KEEPORDER is the best option, andthe other orders enforce the particular iteration pattern.

Any of theNPY_CASTING enum values may be passed tocasting.The values includeNPY_NO_CASTING,NPY_EQUIV_CASTING,NPY_SAFE_CASTING,NPY_SAME_KIND_CASTING, andNPY_UNSAFE_CASTING. To allow the casts to occur, copying orbuffering must also be enabled.

Ifdtype isn’tNULL, then it requires that data type.If copying is allowed, it will make a temporary copy if the datais castable. IfNPY_ITER_UPDATEIFCOPY is enabled, it willalso copy the data back with another cast upon iterator destruction.

Returns NULL if there is an error, otherwise returns the allocatediterator.

To make an iterator similar to the old iterator, this should work.

iter=NpyIter_New(op,NPY_ITER_READWRITE,NPY_CORDER,NPY_NO_CASTING,NULL);

If you want to edit an array with aligneddouble code,but the order doesn’t matter, you would use this.

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_intpnop,PyArrayObject**op,npy_uint32flags,NPY_ORDERorder,NPY_CASTINGcasting,npy_uint32*op_flags,PyArray_Descr**op_dtypes)#

Creates an iterator for broadcasting thenop array objects providedinop, using regular NumPy broadcasting rules.

Any of theNPY_ORDER enum values may be passed toorder. Forefficient iteration,NPY_KEEPORDER is the best option, and theother orders enforce the particular iteration pattern. When usingNPY_KEEPORDER, if you also want to ensure that the iteration isnot reversed along an axis, you should pass the flagNPY_ITER_DONT_NEGATE_STRIDES.

Any of theNPY_CASTING enum values may be passed tocasting.The values includeNPY_NO_CASTING,NPY_EQUIV_CASTING,NPY_SAFE_CASTING,NPY_SAME_KIND_CASTING, andNPY_UNSAFE_CASTING. To allow the casts to occur, copying orbuffering must also be enabled.

Ifop_dtypes isn’tNULL, it specifies a data type orNULLfor eachop[i].

Returns NULL if there is an error, otherwise returns the allocatediterator.

Flags that may be passed inflags, applying to the wholeiterator, are:

NPY_ITER_C_INDEX#

Causes the iterator to track a raveled flat index matching Corder. This option cannot be used withNPY_ITER_F_INDEX.

NPY_ITER_F_INDEX#

Causes the iterator to track a raveled flat index matching Fortranorder. This option cannot be used withNPY_ITER_C_INDEX.

NPY_ITER_MULTI_INDEX#

Causes the iterator to track a multi-index.This prevents the iterator from coalescing axes toproduce bigger inner loops. If the loop is also not bufferedand no index is being tracked (NpyIter_RemoveAxis can be called),then the iterator size can be-1 to indicate that the iteratoris too large. This can happen due to complex broadcasting andwill result in errors being created when the setting the iteratorrange, removing the multi index, or getting the next function.However, it is possible to remove axes again and use the iteratornormally if the size is small enough after removal.

NPY_ITER_EXTERNAL_LOOP#

Causes the iterator to skip iteration of the innermostloop, requiring the user of the iterator to handle it.

This flag is incompatible withNPY_ITER_C_INDEX,NPY_ITER_F_INDEX, andNPY_ITER_MULTI_INDEX.

NPY_ITER_DONT_NEGATE_STRIDES#

This only affects the iterator whenNPY_KEEPORDER isspecified for the order parameter. By default withNPY_KEEPORDER, the iterator reverses axes which havenegative strides, so that memory is traversed in a forwarddirection. This disables this step. Use this flag if youwant to use the underlying memory-ordering of the axes,but don’t want an axis reversed. This is the behavior ofnumpy.ravel(a,order='K'), for instance.

NPY_ITER_COMMON_DTYPE#

Causes the iterator to convert all the operands to a commondata type, calculated based on the ufunc type promotion rules.Copying or buffering must be enabled.

If the common data type is known ahead of time, don’t use thisflag. Instead, set the requested dtype for all the operands.

NPY_ITER_REFS_OK#

Indicates that arrays with reference types (objectarrays or structured arrays containing an object type)may be accepted and used in the iterator. If this flagis enabled, the caller must be sure to check whetherNpyIter_IterationNeedsAPI(iter) is true, in which caseit may not release the GIL during iteration.If you are working with known dtypesNpyIter_GetTransferFlags isa faster and more precise way to check for whether the iterator needsthe API due to buffering.

NPY_ITER_ZEROSIZE_OK#

Indicates that arrays with a size of zero should be permitted.Since the typical iteration loop does not naturally work withzero-sized arrays, you must check that the IterSize is largerthan zero before entering the iteration loop.Currently only the operands are checked, not a forced shape.

NPY_ITER_REDUCE_OK#

Permits writeable operands with a dimension with zerostride and size greater than one. Note that such operandsmust be read/write.

When buffering is enabled, this also switches to a specialbuffering mode which reduces the loop length as necessary tonot trample on values being reduced.

Note that if you want to do a reduction on an automaticallyallocated output, you must useNpyIter_GetOperandArrayto get its reference, then set every value to the reductionunit before doing the iteration loop. In the case of abuffered reduction, this means you must also specify theflagNPY_ITER_DELAY_BUFALLOC, then reset the iteratorafter initializing the allocated operand to prepare thebuffers.

NPY_ITER_RANGED#

Enables support for iteration of sub-ranges of the fulliterindex range[0,NpyIter_IterSize(iter)). Usethe functionNpyIter_ResetToIterIndexRange to specifya range for iteration.

This flag can only be used withNPY_ITER_EXTERNAL_LOOPwhenNPY_ITER_BUFFERED is enabled. This is becausewithout buffering, the inner loop is always the size of theinnermost iteration dimension, and allowing it to get cut upwould require special handling, effectively making it morelike the buffered version.

NPY_ITER_BUFFERED#

Causes the iterator to store buffering data, and use bufferingto satisfy data type, alignment, and byte-order requirements.To buffer an operand, do not specify theNPY_ITER_COPYorNPY_ITER_UPDATEIFCOPY flags, because they willoverride buffering. Buffering is especially useful for Pythoncode using the iterator, allowing for larger chunksof data at once to amortize the Python interpreter overhead.

If used withNPY_ITER_EXTERNAL_LOOP, the inner loopfor the caller may get larger chunks than would be possiblewithout buffering, because of how the strides are laid out.

Note that if an operand is given the flagNPY_ITER_COPYorNPY_ITER_UPDATEIFCOPY, a copy will be made in preferenceto buffering. Buffering will still occur when the array wasbroadcast so elements need to be duplicated to get a constantstride.

In normal buffering, the size of each inner loop is equalto the buffer size, or possibly larger ifNPY_ITER_GROWINNER is specified. IfNPY_ITER_REDUCE_OK is enabled and a reduction occurs,the inner loops may become smaller dependingon the structure of the reduction.

NPY_ITER_GROWINNER#

When buffering is enabled, this allows the size of the innerloop to grow when buffering isn’t necessary. This optionis best used if you’re doing a straight pass through all thedata, rather than anything with small cache-friendly arraysof temporary values for each inner loop.

NPY_ITER_DELAY_BUFALLOC#

When buffering is enabled, this delays allocation of thebuffers untilNpyIter_Reset or another reset function iscalled. This flag exists to avoid wasteful copying ofbuffer data when making multiple copies of a bufferediterator for multi-threaded iteration.

Another use of this flag is for setting up reduction operations.After the iterator is created, and a reduction outputis allocated automatically by the iterator (be sure to useREADWRITE access), its value may be initialized to the reductionunit. UseNpyIter_GetOperandArray to get the object.Then, callNpyIter_Reset to allocate and fill the bufferswith their initial values.

NPY_ITER_COPY_IF_OVERLAP#

If any write operand has overlap with any read operand, eliminate alloverlap by making temporary copies (enabling UPDATEIFCOPY for writeoperands, if necessary). A pair of operands has overlap if there isa memory address that contains data common to both arrays.

Because exact overlap detection has exponential runtimein the number of dimensions, the decision is made basedon heuristics, which has false positives (needless copies in unusualcases) but has no false negatives.

If any read/write overlap exists, this flag ensures the result of theoperation is the same as if all operands were copied.In cases where copies would need to be made,the result of thecomputation may be undefined without this flag!

Flags that may be passed inop_flags[i], where0<=i<nop:

NPY_ITER_READWRITE#

NPY_ITER_READONLY#

NPY_ITER_WRITEONLY#

Indicate how the user of the iterator will read or writetoop[i]. Exactly one of these flags must be specifiedper operand. UsingNPY_ITER_READWRITE orNPY_ITER_WRITEONLYfor a user-provided operand may triggerWRITEBACKIFCOPYsemantics. The data will be written back to the original arraywhenNpyIter_Deallocate is called.

NPY_ITER_COPY#

Allow a copy ofop[i] to be made if it does notmeet the data type or alignment requirements as specifiedby the constructor flags and parameters.

NPY_ITER_UPDATEIFCOPY#

TriggersNPY_ITER_COPY, and when an array operandis flagged for writing and is copied, causes the datain a copy to be copied back toop[i] whenNpyIter_Deallocate is called.

If the operand is flagged as write-only and a copy is needed,an uninitialized temporary array will be created and then copiedto back toop[i] on callingNpyIter_Deallocate, instead ofdoing the unnecessary copy operation.

NPY_ITER_NBO#

NPY_ITER_ALIGNED#

NPY_ITER_CONTIG#

Causes the iterator to provide data forop[i]that is in native byte order, aligned according tothe dtype requirements, contiguous, or any combination.

By default, the iterator produces pointers into thearrays provided, which may be aligned or unaligned, andwith any byte order. If copying or buffering is notenabled and the operand data doesn’t satisfy the constraints,an error will be raised.

The contiguous constraint applies only to the inner loop,successive inner loops may have arbitrary pointer changes.

If the requested data type is in non-native byte order,the NBO flag overrides it and the requested data type isconverted to be in native byte order.

NPY_ITER_ALLOCATE#

This is for output arrays, and requires that the flagNPY_ITER_WRITEONLY orNPY_ITER_READWRITEbe set. Ifop[i] is NULL, creates a new array withthe final broadcast dimensions, and a layout matchingthe iteration order of the iterator.

Whenop[i] is NULL, the requested data typeop_dtypes[i] may be NULL as well, in which case it isautomatically generated from the dtypes of the arrays whichare flagged as readable. The rules for generating the dtypeare the same is for UFuncs. Of special note is handlingof byte order in the selected dtype. If there is exactlyone input, the input’s dtype is used as is. Otherwise,if more than one input dtypes are combined together, theoutput will be in native byte order.

After being allocated with this flag, the caller may retrievethe new array by callingNpyIter_GetOperandArray andgetting the i-th object in the returned C array. The callermust call Py_INCREF on it to claim a reference to the array.

NPY_ITER_NO_SUBTYPE#

For use withNPY_ITER_ALLOCATE, this flag disablesallocating an array subtype for the output, forcingit to be a straight ndarray.

TODO: Maybe it would be better to introduce a functionNpyIter_GetWrappedOutput and remove this flag?

NPY_ITER_NO_BROADCAST#

Ensures that the input or output matches the iterationdimensions exactly.

NPY_ITER_ARRAYMASK#

Indicates that this operand is the mask to use forselecting elements when writing to operands which havetheNPY_ITER_WRITEMASKED flag applied to them.Only one operand may haveNPY_ITER_ARRAYMASK flagapplied to it.

The data type of an operand with this flag should be eitherNPY_BOOL,NPY_MASK, or a struct dtypewhose fields are all valid mask dtypes. In the latter case,it must match up with a struct operand being WRITEMASKED,as it is specifying a mask for each field of that array.

This flag only affects writing from the buffer back tothe array. This means that if the operand is alsoNPY_ITER_READWRITE orNPY_ITER_WRITEONLY,code doing iteration can write to this operand tocontrol which elements will be untouched and which ones will bemodified. This is useful when the mask should be a combinationof input masks.

NPY_ITER_WRITEMASKED#

This array is the mask for allwritemaskedoperands. Code uses thewritemasked flag which indicatesthat only elements where the chosen ARRAYMASK operand is Truewill be written to. In general, the iterator does not enforcethis, it is up to the code doing the iteration to follow thatpromise.

Whenwritemasked flag is used, and this operand is buffered,this changes how data is copied from the buffer into the array.A masked copying routine is used, which only copies theelements in the buffer for whichwritemaskedreturns true from the corresponding element in the ARRAYMASKoperand.

NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE#

In memory overlap checks, assume that operands withNPY_ITER_OVERLAP_ASSUME_ELEMENTWISE enabled are accessed onlyin the iterator order.

This enables the iterator to reason about data dependency,possibly avoiding unnecessary copies.

This flag has effect only ifNPY_ITER_COPY_IF_OVERLAP is enabledon the iterator.

NpyIter*NpyIter_AdvancedNew(npy_intpnop,PyArrayObject**op,npy_uint32flags,NPY_ORDERorder,NPY_CASTINGcasting,npy_uint32*op_flags,PyArray_Descr**op_dtypes,intoa_ndim,int**op_axes,npy_intpconst*itershape,npy_intpbuffersize)#

ExtendsNpyIter_MultiNew with several advanced options providingmore control over broadcasting and buffering.

If -1/NULL values are passed tooa_ndim,op_axes,itershape,andbuffersize, it is equivalent toNpyIter_MultiNew.

The parameteroa_ndim, when not zero or -1, specifies the number ofdimensions that will be iterated with customized broadcasting.If it is provided,op_axes must anditershape can also be provided.Theop_axes parameter let you control in detail how theaxes of the operand arrays get matched together and iterated.Inop_axes, you must provide an array ofnop pointerstooa_ndim-sized arrays of typenpy_intp. If an entryinop_axes is NULL, normal broadcasting rules will apply.Inop_axes[j][i] is stored either a valid axis ofop[j], or-1 which meansnewaxis. Within eachop_axes[j] array, axesmay not be repeated. The following example is how normal broadcastingapplies to a 3-D array, a 2-D array, a 1-D array and a scalar.

Note: Before NumPy 1.8oa_ndim==0 was used for signallingthatop_axes anditershape are unused. This is deprecated andshould be replaced with -1. Better backward compatibility may beachieved by usingNpyIter_MultiNew for this case.

intoa_ndim=3;/* # iteration axes */intop0_axes[]={0,1,2};/* 3-D operand */intop1_axes[]={-1,0,1};/* 2-D operand */intop2_axes[]={-1,-1,0};/* 1-D operand */intop3_axes[]={-1,-1,-1}/* 0-D (scalar) operand */int*op_axes[]={op0_axes,op1_axes,op2_axes,op3_axes};

Theitershape parameter allows you to force the iteratorto have a specific iteration shape. It is an array of lengthoa_ndim. When an entry is negative, its value is determinedfrom the operands. This parameter allows automatically allocatedoutputs to get additional dimensions which don’t match up withany dimension of an input.

Ifbuffersize is zero, a default buffer size is used,otherwise it specifies how big of a buffer to use. Bufferswhich are powers of 2 such as 4096 or 8192 are recommended.

Returns NULL if there is an error, otherwise returns the allocatediterator.

NpyIter*NpyIter_Copy(NpyIter*iter)#

Makes a copy of the given iterator. This function is providedprimarily to enable multi-threaded iteration of the data.

TODO: Move this to a section about multithreaded iteration.

The recommended approach to multithreaded iteration is tofirst create an iterator with the flagsNPY_ITER_EXTERNAL_LOOP,NPY_ITER_RANGED,NPY_ITER_BUFFERED,NPY_ITER_DELAY_BUFALLOC, andpossiblyNPY_ITER_GROWINNER. Create a copy of this iteratorfor each thread (minus one for the first iterator). Then, takethe iteration index range[0,NpyIter_GetIterSize(iter)) andsplit it up into tasks, for example using a TBB parallel_for loop.When a thread gets a task to execute, it then uses its copy ofthe iterator by callingNpyIter_ResetToIterIndexRange anditerating over the full range.

When using the iterator in multi-threaded code or in code notholding the Python GIL, care must be taken to only call functionswhich are safe in that context.NpyIter_Copy cannot be safelycalled without the Python GIL, because it increments Pythonreferences. TheReset* and some other functions may be safelycalled by passing in theerrmsg parameter as non-NULL, so thatthe functions will pass back errors through it instead of settinga Python exception.

NpyIter_Deallocate must be called for each copy.

intNpyIter_RemoveAxis(NpyIter*iter,intaxis)#

Removes an axis from iteration. This requires thatNPY_ITER_MULTI_INDEX was set for iterator creation, and doesnot work if buffering is enabled or an index is being tracked. Thisfunction also resets the iterator to its initial state.

This is useful for setting up an accumulation loop, for example.The iterator can first be created with all the dimensions, includingthe accumulation axis, so that the output gets created correctly.Then, the accumulation axis can be removed, and the calculationdone in a nested fashion.

WARNING: This function may change the internal memory layout ofthe iterator. Any cached functions or pointers from the iteratormust be retrieved again! The iterator range will be reset as well.

ReturnsNPY_SUCCEED orNPY_FAIL.

intNpyIter_RemoveMultiIndex(NpyIter*iter)#

If the iterator is tracking a multi-index, this strips support for them,and does further iterator optimizations that are possible if multi-indicesare not needed. This function also resets the iterator to its initialstate.

WARNING: This function may change the internal memory layout ofthe iterator. Any cached functions or pointers from the iteratormust be retrieved again!

After calling this function,NpyIter_HasMultiIndex(iter) willreturn false.

ReturnsNPY_SUCCEED orNPY_FAIL.

intNpyIter_EnableExternalLoop(NpyIter*iter)#

IfNpyIter_RemoveMultiIndex was called, you may want to enable theflagNPY_ITER_EXTERNAL_LOOP. This flag is not permittedtogether withNPY_ITER_MULTI_INDEX, so this function is providedto enable the feature afterNpyIter_RemoveMultiIndex is called.This function also resets the iterator to its initial state.

WARNING: This function changes the internal logic of the iterator.Any cached functions or pointers from the iterator must be retrievedagain!

ReturnsNPY_SUCCEED orNPY_FAIL.

intNpyIter_Deallocate(NpyIter*iter)#

Deallocates the iterator object and resolves any needed writebacks.

ReturnsNPY_SUCCEED orNPY_FAIL.

NPY_ARRAYMETHOD_FLAGSNpyIter_GetTransferFlags(NpyIter*iter)#

New in version 2.3.

Fetches theNPY_METH_RUNTIME_FLAGS which provide the information onwhether buffering needs the Python GIL (NPY_METH_REQUIRES_PYAPI) orfloating point errors may be set (NPY_METH_NO_FLOATINGPOINT_ERRORS).

Prior to NumPy 2.3, the public function available wasNpyIter_IterationNeedsAPI, which is still available and additionallychecks for object (or similar) dtypes and not exclusively forbuffering/iteration needs itself.In general, this function should be preferred.

intNpyIter_Reset(NpyIter*iter,char**errmsg)#

Resets the iterator back to its initial state, at the beginningof the iteration range.

ReturnsNPY_SUCCEED orNPY_FAIL. If errmsg is non-NULL,no Python exception is set whenNPY_FAIL is returned.Instead, *errmsg is set to an error message. When errmsg isnon-NULL, the function may be safely called without holdingthe Python GIL.

intNpyIter_ResetToIterIndexRange(NpyIter*iter,npy_intpistart,npy_intpiend,char**errmsg)#

Resets the iterator and restricts it to theiterindex range[istart,iend). SeeNpyIter_Copy for an explanation ofhow to use this for multi-threaded iteration. This requires thatthe flagNPY_ITER_RANGED was passed to the iterator constructor.

If you want to reset both theiterindex range and the basepointers at the same time, you can do the following to avoidextra buffer copying (be sure to add the return code error checkswhen you copy this code).

/* 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);

ReturnsNPY_SUCCEED orNPY_FAIL. If errmsg is non-NULL,no Python exception is set whenNPY_FAIL is returned.Instead, *errmsg is set to an error message. When errmsg isnon-NULL, the function may be safely called without holdingthe Python GIL.

intNpyIter_ResetBasePointers(NpyIter*iter,char**baseptrs,char**errmsg)#

Resets the iterator back to its initial state, but using the valuesinbaseptrs for the data instead of the pointers from the arraysbeing iterated. This functions is intended to be used, together withtheop_axes parameter, by nested iteration code with two or moreiterators.

ReturnsNPY_SUCCEED orNPY_FAIL. If errmsg is non-NULL,no Python exception is set whenNPY_FAIL is returned.Instead, *errmsg is set to an error message. When errmsg isnon-NULL, the function may be safely called without holdingthe Python GIL.

TODO: Move the following into a special section on nested iterators.

Creating iterators for nested iteration requires some care. Allthe iterator operands must match exactly, or the calls toNpyIter_ResetBasePointers will be invalid. This means thatautomatic copies and output allocation should not be used haphazardly.It is possible to still use the automatic data conversion and castingfeatures of the iterator by creating one of the iterators withall the conversion parameters enabled, then grabbing the allocatedoperands with theNpyIter_GetOperandArray function and passingthem into the constructors for the rest of the iterators.

WARNING: When creating iterators for nested iteration,the code must not use a dimension more than once in the differentiterators. If this is done, nested iteration will produceout-of-bounds pointers during iteration.

WARNING: When creating iterators for nested iteration, bufferingcan only be applied to the innermost iterator. If a buffered iteratoris used as the source forbaseptrs, it will point into a small bufferinstead of the array and the inner iteration will be invalid.

The pattern for using nested iterators is as follows.

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));

intNpyIter_GotoMultiIndex(NpyIter*iter,npy_intpconst*multi_index)#

Adjusts the iterator to point to thendim indicespointed to bymulti_index. Returns an error if a multi-indexis not being tracked, the indices are out of bounds,or inner loop iteration is disabled.

ReturnsNPY_SUCCEED orNPY_FAIL.

intNpyIter_GotoIndex(NpyIter*iter,npy_intpindex)#

Adjusts the iterator to point to theindex specified.If the iterator was constructed with the flagNPY_ITER_C_INDEX,index is the C-order index,and if the iterator was constructed with the flagNPY_ITER_F_INDEX,index is the Fortran-orderindex. Returns an error if there is no index being tracked,the index is out of bounds, or inner loop iteration is disabled.

ReturnsNPY_SUCCEED orNPY_FAIL.

npy_intpNpyIter_GetIterSize(NpyIter*iter)#

Returns the number of elements being iterated. This is the productof all the dimensions in the shape. When a multi index is being tracked(andNpyIter_RemoveAxis may be called) the size may be-1 toindicate an iterator is too large. Such an iterator is invalid, butmay become valid afterNpyIter_RemoveAxis is called. It is notnecessary to check for this case.

npy_intpNpyIter_GetIterIndex(NpyIter*iter)#

Gets theiterindex of the iterator, which is an index matchingthe iteration order of the iterator.

voidNpyIter_GetIterIndexRange(NpyIter*iter,npy_intp*istart,npy_intp*iend)#

Gets theiterindex sub-range that is being iterated. IfNPY_ITER_RANGED was not specified, this always returns therange[0,NpyIter_IterSize(iter)).

intNpyIter_GotoIterIndex(NpyIter*iter,npy_intpiterindex)#

Adjusts the iterator to point to theiterindex specified.The IterIndex is an index matching the iteration order of the iterator.Returns an error if theiterindex is out of bounds,buffering is enabled, or inner loop iteration is disabled.

ReturnsNPY_SUCCEED orNPY_FAIL.

npy_boolNpyIter_HasDelayedBufAlloc(NpyIter*iter)#

Returns 1 if the flagNPY_ITER_DELAY_BUFALLOC was passedto the iterator constructor, and no call to one of the Resetfunctions has been done yet, 0 otherwise.

npy_boolNpyIter_HasExternalLoop(NpyIter*iter)#

Returns 1 if the caller needs to handle the inner-most 1-dimensionalloop, or 0 if the iterator handles all looping. This is controlledby the constructor flagNPY_ITER_EXTERNAL_LOOP orNpyIter_EnableExternalLoop.

npy_boolNpyIter_HasMultiIndex(NpyIter*iter)#

Returns 1 if the iterator was created with theNPY_ITER_MULTI_INDEX flag, 0 otherwise.

npy_boolNpyIter_HasIndex(NpyIter*iter)#

Returns 1 if the iterator was created with theNPY_ITER_C_INDEX orNPY_ITER_F_INDEXflag, 0 otherwise.

npy_boolNpyIter_RequiresBuffering(NpyIter*iter)#

Returns 1 if the iterator requires buffering, which occurswhen an operand needs conversion or alignment and so cannotbe used directly.

npy_boolNpyIter_IsBuffered(NpyIter*iter)#

Returns 1 if the iterator was created with theNPY_ITER_BUFFERED flag, 0 otherwise.

npy_boolNpyIter_IsGrowInner(NpyIter*iter)#

Returns 1 if the iterator was created with theNPY_ITER_GROWINNER flag, 0 otherwise.

npy_intpNpyIter_GetBufferSize(NpyIter*iter)#

If the iterator is buffered, returns the size of the bufferbeing used, otherwise returns 0.

intNpyIter_GetNDim(NpyIter*iter)#

Returns the number of dimensions being iterated. If a multi-indexwas not requested in the iterator constructor, this valuemay be smaller than the number of dimensions in the originalobjects.

intNpyIter_GetNOp(NpyIter*iter)#

Returns the number of operands in the iterator.

npy_intp*NpyIter_GetAxisStrideArray(NpyIter*iter,intaxis)#

Gets the array of strides for the specified axis. Requires thatthe iterator be tracking a multi-index, and that buffering notbe enabled.

This may be used when you want to match up operand axes insome fashion, then remove them withNpyIter_RemoveAxis tohandle their processing manually. By calling this functionbefore removing the axes, you can get the strides for themanual processing.

ReturnsNULL on error.

intNpyIter_GetShape(NpyIter*iter,npy_intp*outshape)#

Returns the broadcast shape of the iterator inoutshape.This can only be called on an iterator which is tracking a multi-index.

ReturnsNPY_SUCCEED orNPY_FAIL.

PyArray_Descr**NpyIter_GetDescrArray(NpyIter*iter)#

This gives back a pointer to thenop data type Descrs forthe objects being iterated. The result points intoiter,so the caller does not gain any references to the Descrs.

This pointer may be cached before the iteration loop, callingiternext will not change it.

PyObject**NpyIter_GetOperandArray(NpyIter*iter)#

This gives back a pointer to thenop operand PyObjectsthat are being iterated. The result points intoiter,so the caller does not gain any references to the PyObjects.

PyObject*NpyIter_GetIterView(NpyIter*iter,npy_intpi)#

This gives back a reference to a new ndarray view, which is a viewinto the i-th object in the arrayNpyIter_GetOperandArray,whose dimensions and strides match the internal optimizediteration pattern. A C-order iteration of this view is equivalentto the iterator’s iteration order.

For example, if an iterator was created with a single array as itsinput, and it was possible to rearrange all its axes and thencollapse it into a single strided iteration, this would returna view that is a one-dimensional array.

voidNpyIter_GetReadFlags(NpyIter*iter,char*outreadflags)#

Fillsnop flags. Setsoutreadflags[i] to 1 ifop[i] can be read from, and to 0 if not.

voidNpyIter_GetWriteFlags(NpyIter*iter,char*outwriteflags)#

Fillsnop flags. Setsoutwriteflags[i] to 1 ifop[i] can be written to, and to 0 if not.

intNpyIter_CreateCompatibleStrides(NpyIter*iter,npy_intpitemsize,npy_intp*outstrides)#

Builds a set of strides which are the same as the strides of anoutput array created using theNPY_ITER_ALLOCATE flag, where NULLwas passed for op_axes. This is for data packed contiguously,but not necessarily in C or Fortran order. This should be usedtogether withNpyIter_GetShape andNpyIter_GetNDimwith the flagNPY_ITER_MULTI_INDEX passed into the constructor.

A use case for this function is to match the shape and layout ofthe iterator and tack on one or more dimensions. For example,in order to generate a vector per input value for a numerical gradient,you pass in ndim*itemsize for itemsize, then add another dimension tothe end with size ndim and stride itemsize. To do the Hessian matrix,you do the same thing but add two dimensions, or take advantage ofthe symmetry and pack it into 1 dimension with a particular encoding.

This function may only be called if the iterator is tracking a multi-indexand ifNPY_ITER_DONT_NEGATE_STRIDES was used to prevent an axisfrom being iterated in reverse order.

If an array is created with this method, simply adding ‘itemsize’for each iteration will traverse the new array matching theiterator.

ReturnsNPY_SUCCEED orNPY_FAIL.

npy_boolNpyIter_IsFirstVisit(NpyIter*iter,intiop)#

Checks to see whether this is the first time the elements of thespecified reduction operand which the iterator points at are beingseen for the first time. The function returns a reasonable answerfor reduction operands and when buffering is disabled. The answermay be incorrect for buffered non-reduction operands.

This function is intended to be used in EXTERNAL_LOOP mode only,and will produce some wrong answers when that mode is not enabled.

If this function returns true, the caller should also check the innerloop stride of the operand, because if that stride is 0, then onlythe first element of the innermost external loop is being visitedfor the first time.

WARNING: For performance reasons, ‘iop’ is not bounds-checked,it is not confirmed that ‘iop’ is actually a reduction operand,and it is not confirmed that EXTERNAL_LOOP mode is enabled. Thesechecks are the responsibility of the caller, and should be doneoutside of any inner loops.

Functions for iteration#

NpyIter_IterNextFunc*NpyIter_GetIterNext(NpyIter*iter,char**errmsg)#

Returns a function pointer for iteration. A specialized versionof the function pointer may be calculated by this functioninstead of being stored in the iterator structure. Thus, toget good performance, it is required that the function pointerbe saved in a variable rather than retrieved for each loop iteration.

Returns NULL if there is an error. If errmsg is non-NULL,no Python exception is set whenNPY_FAIL is returned.Instead, *errmsg is set to an error message. When errmsg isnon-NULL, the function may be safely called without holdingthe Python GIL.

The typical looping construct is as follows.

NpyIter_IterNextFunc*iternext=NpyIter_GetIterNext(iter,NULL);char**dataptr=NpyIter_GetDataPtrArray(iter);do{/* use the addresses dataptr[0], ... dataptr[nop-1] */}while(iternext(iter));

WhenNPY_ITER_EXTERNAL_LOOP is specified, the typicalinner loop construct is as follows.

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_intpiop,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());

Observe that we are using the dataptr array inside the iterator, notcopying the values to a local temporary. This is possible becausewheniternext() is called, these pointers will be overwrittenwith fresh values, not incrementally updated.

If a compile-time fixed buffer is being used (both flagsNPY_ITER_BUFFERED andNPY_ITER_EXTERNAL_LOOP), theinner size may be used as a signal as well. The size is guaranteedto become zero wheniternext() returns false, enabling thefollowing loop construct. Note that if you use this construct,you should not passNPY_ITER_GROWINNER as a flag, because itwill cause larger sizes under some circumstances.

/* The constructor should have buffersize passed as this value */#define FIXED_BUFFER_SIZE 1024NpyIter_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_intpi,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)#

Returns a function pointer for getting the current multi-indexof the iterator. Returns NULL if the iterator is not trackinga multi-index. It is recommended that this functionpointer be cached in a local variable before the iterationloop.

Returns NULL if there is an error. If errmsg is non-NULL,no Python exception is set whenNPY_FAIL is returned.Instead, *errmsg is set to an error message. When errmsg isnon-NULL, the function may be safely called without holdingthe Python GIL.

char**NpyIter_GetDataPtrArray(NpyIter*iter)#

This gives back a pointer to thenop data pointers. IfNPY_ITER_EXTERNAL_LOOP was not specified, each datapointer points to the current data item of the iterator. Ifno inner iteration was specified, it points to the first dataitem of the inner loop.

This pointer may be cached before the iteration loop, callingiternext will not change it. This function may be safelycalled without holding the Python GIL.

char**NpyIter_GetInitialDataPtrArray(NpyIter*iter)#

Gets the array of data pointers directly into the arrays (neverinto the buffers), corresponding to iteration index 0.

These pointers are different from the pointers accepted byNpyIter_ResetBasePointers, because the direction alongsome axes may have been reversed.

This function may be safely called without holding the Python GIL.

npy_intp*NpyIter_GetIndexPtr(NpyIter*iter)#

This gives back a pointer to the index being tracked, or NULLif no index is being tracked. It is only usable if one ofthe flagsNPY_ITER_C_INDEX orNPY_ITER_F_INDEXwere specified during construction.

When the flagNPY_ITER_EXTERNAL_LOOP is used, the codeneeds to know the parameters for doing the inner loop. Thesefunctions provide that information.

npy_intp*NpyIter_GetInnerStrideArray(NpyIter*iter)#

Returns a pointer to an array of thenop strides,one for each iterated object, to be used by the inner loop.

This pointer may be cached before the iteration loop, callingiternext will not change it. This function may be safelycalled without holding the Python GIL.

WARNING: While the pointer may be cached, its values maychange if the iterator is buffered.

npy_intp*NpyIter_GetInnerLoopSizePtr(NpyIter*iter)#

Returns a pointer to the number of iterations theinner loop should execute.

This address may be cached before the iteration loop, callingiternext will not change it. The value itself may change duringiteration, in particular if buffering is enabled. This functionmay be safely called without holding the Python GIL.

voidNpyIter_GetInnerFixedStrideArray(NpyIter*iter,npy_intp*out_strides)#

Gets an array of strides which are fixed, or will not change duringthe entire iteration. For strides that may change, the valueNPY_MAX_INTP is placed in the stride.

Once the iterator is prepared for iteration (after a reset ifNPY_ITER_DELAY_BUFALLOC was used), call this to get the strideswhich may be used to select a fast inner loop function. For example,if the stride is 0, that means the inner loop can always load itsvalue into a variable once, then use the variable throughout the loop,or if the stride equals the itemsize, a contiguous version for thatoperand may be used.

This function may be safely called without holding the Python GIL.

Converting from previous NumPy iterators#

The old iterator API includes functions like PyArrayIter_Check,PyArray_Iter* and PyArray_ITER_*. The multi-iterator array includesPyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest. Thenew iterator design replaces all of this functionality with a single objectand associated API. One goal of the new API is that all uses of theexisting iterator should be replaceable with the new iterator withoutsignificant effort. In 1.6, the major exception to this is the neighborhooditerator, which does not have corresponding features in this iterator.

Here is a conversion table for which functions to use with the new iterator: