numpy.nditer#

class numpy.nditer(op, flags=None, op_flags=None, op_dtypes=None, order='K', casting='safe', op_axes=None, itershape=None, buffersize=0)[source]#

用于迭代数组的有效多维迭代器对象。要开始使用此对象，请参阅数组迭代入门指南。

参数:
opndarray 或数组类序列

要迭代的数组。

flags字符串序列，可选

控制迭代器行为的标志。

  • buffered 在需要时启用缓冲。

  • c_index 导致跟踪 C 顺序索引。

  • f_index 导致跟踪 Fortran 顺序索引。

  • multi_index 导致跟踪多索引，或包含每个迭代维度的索引元组。

  • common_dtype 导致所有操作数转换为通用数据类型，并在必要时进行复制或缓冲。

  • copy_if_overlap 导致迭代器确定读操作数是否与写操作数重叠，并在必要时创建临时副本以避免重叠。在某些情况下，可能会出现误报（不必要的复制）。

  • delay_bufalloc 将缓冲区的分配延迟到调用 reset() 之前。允许在将 allocate 操作数的值复制到缓冲区之前对其进行初始化。

  • external_loop 导致给定的 values 为具有多个值的单维数组，而不是零维数组。

  • grow_inner 允许在使用 buffered 和 external_loop 时，value 数组的大小大于缓冲区大小。

  • ranged 允许迭代器限制为 iterindex 值的子范围。

  • refs_ok 启用对引用类型的迭代，例如对象数组。

  • reduce_ok 启用对广播的 readwrite 操作数的迭代，也称为归约操作数。

  • zerosize_ok 允许 itersize 为零。

op_flags字符串列表列表，可选

这是每个操作数的标志列表。至少必须指定 readonly、readwrite 或 writeonly 之一。

  • readonly 表示仅从操作数读取。

  • readwrite 表示从操作数读取并写入。

  • writeonly 表示仅写入操作数。

  • no_broadcast 防止操作数被广播。

  • contig 强制操作数数据为连续数据。

  • aligned 强制操作数数据为对齐数据。

  • nbo 强制操作数数据为本机字节序。

  • copy 允许在需要时创建临时只读副本。

  • updateifcopy 允许在需要时创建临时读写副本。

  • allocate 导致在 op 参数中如果数组为 None 则分配数组。

  • no_subtype 阻止 allocate 操作数使用子类型。

  • arraymask 表示此操作数是用于在写入具有 ‘writemasked’ 标志的操作数时选择元素的掩码。迭代器不强制执行此操作，但在将缓冲区中的内容写回数组时，它只复制由此掩码指示的元素。

  • writemasked 表示仅写入选定 arraymask 操作数为 True 的元素。

  • overlap_assume_elementwise 可用于标记仅以迭代器顺序访问的操作数，以便在存在 copy_if_overlap 时允许更保守的复制。

op_dtypesdtype 或 dtype 元组，可选

操作数的所需数据类型。如果启用了复制或缓冲，数据将被转换为/从其原始类型转换。

order{‘C’, ‘F’, ‘A’, ‘K’}，可选

控制迭代顺序。‘C’ 表示 C 顺序，‘F’ 表示 Fortran 顺序，‘A’ 表示如果所有数组都是 Fortran 连续的，则为 ‘F’ 顺序，否则为 ‘C’ 顺序，而 ‘K’ 表示尽可能接近数组元素在内存中出现的顺序。这也会影响 allocate 操作数的元素内存顺序，因为它们被分配为与迭代顺序兼容。默认值为 ‘K’。

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}，可选

控制在进行复制或缓冲时可以进行哪些数据转换。设置此选项为 ‘unsafe’ 不推荐，因为它会对累加产生负面影响。

  • ‘no’ 表示数据类型根本不应转换。

  • ‘equiv’ 表示仅允许字节序更改。

  • ‘safe’ 表示仅允许可以保留值的转换。

  • ‘same_kind’ 表示仅允许安全的转换或在一种类型的转换，例如 float64 到 float32。

  • ‘unsafe’ 表示可以进行任何数据转换。

op_axes整数列表列表，可选

如果提供，则是每个操作数的整数列表或 None。操作数的轴列表是从迭代器的维度到操作数的维度的映射。可以将 -1 值放置在条目中，导致该维度被视为 newaxis。

itershape整数元组，可选

迭代器的所需形状。这允许 allocate 操作数在通过 op_axes 映射的维度不对应于其他操作数的维度时，获得该维度的值不等于 1。

buffersize整数，可选

启用缓冲时，控制临时缓冲区的大小。设置为 0 表示默认值。

备注

nditer 替代了 flatiter。 nditer 背后的迭代器实现也由 NumPy C API 公开。

Python 暴露了两种迭代接口，一种遵循 Python 迭代器协议，另一种模拟 C 风格的 do-while 模式。在大多数情况下，原生 Python 方法更好，但是如果您需要迭代器的坐标或索引，请使用 C 风格模式。

示例

以下是使用 Python 迭代器协议编写 iter_add 函数的方法

>>> import numpy as np

>>> def iter_add_py(x, y, out=None):
...     addop = np.add
...     it = np.nditer([x, y, out], [],
...                 [['readonly'], ['readonly'], ['writeonly','allocate']])
...     with it:
...         for (a, b, c) in it:
...             addop(a, b, out=c)
...         return it.operands[2]

这是同一个函数，但遵循 C 风格模式

