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)[源代码]

高效的多维迭代器对象，用于在数组上迭代。要开始使用此对象，请参见 introductory guide to array iteration .

参数
op数组的数组或序列

要循环访问的数组。

flagsstr序列，可选

用于控制迭代器行为的标志。

  • buffered 在需要时启用缓冲。

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

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

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

  • common_dtype 使所有操作数转换为公共数据类型，并根据需要进行复制或缓冲。

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

  • delay_bufalloc 延迟缓冲区的分配，直到发出reset（）调用。允许 allocate 将值复制到缓冲区之前要初始化的操作数。

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

  • grow_inner 允许 value 当两者同时存在时，要使数组大小大于缓冲区大小 buffered 和 external_loop 使用。

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

  • refs_ok 例如，启用引用类型的迭代。

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

  • zerosize_ok 允许 itersize 为零。

op_flagsstr列表，可选

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

  • readonly 指示操作数只能从中读取。

  • readwrite 指示操作数将被读取和写入。

  • writeonly 指示操作数将只写入。

  • no_broadcast 阻止广播操作数。

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

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

  • nbo 强制操作数数据采用本机字节顺序。

  • copy 如果需要，允许临时只读副本。

  • updateifcopy 如果需要，允许临时读写副本。

  • allocate 如果数组在 op 参数。

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

  • arraymask 指示此操作数是在使用“writemasked”标志集写入操作数时用于选择元素的掩码。当一个数组将这些元素从后面写入时，迭代器只会将这些元素从后面写入，而不是从后面写入。

  • writemasked 指示只有选定 arraymask 操作数为真时将写入。

  • overlap_assume_elementwise 可用于标记仅按迭代器顺序访问的操作数，以便在 copy_if_overlap 是存在的。

op_dtypes数据类型或数据类型的元组，可选

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

order'C'、'F'、'A'、'K'，可选

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

casting'no'、'equiv'、'safe'、'same'u kind'、'unsafe'、可选

控制在进行复制或缓冲时可能发生的数据强制转换类型。不建议将此设置为“不安全”，因为它会对累积产生不利影响。

  • “否”表示完全不应强制转换数据类型。

  • “equiv”表示只允许更改字节顺序。

  • “safe”表示只允许保留值的强制转换。

  • “相同类型”意味着只允许安全的类型或类型内的类型，如float64到float32。

  • “不安全”表示可以进行任何数据转换。

op_axesINTS列表，可选

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

itershape整数元组，可选

迭代器所需的形状。这允许 allocate 由运算轴映射的维数与另一个操作数的维数不对应的操作数，其值不等于该维数的1。

buffersize可选的

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

笔记

nditer 替代物 flatiter . 后面的迭代器实现 nditer 也是由numpy c api公开的。

Python公开提供了两个迭代接口，一个遵循Python迭代器协议，另一个镜像C风格的do-while模式。本地Python方法在大多数情况下更好，但是如果您需要迭代器的坐标或索引，请使用C样式的模式。

实例

我们可以这样写 iter_add 函数，使用Python迭代器协议：

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

if操作数标志 "writeonly" or "readwrite" are used the operands may be views into the original data with the WRITEBACKIFCOPY flag. In this case nditer must be used as a context manager or the nditer.close method must be called before using the result. The temporary data will be written back to the original data when the `_ _调用exit_uuuuuuuuuuuuuuuuu函数，但不能在以下时间之前调用：

>>> 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中。

属性
dtypes数据类型的元组

中提供的值的数据类型 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 可用于检索。

index

当 c_index 或 f_index 如果使用了标志，则此属性提供对索引的访问。如果访问并 has_index 是假的。

iterationneedsapi布尔

迭代是否需要访问python api，例如，如果其中一个操作数是对象数组。

iterindex利息

与迭代顺序相匹配的索引。

itersize利息

迭代器的大小。

itviews

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

multi_index

当 multi_index 如果使用了标志，则此属性提供对索引的访问。如果访问和访问，则引发ValueError has_multi_index 是假的。

ndim利息

迭代器的维数。

nop利息

迭代器操作数。

operands操作数元组

操作数 [Slice]

shape整数元组

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

value

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

方法

close （）

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

copy （）

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

debug_print （）

打印的当前状态 nditer 实例和调试信息到stdout。

enable_external_loop （）

如果在构造过程中没有使用“external_loop”，但需要这样做，则会修改迭代器，使其行为与指定标志时一样。

iternext （）

检查是否保留迭代，并在不返回结果的情况下执行单个内部迭代。

remove_axis （i）

移除轴 i 来自迭代器。

remove_multi_index （）

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

reset （）

将迭代器重置为其初始状态。
numpy.fill_diagonal numpy.nditer.close