Table of Contents

Class np.NDIterator

Namespace
NumSharp
Assembly
NumSharp.dll

NumPy's numpy.nditer — the public, managed face of NumSharp's NDIterRef.

// numpy: for x in np.nditer(a): total += x
foreach (var vals in np.nditer(a))
    total += (int)vals[0];

// numpy: it = np.nditer(a, flags=['multi_index'])
//        while not it.finished: print(it.multi_index, it[0]); it.iternext()
var it = np.nditer(a, flags: new[] {"multi_index"});
while (!it.finished) { Use(it.multi_index, it[0]); it.iternext(); }
public class np.NDIterator : IEnumerable<NDArray[]>, IEnumerable, IDisposable
Inheritance
np.NDIterator
Implements
Inherited Members

Remarks

Port of NumPy 2.4.2's numpy/_core/src/multiarray/nditer_pywrap.c — the Python WRAPPER around the C iterator, which is what this class is: argument conversion, flag-string parsing, the property surface and the iteration protocol. The iterator itself is NDIterRef (NumPy's NpyIter), which already implements the buffering, casting, coalescing, broadcasting and index tracking.

Lifetime. NDIterRef is a ref struct and cannot live in a class field, so this class owns the heap NDIterState directly (handed over by NDIterRef.Detach) and re-borrows a non-owning NDIterRef for the duration of each call. It therefore MUST be disposed — close(), Dispose() or a using — which frees the unmanaged state and resolves any copy_if_overlap / updateifcopy write-backs, exactly like NumPy's with np.nditer(...) as it:. A finalizer is the safety net.

The yielded arrays alias the iterator. this[int] and value return views onto the iterator's LIVE data pointer (0-d normally, 1-d under external_loop), so they change under you on the next step and are invalid after disposal — the same contract as NumPy, where the loop variable must be copied to be kept. Writing through them writes to the operand (or its buffer), which is how readwrite iteration mutates an array.

Iteration yields NDArray[], always. NumPy yields a bare 0-d array for one operand and a tuple for several; C# has no such union, so enumeration always produces the operand array — vals[0] for the single-operand case. This is the same choice np.Broadcast made (object[] always).

Descriptors. The iterator is built over NumPy's resolved per-operand DESCRIPTORS (dtypes), not storage lanes, so fixed-width strings iterate, and the cast rules are NumPy's: copy / updateifcopy operands get a temporary in the iteration dtype laid out in the iterator's order (written back with unsafe casting at close()), a read-only 0-d operand is copied without being asked, and every other cast needs buffered.

Known differences. An allocated output requested as unsized 'U' / 'S' is allocated with one character, as in NumPy, but NumPy's views of it are unsized (writing through them stores nothing) while NumSharp's are one character wide. A non-native request ('>U3') is reported and cast-checked as NumPy does, but its buffer holds native data. The contig flag does not raise NumPy's "required buffering" error when an unbuffered operand is not contiguous, and nbo / aligned force no copy (NumSharp arrays are native; see the string dtype plan's open items).

Constructors

NDIterator(NDArray[], string[], string[][], DType[], char, string, int[][], long[], long)

The port of NumPy's npyiter_init (nditer_pywrap.c) and of the descriptor half of NpyIter_AdvancedNew: the arguments are converted in NumPy's order (flags, order, casting, then the operand count, then op_flags, op_dtypes, op_axes) and the itershape rank rule applied, the op_axes entries checked (npyiter_check_op_axes), the global flags checked, every operand prepared in turn (npyiter_prepare_operands: its flags, its writeability, its size, its requested dtype adapted to it), the iteration shape broadcast and checked (npyiter_fill_axisdata's shape pass, then its stride pass's refusals), the dtypes an allocation or common_dtype needs resolved (npyiter_get_common_dtype), and the iterator built over the resulting DESCRIPTORS and the broadcast shape — which is what lets it iterate fixed-width strings and run NumPy's cast checks and copy routes.