>>> def iter_add(x, y, out=None):
...    addop = np.add
...    it = np.nditer([x, y, out], [],
...                [['readonly'], ['readonly'], ['writeonly','allocate']])
...    with it:
...        while not it.finished:
...            addop(it[0], it[1], out=it[2])
...            it.iternext()
...        return it.operands[2]

这是一个外部积函数的示例

>>> def outer_it(x, y, out=None):
...     mulop = np.multiply
...     it = np.nditer([x, y, out], ['external_loop'],
...             [['readonly'], ['readonly'], ['writeonly', 'allocate']],
...             op_axes=[list(range(x.ndim)) + [-1] * y.ndim,
...                      [-1] * x.ndim + list(range(y.ndim)),
...                      None])
...     with it:
...         for (a, b, c) in it:
...             mulop(a, b, out=c)
...         return it.operands[2]

>>> a = np.arange(2)+1
>>> b = np.arange(3)+1
>>> outer_it(a,b)
array([[1, 2, 3],
       [2, 4, 6]])

这是一个像“lambda” ufunc 一样工作的函数示例

>>> def luf(lamdaexpr, *args, **kwargs):
...    '''luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)'''
...    nargs = len(args)
...    op = (kwargs.get('out',None),) + args
...    it = np.nditer(op, ['buffered','external_loop'],
...            [['writeonly','allocate','no_broadcast']] +
...                            [['readonly','nbo','aligned']]*nargs,
...            order=kwargs.get('order','K'),
...            casting=kwargs.get('casting','safe'),
...            buffersize=kwargs.get('buffersize',0))
...    while not it.finished:
...        it[0] = lamdaexpr(*it[1:])
...        it.iternext()
...    return it.operands[0]

>>> a = np.arange(5)
>>> b = np.ones(5)
>>> luf(lambda i,j:i*i + j/2, a, b)
array([  0.5,   1.5,   4.5,   9.5,  16.5])

如果操作数标志 "writeonly" 或 "readwrite" 被使用，操作数可能是使用 WRITEBACKIFCOPY 标志的原始数据的视图。在这种情况下，nditer 必须用作上下文管理器，或者在使用结果之前必须调用 nditer.close 方法。当 __exit__ 函数被调用时，临时数据将被写回原始数据，但在此之前不会。

>>> a = np.arange(6, dtype='i4')[::-2]
>>> with np.nditer(a, [],
...        [['writeonly', 'updateifcopy']],
...        casting='unsafe',
...        op_dtypes=[np.dtype('f4')]) as i:
...    x = i.operands[0]
...    x[:] = [-1, -2, -3]
...    # a still unchanged here
>>> a, x
(array([-1, -2, -3], dtype=int32), array([-1., -2., -3.], dtype=float32))

重要的是要注意，一旦迭代器退出，悬空引用（如示例中的 x）可能与原始数据 a 共享数据，也可能不共享。如果写回语义处于活动状态，即如果 x.base.flags.writebackifcopy 为 True，那么退出迭代器将断开 x 和 a 之间的连接，写入 x 将不再写入 a。如果写回语义不处于活动状态，那么 x.data 仍然会指向 a.data 的一部分，写入其中一个会影响另一个。

上下文管理和 close 方法出现在版本 1.15.0 中。

属性：
dtypesdtype 的元组

在 value 中提供的值的數據類型。如果启用了缓冲，这可能与操作数数据类型不同。仅在迭代器关闭之前有效。

finished布尔值

是否完成了对操作数的迭代。

has_delayed_bufalloc布尔值

如果为 True，则使用 delay_bufalloc 标志创建迭代器，并且尚未对其调用 reset() 函数。

has_index布尔值

如果为 True，则使用 c_index 或 f_index 标志创建迭代器，并且可以使用属性 index 来检索它。

has_multi_index布尔值

如果为 True，则使用 multi_index 标志创建迭代器，并且可以使用属性 multi_index 来检索它。

索引

当使用 c_index 或 f_index 标志时，此属性提供对索引的访问。如果访问它并且 has_index 为 False，则会引发 ValueError。

iterationneedsapi布尔值

迭代是否需要访问 Python API，例如，如果操作数之一是对象数组。

iterindex整数

与迭代顺序匹配的索引。

itersize整数

迭代器的大小。

itviews

内存中 operands 的结构化视图，与重新排序和优化的迭代器访问模式匹配。仅在迭代器关闭之前有效。

multi_index

当使用 multi_index 标志时，此属性提供对索引的访问。如果访问它并且 has_multi_index 为 False，则会引发 ValueError。

ndim整数

迭代器的维度。

nop整数

迭代器操作数的数量。

operands操作数的元组

operands[切片]

shape整数元组

形状元组，迭代器的形状。

值

当前迭代中 operands 的值。通常，这是一个数组标量的元组，但是如果使用标志 external_loop，它是一个一维数组的元组。

方法

关闭()

解析可写操作数中的所有写回语义。

复制()

获取迭代器当前状态的副本。

调试打印()

将 nditer 实例的当前状态和调试信息打印到标准输出。

启用外部循环()

当在构建期间未使用“external_loop”，但需要它时，这会修改迭代器，使其表现得好像指定了该标志。

iternext()

检查是否还有迭代，并执行一次内部迭代，但不返回结果。

remove_axis(i, /)

从迭代器中删除轴 i。

删除多索引()

当指定“multi_index”标志时，这会将其删除，从而允许进一步优化内部迭代结构。

重置()

将迭代器重置为其初始状态。
此页上的内容