{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "nditer", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:nditer" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " supersedes " }, { "__type": "InlineRole", "__tag": 4003, "value": "flatiter", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". The iterator implementation behind " }, { "__type": "CrossRef", "__tag": 4002, "value": "nditer", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:nditer" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is also exposed by the NumPy C API." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Python exposure supplies two iteration interfaces, one which follows the Python iterator protocol, and another which mirrors the C-style do-while pattern. The native Python approach is better in most cases, but if you need the coordinates or index of an iterator, use the C-style pattern." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Efficient multi-dimensional iterator object to iterate over arrays. To get started using this object, see the " }, { "__type": "InlineRole", "__tag": 4003, "value": "introductory guide to array iteration ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "dtypes", "annotation": "tuple of dtype(s)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The data types of the values provided in " }, { "__type": "CrossRef", "__tag": 4002, "value": "value", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "value" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": ". This may be different from the operand data types if buffering is enabled. Valid only before the iterator is closed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "finished", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether the iteration over the operands is finished or not." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "has_delayed_bufalloc", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, the iterator was created with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "delay_bufalloc" }, { "__type": "Text", "__tag": 4046, "value": " flag, and no reset() function was called on it yet." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "has_index", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, the iterator was created with either the " }, { "__type": "InlineCode", "__tag": 4051, "value": "c_index" }, { "__type": "Text", "__tag": 4046, "value": " or the " }, { "__type": "InlineCode", "__tag": 4051, "value": "f_index" }, { "__type": "Text", "__tag": 4046, "value": " flag, and the property " }, { "__type": "CrossRef", "__tag": 4002, "value": "index", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "index" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " can be used to retrieve it." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "has_multi_index", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, the iterator was created with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "multi_index" }, { "__type": "Text", "__tag": 4046, "value": " flag, and the property " }, { "__type": "CrossRef", "__tag": 4002, "value": "multi_index", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "multi_index" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " can be used to retrieve it." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "index", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the " }, { "__type": "InlineCode", "__tag": 4051, "value": "c_index" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "f_index" }, { "__type": "Text", "__tag": 4046, "value": " flag was used, this property provides access to the index. Raises a ValueError if accessed and " }, { "__type": "InlineCode", "__tag": 4051, "value": "has_index" }, { "__type": "Text", "__tag": 4046, "value": " is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "iterationneedsapi", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether iteration requires access to the Python API, for example if one of the operands is an object array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "iterindex", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An index which matches the order of iteration." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "itersize", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Size of the iterator." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "itviews", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Structured view(s) of " }, { "__type": "CrossRef", "__tag": 4002, "value": "operands", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "operands" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " in memory, matching the reordered and optimized iterator access pattern. Valid only before the iterator is closed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "multi_index", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the " }, { "__type": "InlineCode", "__tag": 4051, "value": "multi_index" }, { "__type": "Text", "__tag": 4046, "value": " flag was used, this property provides access to the index. Raises a ValueError if accessed accessed and " }, { "__type": "InlineCode", "__tag": 4051, "value": "has_multi_index" }, { "__type": "Text", "__tag": 4046, "value": " is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "ndim", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dimensions of the iterator." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nop", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of iterator operands." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "operands", "annotation": "tuple of operand(s)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The array(s) to be iterated over. Valid only before the iterator is closed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "shape", "annotation": "tuple of ints", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Shape tuple, the shape of the iterator." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "value", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Value of " }, { "__type": "InlineCode", "__tag": 4051, "value": "operands" }, { "__type": "Text", "__tag": 4046, "value": " at current iteration. Normally, this is a tuple of array scalars, but if the flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "external_loop" }, { "__type": "Text", "__tag": 4046, "value": " is used, it is a tuple of one dimensional arrays." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "op", "annotation": "ndarray or sequence of array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The array(s) to iterate over." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "flags", "annotation": "sequence of str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flags to control the behavior of the iterator." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "buffered" }, { "__type": "Text", "__tag": 4046, "value": " enables buffering when required." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "c_index" }, { "__type": "Text", "__tag": 4046, "value": " causes a C-order index to be tracked." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "f_index" }, { "__type": "Text", "__tag": 4046, "value": " causes a Fortran-order index to be tracked." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "multi_index" }, { "__type": "Text", "__tag": 4046, "value": " causes a multi-index, or a tuple of indices with one per iteration dimension, to be tracked." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "common_dtype" }, { "__type": "Text", "__tag": 4046, "value": " causes all the operands to be converted to a common data type, with copying or buffering as necessary." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "copy_if_overlap" }, { "__type": "Text", "__tag": 4046, "value": " causes the iterator to determine if read operands have overlap with write operands, and make temporary copies as necessary to avoid overlap. False positives (needless copying) are possible in some cases." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "delay_bufalloc" }, { "__type": "Text", "__tag": 4046, "value": " delays allocation of the buffers until a reset() call is made. Allows " }, { "__type": "InlineCode", "__tag": 4051, "value": "allocate" }, { "__type": "Text", "__tag": 4046, "value": " operands to be initialized before their values are copied into the buffers." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "external_loop" }, { "__type": "Text", "__tag": 4046, "value": " causes the " }, { "__type": "InlineCode", "__tag": 4051, "value": "values" }, { "__type": "Text", "__tag": 4046, "value": " given to be one-dimensional arrays with multiple values instead of zero-dimensional arrays." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "grow_inner" }, { "__type": "Text", "__tag": 4046, "value": " allows the " }, { "__type": "InlineCode", "__tag": 4051, "value": "value" }, { "__type": "Text", "__tag": 4046, "value": " array sizes to be made larger than the buffer size when both " }, { "__type": "InlineCode", "__tag": 4051, "value": "buffered" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "external_loop" }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "ranged" }, { "__type": "Text", "__tag": 4046, "value": " allows the iterator to be restricted to a sub-range of the iterindex values." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "refs_ok" }, { "__type": "Text", "__tag": 4046, "value": " enables iteration of reference types, such as object arrays." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "reduce_ok" }, { "__type": "Text", "__tag": 4046, "value": " enables iteration of " }, { "__type": "InlineCode", "__tag": 4051, "value": "readwrite" }, { "__type": "Text", "__tag": 4046, "value": " operands which are broadcasted, also known as reduction operands." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "zerosize_ok" }, { "__type": "Text", "__tag": 4046, "value": " allows " }, { "__type": "CrossRef", "__tag": 4002, "value": "itersize", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "itersize" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " to be zero." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "op_flags", "annotation": "list of list of str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is a list of flags for each operand. At minimum, one of " }, { "__type": "InlineCode", "__tag": 4051, "value": "readonly" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "readwrite" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "writeonly" }, { "__type": "Text", "__tag": 4046, "value": " must be specified." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "readonly" }, { "__type": "Text", "__tag": 4046, "value": " indicates the operand will only be read from." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "readwrite" }, { "__type": "Text", "__tag": 4046, "value": " indicates the operand will be read from and written to." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "writeonly" }, { "__type": "Text", "__tag": 4046, "value": " indicates the operand will only be written to." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "no_broadcast" }, { "__type": "Text", "__tag": 4046, "value": " prevents the operand from being broadcasted." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "contig" }, { "__type": "Text", "__tag": 4046, "value": " forces the operand data to be contiguous." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "aligned" }, { "__type": "Text", "__tag": 4046, "value": " forces the operand data to be aligned." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "nbo" }, { "__type": "Text", "__tag": 4046, "value": " forces the operand data to be in native byte order." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "copy" }, { "__type": "Text", "__tag": 4046, "value": " allows a temporary read-only copy if required." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "updateifcopy" }, { "__type": "Text", "__tag": 4046, "value": " allows a temporary read-write copy if required." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "allocate" }, { "__type": "Text", "__tag": 4046, "value": " causes the array to be allocated if it is None in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "op" }, { "__type": "Text", "__tag": 4046, "value": " parameter." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "no_subtype" }, { "__type": "Text", "__tag": 4046, "value": " prevents an " }, { "__type": "InlineCode", "__tag": 4051, "value": "allocate" }, { "__type": "Text", "__tag": 4046, "value": " operand from using a subtype." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "arraymask" }, { "__type": "Text", "__tag": 4046, "value": " indicates that this operand is the mask to use for selecting elements when writing to operands with the 'writemasked' flag set. The iterator does not enforce this, but when writing from a buffer back to the array, it only copies those elements indicated by this mask." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "writemasked" }, { "__type": "Text", "__tag": 4046, "value": " indicates that only elements where the chosen " }, { "__type": "InlineCode", "__tag": 4051, "value": "arraymask" }, { "__type": "Text", "__tag": 4046, "value": " operand is True will be written to." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "overlap_assume_elementwise" }, { "__type": "Text", "__tag": 4046, "value": " can be used to mark operands that are accessed only in the iterator order, to allow less conservative copying when " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy_if_overlap" }, { "__type": "Text", "__tag": 4046, "value": " is present." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "op_dtypes", "annotation": "dtype or tuple of dtype(s), optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The required data type(s) of the operands. If copying or buffering is enabled, the data will be converted to/from their original types." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "order", "annotation": "{'C', 'F', 'A', 'K'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls the iteration order. 'C' means C order, 'F' means Fortran order, 'A' means 'F' order if all the arrays are Fortran contiguous, 'C' order otherwise, and 'K' means as close to the order the array elements appear in memory as possible. This also affects the element memory order of " }, { "__type": "InlineCode", "__tag": 4051, "value": "allocate" }, { "__type": "Text", "__tag": 4046, "value": " operands, as they are allocated to be compatible with iteration order. Default is 'K'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "casting", "annotation": "{'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls what kind of data casting may occur when making a copy or buffering. Setting this to 'unsafe' is not recommended, as it can adversely affect accumulations." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'no' means the data types should not be cast at all." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'equiv' means only byte-order changes are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'safe' means only casts which can preserve values are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'unsafe' means any data conversions may be done." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "op_axes", "annotation": "list of list of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, is a list of ints or None for each operands. The list of axes for an operand is a mapping from the dimensions of the iterator to the dimensions of the operand. A value of -1 can be placed for entries, causing that dimension to be treated as " }, { "__type": "InlineRole", "__tag": 4003, "value": "newaxis", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "itershape", "annotation": "tuple of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The desired shape of the iterator. This allows " }, { "__type": "InlineCode", "__tag": 4051, "value": "allocate" }, { "__type": "Text", "__tag": 4046, "value": " operands with a dimension mapped by op_axes not corresponding to a dimension of a different operand to get a value not equal to 1 for that dimension." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "buffersize", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When buffering is enabled, controls the size of the temporary buffers. Set to 0 for the default value." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/dev/numpy/build-install/usr/lib/python3.14/site-packages/numpy/__init__.py", "item_line": null, "item_type": "class", "aliases": [ "numpy.nditer" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Here is how we might write an ``iter_add`` function, using the\nPython iterator protocol:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "def iter_add_py(x, y, out=None):\n addop = np.add\n it = np.nditer([x, y, out], [],\n [['readonly'], ['readonly'], ['writeonly','allocate']])\n with it:\n for (a, b, c) in it:\n addop(a, b, out=c)\n return it.operands[2]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere is the same function, but following the C-style pattern:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def iter_add(x, y, out=None):\n addop = np.add\n it = np.nditer([x, y, out], [],\n [['readonly'], ['readonly'], ['writeonly','allocate']])\n with it:\n while not it.finished:\n addop(it[0], it[1], out=it[2])\n it.iternext()\n return it.operands[2]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere is an example outer product function:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def outer_it(x, y, out=None):\n mulop = np.multiply\n it = np.nditer([x, y, out], ['external_loop'],\n [['readonly'], ['readonly'], ['writeonly', 'allocate']],\n op_axes=[list(range(x.ndim)) + [-1] * y.ndim,\n [-1] * x.ndim + list(range(y.ndim)),\n None])\n with it:\n for (a, b, c) in it:\n mulop(a, b, out=c)\n return it.operands[2]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(2)+1\nb = np.arange(3)+1\nouter_it(a,b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere is an example function which operates like a \"lambda\" ufunc:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def luf(lamdaexpr, *args, **kwargs):\n '''luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)'''\n nargs = len(args)\n op = (kwargs.get('out',None),) + args\n it = np.nditer(op, ['buffered','external_loop'],\n [['writeonly','allocate','no_broadcast']] +\n [['readonly','nbo','aligned']]*nargs,\n order=kwargs.get('order','K'),\n casting=kwargs.get('casting','safe'),\n buffersize=kwargs.get('buffersize',0))\n while not it.finished:\n it[0] = lamdaexpr(*it[1:])\n it.iternext()\n return it.operands[0]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(5)\nb = np.ones(5)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "luf(lambda i,j:i*i + j/2, a, b)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIf operand flags ``\"writeonly\"`` or ``\"readwrite\"`` are used the\noperands may be views into the original data with the\n`WRITEBACKIFCOPY` flag. In this case `nditer` must be used as a\ncontext manager or the `nditer.close` method must be called before\nusing the result. The temporary data will be written back to the\noriginal data when the :meth:`~object.__exit__` function is called\nbut not before:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(6, dtype='i4')[::-2]\nwith np.nditer(a, [],\n [['writeonly', 'updateifcopy']],\n casting='unsafe',\n op_dtypes=[np.dtype('f4')]) as i:\n x = i.operands[0]\n x[:] = [-1, -2, -3]\n # a still unchanged here\na, x\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIt is important to note that once the iterator is exited, dangling\nreferences (like `x` in the example) may or may not share data with\nthe original data `a`. If writeback semantics were active, i.e. if\n`x.base.flags.writebackifcopy` is `True`, then exiting the iterator\nwill sever the connection between `x` and `a`, writing to `x` will\nno longer write to `a`. If writeback semantics are not active, then\n`x.data` will still point at some part of `a.data`, and writing to\none will affect the other.\n\nContext management and the `close` method appeared in version 1.15.0." } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "op", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "flags", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "op_flags", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "op_dtypes", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "order", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "K" }, { "__type": "SigParam", "__tag": 4030, "name": "casting", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "safe" }, { "__type": "SigParam", "__tag": 4030, "name": "op_axes", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "itershape", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "buffersize", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "nditer" }, "references": null, "qa": "numpy:nditer", "arbitrary": [], "local_refs": [ "buffersize", "casting", "dtypes", "finished", "flags", "has_delayed_bufalloc", "has_index", "has_multi_index", "index", "iterationneedsapi", "iterindex", "itershape", "itersize", "itviews", "multi_index", "ndim", "nop", "op", "op_axes", "op_dtypes", "op_flags", "operands", "order", "shape", "value" ] }