public NDIterator(NDArray[] op, string[] flags = null, string[][] op_flags = null, DType[] op_dtypes = null, char order = 'K', string casting = "safe", int[][] op_axes = null, long[] itershape = null, long buffersize = 0)

Parameters

op NDArray[]

The operands; a null entry is an output for the iterator to allocate.

flags string[]

The global flags.

op_flags string[][]

The per-operand flags (one inner list per operand, or one list for all).

op_dtypes DType[]

The requested iteration dtypes (one per operand; null entries mean "the operand's").

order char

The iteration order.

casting string

The casting rule.

op_axes int[][]

The per-operand axis maps (null entries for natural broadcasting).

itershape long[]

The iteration shape, or null: a negative entry is deduced from the operands; without op_axes it sets the rank and every operand is right-aligned into it.

buffersize long

The buffer size in elements (0 = NumPy's NPY_BUFSIZE, 8192 — as in NumPy, setbufsize(long) does not change it).

Remarks

NumPy's np.nditer(...) constructor, the one np.nditer calls; a subclass of the iterator chains to it. Every parameter after op has NumPy's default (since API-parity batch 12), so new np.NDIterator(new[] { a }) is NumPy's np.nditer([a]). The iterator holds native buffers: dispose it (or use it in a using) when done.

Exceptions

ValueError

NumPy's argument, flag, op_axes, shape-pass and stride-pass errors (verbatim texts: a broadcast mismatch, an invalid or duplicate axis, a stretched no_broadcast operand, a refused reduction), or a text that does not parse as the number a copy or the first buffer fill reads it into.

TypeError

A malformed op_dtypes sequence, a StringDType operand or request without refs_ok (before the shape pass), a refused cast, or a cast operand neither copied nor buffered.

OverflowError

A text read into an integer dtype by a copy or the first buffer fill holds a number outside that dtype.

MemoryError

A StringDType copy or buffer transfer cannot allocate a string (NumPy's MemoryError texts).

Properties

Current

The values published by the most recent MoveNext(). Borrowed: the per-step views are handed to the consumer, who owns them (NumPy's [x.copy() for x in it] idiom is the one that keeps them).

public NDArray[] Current { get; }

Property Value

NDArray[]

this[int]

A LIVE view of operand i at the current position (NumPy's it[i]) — 0-d normally, 1-d spanning the inner loop under external_loop. Writing through it writes to the operand or its buffer; the view is invalidated by the next step and by disposal. A negative index counts from the last operand. Setting it copies a value into the current element(s) — see the setter's remarks.

public NDArray this[int i] { get; set; }

Parameters

i int

The operand index (negative counts from the end).

Property Value

NDArray

The view; read-only unless the operand is written (readwrite / writeonly), as NumPy's views are (its write flags).

Remarks

The setter is NumPy's npyiter_seq_ass_item: the value is copied into a 1-D view of the current inner loop (one element without external_loop) by PyArray_CopyObject, the store a[...] = value makes. A C# number literal is NumPy's Python scalar, PACKED: range-checked, a float truncated into an integer operand, a NaN into one NumPy's ValueError, so it[1] = 300 on an int8 operand raises like NumPy's. A 0-d ARRAY (np.array(300), NDArray.Scalar(300)) is an array: it is assigned with an unsafe cast and stores 44, as NumPy's 0-d ndarray does. A value with dimensions is broadcast to the view ("could not broadcast input array from shape (2,) into shape (1,)"). Null is Python's None: NaN into a float operand, nan+nanj into a complex one, False into a bool one, Python's int() TypeError into an integer one.

A view of NEP 55 StringDType memory (the operand, or its buffer under a buffered cast to StringDType) goes through StringDType's setitem for a C# literal (a number stores its str(), null stores the NA object, or 'None' under coerce=True, and both raise "StringDType only allows string data when string coercion is disabled." under coerce=False), and an array is cast. A null into fixed-width text memory stores str(None), truncated to the width ('No' for <U2), as NumPy's setitem does.

Exceptions

ValueError

The iterator is closed or past the end ("Iterator is past the end"), or a delay_bufalloc iterator has not been reset (NumPy's text).

IndexError

No operand i: "Iterator operand index i is out of bounds".

RuntimeError

Setting a read-only operand: "Iterator operand i is not writeable".

OverflowError

Setting a C# number literal that does not fit the operand's dtype (NumPy's OverflowError texts: "Python integer 300 out of bounds for int8", "cannot convert float infinity to integer").

TypeError

Setting null (Python's None) or a complex literal into an integer operand (Python's int() texts), or a complex literal into a real one.

dtypes

The per-operand iteration dtypes (NumPy's dtypes): the descriptor each operand is iterated as — a requested dtype adapted to its operand ('U' over a <U3 array is <U3), the common dtype, or the operand's own. A string reports its width and class (dtype('<U5')), which a type code cannot.

public DType[] dtypes { get; }

Property Value

DType[]

Remarks

An allocated output keeps its request as given, as NumPy does: np.nditer([u, null], op_dtypes: [null, "U"]) reports dtype('<U') for the output although the array is allocated <U1. A non-native request ('>U3') is reported as requested although the buffer holds native data.

Exceptions

InvalidOperationException

The iterator is closed.

finished

True once iteration has run past the end (NumPy's finished): after the pull or iternext() that found no next element, and from the start for an empty iteration or range. A seek (iterindex, multi_index, index) clears it.

public bool finished { get; }

Property Value

bool

Remarks

A CLOSED iterator reads false, as NumPy's does (its getter tests the iterator before the flag).

has_delayed_bufalloc

Whether buffer allocation is still delayed pending a reset() (NumPy's has_delayed_bufalloc). While it is, the element views and multi_index refuse — NumPy's delay_bufalloc exists so an allocated output can be initialized before the buffers first read it.

public bool has_delayed_bufalloc { get; }

Property Value

bool

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

has_index

Whether a C- or F-order flat index is being tracked (NumPy's has_index).

public bool has_index { get; }

Property Value

bool

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

has_multi_index

Whether a multi-index is being tracked (NumPy's has_multi_index).

public bool has_multi_index { get; }

Property Value

bool

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

index

The tracked flat index (NumPy's index) — the position in C or F order of the operands' own shape, whatever order the iterator walks. Requires the c_index or f_index flag. Setting it moves the iterator there (NumPy's NpyIter_GotoIndex): the next pull yields that element.

public long index { get; set; }

Property Value

long

Exceptions

ValueError

Reading: the iterator is closed or past the end ("Iterator is past the end"), or no index is tracked ("Iterator does not have an index"). Setting: the iterator is closed ("Iterator is invalid"), no index is tracked, or it is buffered / external-loop (NumPy's "Cannot call GotoIndex on an iterator which …" texts).

IndexError

Setting: an index outside [0, itersize) ("Iterator GotoIndex called with an out-of-bounds index"), or one outside the current iterrange.

iterationneedsapi

Whether iteration needs the Python C-API (NumPy's iterationneedsapi). Always FALSE in NumSharp — there is no Python runtime, and the transfer flags never carry REQUIRES_PYAPI.

public bool iterationneedsapi { get; }

Property Value

bool

iterindex

The current flat iteration position (NumPy's iterindex), counted in the iterator's own order. Setting it moves the iterator there (NumPy's NpyIter_GotoIterIndex; a buffered iterator writes its window back and fills the one at the new position): the next pull yields that element.

public long iterindex { get; set; }

Property Value

long

Exceptions

ValueError

Reading: the iterator is closed or past the end ("Iterator is past the end"). Setting: the iterator is closed ("Iterator is invalid"), or it is external-loop ("Cannot call GotoIterIndex on an iterator which has the flag EXTERNAL_LOOP").

IndexError

Setting: a position outside the current iterrange ("Iterator GotoIterIndex called with an iterindex outside the iteration range.").

iterrange

The [start, end) sub-range being iterated (NumPy's iterrange). Setting it requires the ranged flag, and resets the iterator to the start of the new range (NumPy's NpyIter_ResetToIterIndexRange, which also allocates delayed buffers); an empty range is finished at once.

public (long Start, long End) iterrange { get; set; }

Property Value

(long low, long high)

Exceptions

ValueError

The iterator is closed ("Iterator is invalid"); setting without the ranged flag, a range outside [0, itersize] ("Out-of-bounds range [s, e) passed to ResetToIterIndexRange"), or an end before the start ("Invalid range [s, e) passed to ResetToIterIndexRange").

itersize

Total number of elements the iterator will visit (NumPy's itersize).

public long itersize { get; }

Property Value

long

itviews

Per-operand views with the iterator's internal axis ordering (NumPy's itviews). Not available while buffering.

public NDArray[] itviews { get; }

Property Value

NDArray[]

multi_index

The tracked multi-index (NumPy's multi_index) in the operands' own axis order. Requires the multi_index flag. Setting it moves the iterator there (NumPy's NpyIter_GotoMultiIndex): the next pull yields that element.

public long[] multi_index { get; set; }

Property Value

long[]

Exceptions

ValueError

Reading: the iterator is closed or past the end ("Iterator is past the end"), no multi-index is tracked, or a delay_bufalloc iterator has not been reset (NumPy's texts). Setting: the iterator is closed ("Iterator is invalid"), no multi-index is tracked, a null value ("multi_index must be set with a sequence"), a value whose length is not ndim ("Wrong number of indices"), or a buffered iterator ("Cannot call GotoMultiIndex on an iterator which is buffered").

IndexError

Setting: a coordinate outside its axis ("Iterator GotoMultiIndex called with an out-of-bounds multi-index"), or a position outside the current iterrange.

ndim

The number of dimensions iterated (NumPy's ndim).

public int ndim { get; }

Property Value

int

nop

The number of operands (NumPy's nop).

public int nop { get; }

Property Value

int

operands

The operands, including any the iterator ALLOCATED and the temporaries of its copy routes (NumPy's operands). Each read returns a new array of the same operand objects, as NumPy returns a new tuple, so replacing an entry cannot change what the iterator walks.

public NDArray[] operands { get; }

Property Value

NDArray[]

Exceptions

ValueError

The iterator is closed ("Iterator is invalid"): the copy-route temporaries were written back and released by close().

shape

The shape being iterated (NumPy's shape). Without multi_index the iterator is free to coalesce and reorder axes, so this is the COALESCED shape listed INNERMOST FIRST, NumPy's axisdata order (probed: a C-contiguous (2,3) reports (6,), an f_index walk of it — which cannot coalesce — (3, 2)); with multi_index it is the operands' own shape in their axis order, (2, 3).

public long[] shape { get; }

Property Value

long[]

Remarks

Code that reads the shape of an iterator without a multi-index gets the iteration's axes, not the array's: a forced F-order walk of a C (3, 4) array reports (3, 4) (axis 0 is its inner axis), a C-order walk of an F one reports (4, 3).

Exceptions

ValueError

The iterator is closed or past the end — NumPy's npyiter_shape_get guards it like a position ("Iterator is past the end"), so an empty iteration has no shape either.

value

The current values — one live view per operand (NumPy's value). NumPy returns a bare array for a single operand and a tuple otherwise; this always returns the array, so use value[0] for the single-operand case.

public NDArray[] value { get; }

Property Value

NDArray[]

Exceptions

ValueError

The iterator is closed or past the end ("Iterator is past the end"), or a delay_bufalloc iterator has not been reset.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

~NDIterator()

protected ~NDIterator()

GetEnumerator()

Enumerates the iterator's single live cursor, so — as in NumPy, where iter(it) is it — a second enumeration RESUMES where the first stopped rather than restarting (call reset() to go again).

public IEnumerator<NDArray[]> GetEnumerator()

Returns

IEnumerator<NDArray[]>

Remarks

Deliberately a thin wrapper rather than this, even though returning this would model iter(it) is it more literally: foreach disposes the enumerator it obtains, and this class's Dispose() frees the unmanaged iterator state. Handing out this would therefore CLOSE the iterator at the end of any foreach/LINQ pass, making every property read afterwards throw. The wrapper's Dispose is a no-op and the cursor is still shared, so the observable semantics are unchanged. (np.Broadcast can safely return this only because it owns no unmanaged resources.)

MoveNext()

NumPy's npyiter_next: ADVANCES ON ENTRY (its started flag) and then publishes the values at the new position — the first pull publishes the first element without moving, every later pull moves one step first. So after one pull iterindex still reads 0, and a copy() taken there (which carries the flag) resumes with the SECOND element.

public bool MoveNext()

Returns

bool

True when a value was published; false at the end.

Remarks

The order is what makes a buffered readwrite loop correct: a write through the published view lands in the buffer BEFORE the iterator moves past it, and moving past the end of a buffer is what flushes it. The publish-then-advance form this replaced (journey4's surface gap SU42) moved first, flushed the buffer, and lost the last write of every buffer. A published view stays valid until the next pull; under buffered external_loop iteration it aliases a buffer the next pull refills — NumPy has the identical hazard, hence its documented [x.copy() for x in it] idiom.

close()

Resolve write-backs and release the iterator (NumPy's close(), i.e. the end of a with np.nditer(...) as it: block). Idempotent; the iterator is unusable afterwards.

public void close()

copy()

Duplicate the iterator at its current position (NumPy's copy()). The copy owns its own state and must be disposed independently.

public np.NDIterator copy()

Returns

np.NDIterator

The copy, carrying NumPy's started / finished flags (so it resumes where the original would).

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

debug_print()

Dump the iterator's internal state to standard output (NumPy's debug_print()); a closed iterator prints NumPy's Iterator: (nil).

public void debug_print()

enable_external_loop()

Switch to external-loop iteration after construction (NumPy's enable_external_loop()), restarting from the first chunk (delayed buffers are allocated).

public void enable_external_loop()

Exceptions

ValueError

The iterator is closed ("Iterator is invalid"), or a flat index or multi-index is tracked ("Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is being tracked").

iternext()

Advance to the next element/chunk (NumPy's iternext()). Returns false at the end — and for a closed or finished iterator, without advancing (NumPy's npyiter_iternext raises nothing there).

public bool iternext()

Returns

bool

True when the iterator moved to another element; false when it is (now) finished.

remove_axis(int)

Remove an axis from iteration (NumPy's remove_axis(i)): the iterator then walks every other axis with that one fixed at index 0, and restarts. Requires the multi_index flag; the axis is in the operands' own numbering, whatever order the iterator walks.

public void remove_axis(int axis)

Parameters

axis int

The axis to remove, in [0, ndim) (no negative indexing, as in NumPy).

Exceptions

ValueError

The iterator is closed ("Iterator is invalid"), or axis is out of bounds ("axis out of bounds in iterator RemoveAxis").

RuntimeError

No multi-index is tracked, a flat index is tracked, or the iterator is buffered (NumPy's texts).

remove_multi_index()

Stop tracking the multi-index, letting the iterator coalesce and reorder axes (NumPy's remove_multi_index()). Resets the position to the start, whether or not a multi-index was tracked (a buffered window is written back first, delayed buffers are allocated).

public void remove_multi_index()

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

reset()

Rewind to the start of the range (NumPy's reset()); also allocates delayed buffers — the reset a delay_bufalloc iterator needs before its elements can be read. A buffered window already at the start is left as it is (NumPy's NpyIter_Reset).

public void reset()

Exceptions

ValueError

The iterator is closed ("Iterator is invalid").

MemoryError

Delayed buffers could not be allocated.