{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:c-api:iterator", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array iterator API" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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 wrong alignment or type, without requiring difficult coding." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This page documents the API for the iterator. The iterator is named " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter" }, { "__type": "Text", "__tag": 4046, "value": " and functions are named " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_*" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There is an " }, { "__type": "CrossRef", "__tag": 4002, "value": "introductory guide to array iteration", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.nditer" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " which 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 idea before writing the C iteration code." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array iterator" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The best way to become familiar with the iterator is to look at its usage within the NumPy codebase itself. For example, here is a slightly tweaked version of the code for " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CountNonzero" }, { "__type": "Text", "__tag": 4046, "value": ", which counts the number of non-zero elements in an array." } ] }, { "__type": "Code", "__tag": 4050, "value": "npy_intp PyArray_CountNonzero(PyArrayObject* self)\n{\n /* Nonzero boolean function */\n PyArray_NonzeroFunc* nonzero = PyArray_DESCR(self)->f->nonzero;\n\n NpyIter* iter;\n NpyIter_IterNextFunc *iternext;\n char** dataptr;\n npy_intp nonzero_count;\n npy_intp* strideptr,* innersizeptr;\n\n /* Handle zero-sized arrays specially */\n if (PyArray_SIZE(self) == 0) {\n return 0;\n }\n\n /*\n * Create and use an iterator to count the nonzeros.\n * flag NPY_ITER_READONLY\n * - The array is never written to.\n * flag NPY_ITER_EXTERNAL_LOOP\n * - Inner loop is done outside the iterator for efficiency.\n * flag NPY_ITER_NPY_ITER_REFS_OK\n * - Reference types are acceptable.\n * order NPY_KEEPORDER\n * - Visit elements in memory order, regardless of strides.\n * This is good for performance when the specific order\n * elements are visited is unimportant.\n * casting NPY_NO_CASTING\n * - No casting is required for this operation.\n */\n iter = NpyIter_New(self, NPY_ITER_READONLY|\n NPY_ITER_EXTERNAL_LOOP|\n NPY_ITER_REFS_OK,\n NPY_KEEPORDER, NPY_NO_CASTING,\n NULL);\n if (iter == NULL) {\n return -1;\n }\n\n /*\n * The iternext function gets stored in a local variable\n * so it can be called repeatedly in an efficient manner.\n */\n iternext = NpyIter_GetIterNext(iter, NULL);\n if (iternext == NULL) {\n NpyIter_Deallocate(iter);\n return -1;\n }\n /* The location of the data pointer which the iterator may update */\n dataptr = NpyIter_GetDataPtrArray(iter);\n /* The location of the stride which the iterator may update */\n strideptr = NpyIter_GetInnerStrideArray(iter);\n /* The location of the inner loop size which the iterator may update */\n innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);\n\n nonzero_count = 0;\n do {\n /* Get the inner loop data/stride/count values */\n char* data = *dataptr;\n npy_intp stride = *strideptr;\n npy_intp count = *innersizeptr;\n\n /* This is a typical inner loop for NPY_ITER_EXTERNAL_LOOP */\n while (count--) {\n if (nonzero(data, self)) {\n ++nonzero_count;\n }\n data += stride;\n }\n\n /* Increment the iterator to the next inner loop */\n } while(iternext(iter));\n\n NpyIter_Deallocate(iter);\n\n return nonzero_count;\n}", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Iteration example" } ], "level": 1, "target": "iteration-example" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Here is a copy function using the iterator. The " }, { "__type": "InlineCode", "__tag": 4051, "value": "order" }, { "__type": "Text", "__tag": 4046, "value": " parameter is used to control the memory layout of the allocated result, typically " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": " is desired." } ] }, { "__type": "Code", "__tag": 4050, "value": "PyObject *CopyArray(PyObject *arr, NPY_ORDER order)\n{\n NpyIter *iter;\n NpyIter_IterNextFunc *iternext;\n PyObject *op[2], *ret;\n npy_uint32 flags;\n npy_uint32 op_flags[2];\n npy_intp itemsize, *innersizeptr, innerstride;\n char **dataptrarray;\n\n /*\n * No inner iteration - inner loop is handled by CopyArray code\n */\n flags = NPY_ITER_EXTERNAL_LOOP;\n /*\n * Tell the constructor to automatically allocate the output.\n * The data type of the output will match that of the input.\n */\n op[0] = arr;\n op[1] = NULL;\n op_flags[0] = NPY_ITER_READONLY;\n op_flags[1] = NPY_ITER_WRITEONLY | NPY_ITER_ALLOCATE;\n\n /* Construct the iterator */\n iter = NpyIter_MultiNew(2, op, flags, order, NPY_NO_CASTING,\n op_flags, NULL);\n if (iter == NULL) {\n return NULL;\n }\n\n /*\n * Make a copy of the iternext function pointer and\n * a few other variables the inner loop needs.\n */\n iternext = NpyIter_GetIterNext(iter, NULL);\n innerstride = NpyIter_GetInnerStrideArray(iter)[0];\n itemsize = NpyIter_GetDescrArray(iter)[0]->elsize;\n /*\n * The inner loop size and data pointers may change during the\n * loop, so just cache the addresses.\n */\n innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);\n dataptrarray = NpyIter_GetDataPtrArray(iter);\n\n /*\n * Note that because the iterator allocated the output,\n * it matches the iteration order and is packed tightly,\n * so we don't need to check it like the input.\n */\n if (innerstride == itemsize) {\n do {\n memcpy(dataptrarray[1], dataptrarray[0],\n itemsize * (*innersizeptr));\n } while (iternext(iter));\n } else {\n /* For efficiency, should specialize this based on item size... */\n npy_intp i;\n do {\n npy_intp size = *innersizeptr;\n char *src = dataptrarray[0], *dst = dataptrarray[1];\n for(i = 0; i < size; i++, src += innerstride, dst += itemsize) {\n memcpy(dst, src, itemsize);\n }\n } while (iternext(iter));\n }\n\n /* Get the result from the iterator object array */\n ret = NpyIter_GetOperandArray(iter)[1];\n Py_INCREF(ret);\n\n if (NpyIter_Deallocate(iter) != NPY_SUCCEED) {\n Py_DECREF(ret);\n return NULL;\n }\n\n return ret;\n}", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Multi-iteration example" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This example shows you how to work with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_MULTI_INDEX" }, { "__type": "Text", "__tag": 4046, "value": " flag. For simplicity, we assume the argument is a two-dimensional array." } ] }, { "__type": "Code", "__tag": 4050, "value": "int PrintMultiIndex(PyArrayObject *arr) {\n NpyIter *iter;\n NpyIter_IterNextFunc *iternext;\n npy_intp multi_index[2];\n\n iter = NpyIter_New(\n arr, NPY_ITER_READONLY | NPY_ITER_MULTI_INDEX | NPY_ITER_REFS_OK,\n NPY_KEEPORDER, NPY_NO_CASTING, NULL);\n if (iter == NULL) {\n return -1;\n }\n if (NpyIter_GetNDim(iter) != 2) {\n NpyIter_Deallocate(iter);\n PyErr_SetString(PyExc_ValueError, \"Array must be 2-D\");\n return -1;\n }\n if (NpyIter_GetIterSize(iter) != 0) {\n iternext = NpyIter_GetIterNext(iter, NULL);\n if (iternext == NULL) {\n NpyIter_Deallocate(iter);\n return -1;\n }\n NpyIter_GetMultiIndexFunc *get_multi_index =\n NpyIter_GetGetMultiIndex(iter, NULL);\n if (get_multi_index == NULL) {\n NpyIter_Deallocate(iter);\n return -1;\n }\n\n do {\n get_multi_index(iter, multi_index);\n printf(\"multi_index is [%\" NPY_INTP_FMT \", %\" NPY_INTP_FMT \"]\\n\",\n multi_index[0], multi_index[1]);\n } while (iternext(iter));\n }\n if (!NpyIter_Deallocate(iter)) {\n return -1;\n }\n return 0;\n}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When called with a 2x3 array, the above example prints:" } ] }, { "__type": "Code", "__tag": 4050, "value": "multi_index is [0, 0]\nmulti_index is [0, 1]\nmulti_index is [0, 2]\nmulti_index is [1, 0]\nmulti_index is [1, 1]\nmulti_index is [1, 2]", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Multi index tracking example" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The iterator layout is an internal detail, and user code only sees an incomplete struct." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Iterator data types" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Creates an iterator for the given numpy array object " }, { "__type": "InlineCode", "__tag": 4051, "value": "op" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flags that may be passed in " }, { "__type": "InlineCode", "__tag": 4051, "value": "flags" }, { "__type": "Text", "__tag": 4046, "value": " are any combination of the global and per-operand flags documented in " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_MultiNew" }, { "__type": "Text", "__tag": 4046, "value": ", except for " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_ALLOCATE" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ORDER" }, { "__type": "Text", "__tag": 4046, "value": " enum values may be passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "order" }, { "__type": "Text", "__tag": 4046, "value": ". For efficient iteration, " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": " is the best option, and the other orders enforce the particular iteration pattern." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CASTING" }, { "__type": "Text", "__tag": 4046, "value": " enum values may be passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "casting" }, { "__type": "Text", "__tag": 4046, "value": ". The values include " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NO_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_EQUIV_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAME_KIND_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_UNSAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ". To allow the casts to occur, copying or buffering must also be enabled." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": " isn't " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then it requires that data type. If copying is allowed, it will make a temporary copy if the data is castable. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_UPDATEIFCOPY" }, { "__type": "Text", "__tag": 4046, "value": " is enabled, it will also copy the data back with another cast upon iterator destruction." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns NULL if there is an error, otherwise returns the allocated iterator." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To make an iterator similar to the old iterator, this should work." } ] }, { "__type": "Code", "__tag": 4050, "value": "iter = NpyIter_New(op, NPY_ITER_READWRITE,\n NPY_CORDER, NPY_NO_CASTING, NULL);", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you want to edit an array with aligned " }, { "__type": "InlineCode", "__tag": 4051, "value": "double" }, { "__type": "Text", "__tag": 4046, "value": " code, but the order doesn't matter, you would use this." } ] }, { "__type": "Code", "__tag": 4050, "value": "dtype = PyArray_DescrFromType(NPY_DOUBLE);\n iter = NpyIter_New(op, NPY_ITER_READWRITE|\n NPY_ITER_BUFFERED|\n NPY_ITER_NBO|\n NPY_ITER_ALIGNED,\n NPY_KEEPORDER,\n NPY_SAME_KIND_CASTING,\n dtype);\n Py_DECREF(dtype);", "execution_status": null } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Creates an iterator for broadcasting the " }, { "__type": "InlineCode", "__tag": 4051, "value": "nop" }, { "__type": "Text", "__tag": 4046, "value": " array objects provided in " }, { "__type": "InlineCode", "__tag": 4051, "value": "op" }, { "__type": "Text", "__tag": 4046, "value": ", using regular NumPy broadcasting rules." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ORDER" }, { "__type": "Text", "__tag": 4046, "value": " enum values may be passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "order" }, { "__type": "Text", "__tag": 4046, "value": ". For efficient iteration, " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": " is the best option, and the other orders enforce the particular iteration pattern. When using " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": ", if you also want to ensure that the iteration is not reversed along an axis, you should pass the flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_DONT_NEGATE_STRIDES" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CASTING" }, { "__type": "Text", "__tag": 4046, "value": " enum values may be passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "casting" }, { "__type": "Text", "__tag": 4046, "value": ". The values include " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NO_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_EQUIV_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAME_KIND_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_UNSAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ". To allow the casts to occur, copying or buffering must also be enabled." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_dtypes" }, { "__type": "Text", "__tag": 4046, "value": " isn't " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", it specifies a data type or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " for each " }, { "__type": "InlineCode", "__tag": 4051, "value": "op[i]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns NULL if there is an error, otherwise returns the allocated iterator." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flags that may be passed in " }, { "__type": "InlineCode", "__tag": 4051, "value": "flags" }, { "__type": "Text", "__tag": 4046, "value": ", applying to the whole iterator, are:" } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extends " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_MultiNew" }, { "__type": "Text", "__tag": 4046, "value": " with several advanced options providing more control over broadcasting and buffering." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If -1/NULL values are passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "oa_ndim" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "itershape" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "buffersize" }, { "__type": "Text", "__tag": 4046, "value": ", it is equivalent to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_MultiNew" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The parameter " }, { "__type": "InlineCode", "__tag": 4051, "value": "oa_ndim" }, { "__type": "Text", "__tag": 4046, "value": ", when not zero or -1, specifies the number of dimensions that will be iterated with customized broadcasting. If it is provided, " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": " must and " }, { "__type": "InlineCode", "__tag": 4051, "value": "itershape" }, { "__type": "Text", "__tag": 4046, "value": " can also be provided. The " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": " parameter let you control in detail how the axes of the operand arrays get matched together and iterated. In " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": ", you must provide an array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "nop" }, { "__type": "Text", "__tag": 4046, "value": " pointers to " }, { "__type": "InlineCode", "__tag": 4051, "value": "oa_ndim" }, { "__type": "Text", "__tag": 4046, "value": "-sized arrays of type " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_intp" }, { "__type": "Text", "__tag": 4046, "value": ". If an entry in " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": " is NULL, normal broadcasting rules will apply. In " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes[j][i]" }, { "__type": "Text", "__tag": 4046, "value": " is stored either a valid axis of " }, { "__type": "InlineCode", "__tag": 4051, "value": "op[j]" }, { "__type": "Text", "__tag": 4046, "value": ", or -1 which means " }, { "__type": "InlineCode", "__tag": 4051, "value": "newaxis" }, { "__type": "Text", "__tag": 4046, "value": ". Within each " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes[j]" }, { "__type": "Text", "__tag": 4046, "value": " array, axes may not be repeated. The following example is how normal broadcasting applies to a 3-D array, a 2-D array, a 1-D array and a scalar." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note" } ] }, { "__type": "Text", "__tag": 4046, "value": ": Before NumPy 1.8 " }, { "__type": "InlineCode", "__tag": 4051, "value": "oa_ndim == 0" }, { "__type": "Text", "__tag": 4046, "value": " was used for signalling that " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "itershape" }, { "__type": "Text", "__tag": 4046, "value": " are unused. This is deprecated and should be replaced with -1. Better backward compatibility may be achieved by using " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_MultiNew" }, { "__type": "Text", "__tag": 4046, "value": " for this case." } ] }, { "__type": "Code", "__tag": 4050, "value": "int oa_ndim = 3; /* # iteration axes */\n int op0_axes[] = {0, 1, 2}; /* 3-D operand */\n int op1_axes[] = {-1, 0, 1}; /* 2-D operand */\n int op2_axes[] = {-1, -1, 0}; /* 1-D operand */\n int op3_axes[] = {-1, -1, -1} /* 0-D (scalar) operand */\n int* op_axes[] = {op0_axes, op1_axes, op2_axes, op3_axes};", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "itershape" }, { "__type": "Text", "__tag": 4046, "value": " parameter allows you to force the iterator to have a specific iteration shape. It is an array of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "oa_ndim" }, { "__type": "Text", "__tag": 4046, "value": ". When an entry is negative, its value is determined from the operands. This parameter allows automatically allocated outputs to get additional dimensions which don't match up with any dimension of an input." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "buffersize" }, { "__type": "Text", "__tag": 4046, "value": " is zero, a default buffer size is used, otherwise it specifies how big of a buffer to use. Buffers which are powers of 2 such as 4096 or 8192 are recommended." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns NULL if there is an error, otherwise returns the allocated iterator." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Resets the iterator and restricts it to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "iterindex" }, { "__type": "Text", "__tag": 4046, "value": " range " }, { "__type": "InlineCode", "__tag": 4051, "value": "[istart, iend)" }, { "__type": "Text", "__tag": 4046, "value": ". See " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_Copy" }, { "__type": "Text", "__tag": 4046, "value": " for an explanation of how to use this for multi-threaded iteration. This requires that the flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_RANGED" }, { "__type": "Text", "__tag": 4046, "value": " was passed to the iterator constructor." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you want to reset both the " }, { "__type": "InlineCode", "__tag": 4051, "value": "iterindex" }, { "__type": "Text", "__tag": 4046, "value": " range and the base pointers at the same time, you can do the following to avoid extra buffer copying (be sure to add the return code error checks when you copy this code)." } ] }, { "__type": "Code", "__tag": 4050, "value": "/* Set to a trivial empty range */\n NpyIter_ResetToIterIndexRange(iter, 0, 0);\n /* Set the base pointers */\n NpyIter_ResetBasePointers(iter, baseptrs);\n /* Set to the desired range */\n NpyIter_ResetToIterIndexRange(iter, istart, iend);", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SUCCEED" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": ". If errmsg is non-NULL, no Python exception is set when " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": " is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Resets the iterator back to its initial state, but using the values in " }, { "__type": "InlineCode", "__tag": 4051, "value": "baseptrs" }, { "__type": "Text", "__tag": 4046, "value": " for the data instead of the pointers from the arrays being iterated. This functions is intended to be used, together with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "op_axes" }, { "__type": "Text", "__tag": 4046, "value": " parameter, by nested iteration code with two or more iterators." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SUCCEED" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": ". If errmsg is non-NULL, no Python exception is set when " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": " is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "TODO" } ] }, { "__type": "Text", "__tag": 4046, "value": ": Move the following into a special section on nested iterators." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Creating iterators for nested iteration requires some care. All the iterator operands must match exactly, or the calls to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_ResetBasePointers" }, { "__type": "Text", "__tag": 4046, "value": " will be invalid. This means that automatic copies and output allocation should not be used haphazardly. It is possible to still use the automatic data conversion and casting features of the iterator by creating one of the iterators with all the conversion parameters enabled, then grabbing the allocated operands with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_GetOperandArray" }, { "__type": "Text", "__tag": 4046, "value": " function and passing them into the constructors for the rest of the iterators." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "WARNING" } ] }, { "__type": "Text", "__tag": 4046, "value": ": When creating iterators for nested iteration, the code must not use a dimension more than once in the different iterators. If this is done, nested iteration will produce out-of-bounds pointers during iteration." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "WARNING" } ] }, { "__type": "Text", "__tag": 4046, "value": ": When creating iterators for nested iteration, buffering can only be applied to the innermost iterator. If a buffered iterator is used as the source for " }, { "__type": "InlineCode", "__tag": 4051, "value": "baseptrs" }, { "__type": "Text", "__tag": 4046, "value": ", it will point into a small buffer instead of the array and the inner iteration will be invalid." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The pattern for using nested iterators is as follows." } ] }, { "__type": "Code", "__tag": 4050, "value": "NpyIter *iter1, *iter1;\n NpyIter_IterNextFunc *iternext1, *iternext2;\n char **dataptrs1;\n\n /*\n * With the exact same operands, no copies allowed, and\n * no axis in op_axes used both in iter1 and iter2.\n * Buffering may be enabled for iter2, but not for iter1.\n */\n iter1 = ...; iter2 = ...;\n\n iternext1 = NpyIter_GetIterNext(iter1);\n iternext2 = NpyIter_GetIterNext(iter2);\n dataptrs1 = NpyIter_GetDataPtrArray(iter1);\n\n do {\n NpyIter_ResetBasePointers(iter2, dataptrs1);\n do {\n /* Use the iter2 values */\n } while (iternext2(iter2));\n } while (iternext1(iter1));", "execution_status": null } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Gets the " }, { "__type": "InlineCode", "__tag": 4051, "value": "iterindex" }, { "__type": "Text", "__tag": 4046, "value": " sub-range that is being iterated. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_RANGED" }, { "__type": "Text", "__tag": 4046, "value": " was not specified, this always returns the range " }, { "__type": "InlineCode", "__tag": 4051, "value": "[0, NpyIter_IterSize(iter))" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Builds a set of strides which are the same as the strides of an output array created using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_ALLOCATE" }, { "__type": "Text", "__tag": 4046, "value": " flag, where NULL was passed for op_axes. This is for data packed contiguously, but not necessarily in C or Fortran order. This should be used together with " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_GetShape" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter_GetNDim" }, { "__type": "Text", "__tag": 4046, "value": " with the flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_MULTI_INDEX" }, { "__type": "Text", "__tag": 4046, "value": " passed into the constructor." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A use case for this function is to match the shape and layout of the 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 to the end with size ndim and stride itemsize. To do the Hessian matrix, you do the same thing but add two dimensions, or take advantage of the symmetry and pack it into 1 dimension with a particular encoding." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function may only be called if the iterator is tracking a multi-index and if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_DONT_NEGATE_STRIDES" }, { "__type": "Text", "__tag": 4046, "value": " was used to prevent an axis from being iterated in reverse order." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If an array is created with this method, simply adding 'itemsize' for each iteration will traverse the new array matching the iterator." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SUCCEED" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Construction and destruction" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns a function pointer for iteration. A specialized version of the function pointer may be calculated by this function instead of being stored in the iterator structure. Thus, to get good performance, it is required that the function pointer be saved in a variable rather than retrieved for each loop iteration." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": " is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The typical looping construct is as follows." } ] }, { "__type": "Code", "__tag": 4050, "value": "NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);\n char** dataptr = NpyIter_GetDataPtrArray(iter);\n\n do {\n /* use the addresses dataptr[0], ... dataptr[nop-1] */\n } while(iternext(iter));", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_EXTERNAL_LOOP" }, { "__type": "Text", "__tag": 4046, "value": " is specified, the typical inner loop construct is as follows." } ] }, { "__type": "Code", "__tag": 4050, "value": "NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);\n char** dataptr = NpyIter_GetDataPtrArray(iter);\n npy_intp* stride = NpyIter_GetInnerStrideArray(iter);\n npy_intp* size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;\n npy_intp iop, nop = NpyIter_GetNOp(iter);\n\n do {\n size = *size_ptr;\n while (size--) {\n /* use the addresses dataptr[0], ... dataptr[nop-1] */\n for (iop = 0; iop < nop; ++iop) {\n dataptr[iop] += stride[iop];\n }\n }\n } while (iternext());", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Observe that we are using the dataptr array inside the iterator, not copying the values to a local temporary. This is possible because when " }, { "__type": "InlineCode", "__tag": 4051, "value": "iternext()" }, { "__type": "Text", "__tag": 4046, "value": " is called, these pointers will be overwritten with fresh values, not incrementally updated." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a compile-time fixed buffer is being used (both flags " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_BUFFERED" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_EXTERNAL_LOOP" }, { "__type": "Text", "__tag": 4046, "value": "), the inner size may be used as a signal as well. The size is guaranteed to become zero when " }, { "__type": "InlineCode", "__tag": 4051, "value": "iternext()" }, { "__type": "Text", "__tag": 4046, "value": " returns false, enabling the following loop construct. Note that if you use this construct, you should not pass " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_GROWINNER" }, { "__type": "Text", "__tag": 4046, "value": " as a flag, because it will cause larger sizes under some circumstances." } ] }, { "__type": "Code", "__tag": 4050, "value": "/* The constructor should have buffersize passed as this value */\n #define FIXED_BUFFER_SIZE 1024\n\n NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);\n char **dataptr = NpyIter_GetDataPtrArray(iter);\n npy_intp *stride = NpyIter_GetInnerStrideArray(iter);\n npy_intp *size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;\n npy_intp i, iop, nop = NpyIter_GetNOp(iter);\n\n /* One loop with a fixed inner size */\n size = *size_ptr;\n while (size == FIXED_BUFFER_SIZE) {\n /*\n * This loop could be manually unrolled by a factor\n * which divides into FIXED_BUFFER_SIZE\n */\n for (i = 0; i < FIXED_BUFFER_SIZE; ++i) {\n /* use the addresses dataptr[0], ... dataptr[nop-1] */\n for (iop = 0; iop < nop; ++iop) {\n dataptr[iop] += stride[iop];\n }\n }\n iternext();\n size = *size_ptr;\n }\n\n /* Finish-up loop with variable inner size */\n if (size > 0) do {\n size = *size_ptr;\n while (size--) {\n /* use the addresses dataptr[0], ... dataptr[nop-1] */\n for (iop = 0; iop < nop; ++iop) {\n dataptr[iop] += stride[iop];\n }\n }\n } while (iternext());", "execution_status": null } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns a function pointer for getting the current multi-index of the iterator. Returns NULL if the iterator is not tracking a multi-index. It is recommended that this function pointer be cached in a local variable before the iteration loop." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": " is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_EXTERNAL_LOOP" }, { "__type": "Text", "__tag": 4046, "value": " is used, the code needs to know the parameters for doing the inner loop. These functions provide that information." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Gets an array of strides which are fixed, or will not change during the entire iteration. For strides that may change, the value NPY_MAX_INTP is placed in the stride." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Once the iterator is prepared for iteration (after a reset if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_DELAY_BUFALLOC" }, { "__type": "Text", "__tag": 4046, "value": " was used), call this to get the strides which 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 its value into a variable once, then use the variable throughout the loop, or if the stride equals the itemsize, a contiguous version for that operand may be used." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function may be safely called without holding the Python GIL." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Functions for iteration" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The old iterator API includes functions like PyArrayIter_Check, PyArray_Iter* and PyArray_ITER_*. The multi-iterator array includes PyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest. The new iterator design replaces all of this functionality with a single object and associated API. One goal of the new API is that all uses of the existing iterator should be replaceable with the new iterator without significant effort. In 1.6, the major exception to this is the neighborhood iterator, which does not have corresponding features in this iterator." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Here is a conversion table for which functions to use with the new iterator:" } ] }, { "__type": "Code", "__tag": 4050, "value": "===================================== ===================================================\n*Iterator Functions*\n:c:func:`PyArray_IterNew` :c:func:`NpyIter_New`\n:c:func:`PyArray_IterAllButAxis` :c:func:`NpyIter_New` + ``axes`` parameter **or**\n Iterator flag :c:data:`NPY_ITER_EXTERNAL_LOOP`\n:c:func:`PyArray_BroadcastToShape` **NOT SUPPORTED** (Use the support for\n multiple operands instead.)\n:c:func:`PyArrayIter_Check` Will need to add this in Python exposure\n:c:func:`PyArray_ITER_RESET` :c:func:`NpyIter_Reset`\n:c:func:`PyArray_ITER_NEXT` Function pointer from :c:func:`NpyIter_GetIterNext`\n:c:func:`PyArray_ITER_DATA` :c:func:`NpyIter_GetDataPtrArray`\n:c:func:`PyArray_ITER_GOTO` :c:func:`NpyIter_GotoMultiIndex`\n:c:func:`PyArray_ITER_GOTO1D` :c:func:`NpyIter_GotoIndex` or\n :c:func:`NpyIter_GotoIterIndex`\n:c:func:`PyArray_ITER_NOTDONE` Return value of ``iternext`` function pointer\n*Multi-iterator Functions*\n:c:func:`PyArray_MultiIterNew` :c:func:`NpyIter_MultiNew`\n:c:func:`PyArray_MultiIter_RESET` :c:func:`NpyIter_Reset`\n:c:func:`PyArray_MultiIter_NEXT` Function pointer from :c:func:`NpyIter_GetIterNext`\n:c:func:`PyArray_MultiIter_DATA` :c:func:`NpyIter_GetDataPtrArray`\n:c:func:`PyArray_MultiIter_NEXTi` **NOT SUPPORTED** (always lock-step iteration)\n:c:func:`PyArray_MultiIter_GOTO` :c:func:`NpyIter_GotoMultiIndex`\n:c:func:`PyArray_MultiIter_GOTO1D` :c:func:`NpyIter_GotoIndex` or\n :c:func:`NpyIter_GotoIterIndex`\n:c:func:`PyArray_MultiIter_NOTDONE` Return value of ``iternext`` function pointer\n:c:func:`PyArray_Broadcast` Handled by :c:func:`NpyIter_MultiNew`\n:c:func:`PyArray_RemoveSmallest` Iterator flag :c:data:`NPY_ITER_EXTERNAL_LOOP`\n*Other Functions*\n:c:func:`PyArray_ConvertToCommonType` Iterator flag :c:data:`NPY_ITER_COMMON_DTYPE`\n===================================== ===================================================", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Converting from previous NumPy iterators" } ], "level": 1, "target": null } ], "local_refs": [] }