数组迭代#
在 NumPy 1.6 中引入的迭代器对象nditer提供了许多灵活的方法来系统地访问一个或多个数组的所有元素。本页介绍了一些使用该对象进行 Python 数组计算的基本方法，然后总结了如何在 Cython 中加速内部循环。由于nditer的 Python 接口是 C 数组迭代器 API 的相对直接映射，因此这些想法也将有助于从 C 或 C++ 进行数组迭代。
单数组迭代#
使用nditer可以完成的最基本任务是访问数组的每个元素。每个元素都使用标准 Python 迭代器接口逐个提供。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a):
... print(x, end=' ')
...
0 1 2 3 4 5
对于此迭代需要注意的一点是，选择的顺序与数组的内存布局匹配，而不是使用标准的 C 或 Fortran 顺序。这样做是为了提高访问效率，反映了默认情况下只是想访问每个元素而不关心特定顺序的想法。我们可以通过迭代先前数组的转置来查看这一点，这与以 C 顺序获取该转置的副本相比。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a.T):
... print(x, end=' ')
...
0 1 2 3 4 5
>>> for x in np.nditer(a.T.copy(order='C')):
... print(x, end=' ')
...
0 3 1 4 2 5
a 和 a.T 的元素都以相同的顺序遍历，即它们在内存中存储的顺序，而a.T.copy(order=’C’)的元素则以不同的顺序访问，因为它们已被放入不同的内存布局中。
控制迭代顺序#
有时需要以特定顺序访问数组的元素，而不管元素在内存中的布局如何。nditer对象提供了一个order参数来控制迭代的这一方面。默认情况下，具有上述行为，为 order=’K’ 以保持现有顺序。这可以使用 order=’C’（C 顺序）和 order=’F’（Fortran 顺序）来覆盖。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, order='F'):
... print(x, end=' ')
...
0 3 1 4 2 5
>>> for x in np.nditer(a.T, order='C'):
... print(x, end=' ')
...
0 3 1 4 2 5
修改数组值#
默认情况下，nditer将输入操作数视为只读对象。要能够修改数组元素，必须使用‘readwrite’或‘writeonly’每个操作数标志指定读写或只写模式。
nditer然后将产生可写的缓冲区数组，您可以修改这些数组。但是，因为nditer必须在迭代完成后将此缓冲区数据复制回原始数组，所以您必须通过两种方法之一来发出迭代结束的信号。您可以：
一旦调用close或退出其上下文，nditer就不能再进行迭代了。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> a
array([[0, 1, 2],
[3, 4, 5]])
>>> with np.nditer(a, op_flags=['readwrite']) as it:
... for x in it:
... x[...] = 2 * x
...
>>> a
array([[ 0, 2, 4],
[ 6, 8, 10]])
如果您正在编写需要支持旧版本 NumPy 的代码，请注意，在 1.15 之前，nditer不是上下文管理器，也没有close方法。相反，它依赖于析构函数来启动缓冲区的回写。
使用外部循环#
在所有之前的示例中，a的元素是由迭代器一次一个地提供的，因为所有循环逻辑都在迭代器内部。虽然这简单方便，但效率不高。更好的方法是将一维最内层循环移动到您的代码中，位于迭代器之外。这样，NumPy 的向量化操作就可以用于正在访问的更大块的元素。
nditer将尝试向内部循环提供尽可能大的块。通过强制使用“C”和“F”顺序，我们得到不同的外部循环大小。此模式通过指定迭代器标志来启用。
观察到，在保持本地内存顺序的默认情况下，迭代器能够提供单个一维块，而当强制使用 Fortran 顺序时，它必须提供三个包含两个元素的块。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop']):
... print(x, end=' ')
...
[0 1 2 3 4 5]
>>> for x in np.nditer(a, flags=['external_loop'], order='F'):
... print(x, end=' ')
...
[0 3] [1 4] [2 5]
跟踪索引或多索引#
在迭代期间，您可能希望在计算中使用当前元素的索引。例如，您可能希望以内存顺序访问数组的元素，但是使用 C 顺序、Fortran 顺序或多维索引来查找不同数组中的值。
索引由迭代器对象本身跟踪，并可通过index或multi_index属性访问，具体取决于请求的内容。下面的示例显示了演示索引进度的打印输出。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> it = np.nditer(a, flags=['f_index'])
>>> for x in it:
... print("%d <%d>" % (x, it.index), end=' ')
...
0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5>
>>> it = np.nditer(a, flags=['multi_index'])
>>> for x in it:
... print("%d <%s>" % (x, it.multi_index), end=' ')
...
0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)>
>>> with np.nditer(a, flags=['multi_index'], op_flags=['writeonly']) as it:
... for x in it:
... x[...] = it.multi_index[1] - it.multi_index[0]
...
>>> a
array([[ 0, 1, 2],
[-1, 0, 1]])
跟踪索引或多索引与使用外部循环不兼容，因为它需要每个元素不同的索引值。如果您尝试组合这些标志，nditer对象将引发异常。
示例
>>> import numpy as np
>>> a = np.zeros((2,3))
>>> it = np.nditer(a, flags=['c_index', 'external_loop'])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is being tracked
替代循环和元素访问#
为了使其属性在迭代期间更容易访问，nditer有一种替代的迭代语法，它显式地使用迭代器对象本身。使用此循环结构，当前值可以通过索引迭代器来访问。其他属性（如跟踪索引）保持不变。下面的示例产生的结果与上一节中的示例相同。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> it = np.nditer(a, flags=['f_index'])
>>> while not it.finished:
... print("%d <%d>" % (it[0], it.index), end=' ')
... is_not_finished = it.iternext()
...
0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5>
>>> it = np.nditer(a, flags=['multi_index'])
>>> while not it.finished:
... print("%d <%s>" % (it[0], it.multi_index), end=' ')
... is_not_finished = it.iternext()
...
0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)>
>>> with np.nditer(a, flags=['multi_index'], op_flags=['writeonly']) as it:
... while not it.finished:
... it[0] = it.multi_index[1] - it.multi_index[0]
... is_not_finished = it.iternext()
...
>>> a
array([[ 0, 1, 2],
[-1, 0, 1]])
缓冲数组元素#
在强制迭代顺序时，我们观察到外部循环选项可能会以较小的块提供元素，因为无法以恒定步长以适当的顺序访问元素。在编写 C 代码时，这通常是可以的，但是在纯 Python 代码中，这可能会导致性能显著下降。
通过启用缓冲模式，迭代器向内部循环提供的块可以做得更大，从而显著减少 Python 解释器的开销。在强制 Fortran 迭代顺序的示例中，启用缓冲后，内部循环可以一次性看到所有元素。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop'], order='F'):
... print(x, end=' ')
...
[0 3] [1 4] [2 5]
>>> for x in np.nditer(a, flags=['external_loop','buffered'], order='F'):
... print(x, end=' ')
...
[0 3 1 4 2 5]
以特定数据类型迭代#
有时候，需要将数组视为与存储时不同的数据类型。例如，即使正在操作的数组是32位浮点数，也可能希望对64位浮点数进行所有计算。除非编写底层的C代码，否则通常最好让迭代器处理复制或缓冲，而不是在内循环中自己转换数据类型。
有两种机制可以做到这一点：临时复制和缓冲模式。使用临时复制，将使用新的数据类型创建整个数组的副本，然后在副本中进行迭代。通过一种模式允许写入访问，该模式在所有迭代完成后更新原始数组。临时复制的主要缺点是临时副本可能会消耗大量的内存，特别是如果迭代数据类型的itemsize大于原始数据类型时。
缓冲模式可以减轻内存使用问题，并且比临时复制更缓存友好。除非特殊情况（需要在迭代器外部一次性使用整个数组），否则建议使用缓冲而不是临时复制。在NumPy中，ufunc和其他函数使用缓冲来支持灵活的输入，并最大限度地减少内存开销。
在我们的示例中，我们将使用复杂数据类型处理输入数组，以便我们可以对负数进行平方根运算。如果不启用复制或缓冲模式，如果数据类型不完全匹配，迭代器将引发异常。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_dtypes=['complex128']):
... print(np.sqrt(x), end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand required copying or buffering, but neither copying nor buffering was enabled
在复制模式下，“copy”被指定为每个操作数的标志。这样做是为了提供每个操作数的控制方式。缓冲模式被指定为迭代器标志。
示例
>>> import numpy as np
>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_flags=['readonly','copy'],
... op_dtypes=['complex128']):
... print(np.sqrt(x), end=' ')
...
1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+0j)
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['complex128']):
... print(np.sqrt(x), end=' ')
...
1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+0j)
迭代器使用NumPy的类型转换规则来确定是否允许特定的转换。默认情况下，它强制执行“安全”转换。这意味着，例如，如果您尝试将64位浮点数组视为32位浮点数组，它将引发异常。在许多情况下，“same_kind”规则是最合理的规则，因为它允许从64位浮点转换为32位浮点，但不允许从浮点转换为整数或从复数转换为浮点。
示例
>>> import numpy as np
>>> a = np.arange(6.)
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32']):
... print(x, end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype('float32') according to the rule 'safe'
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32'],
... casting='same_kind'):
... print(x, end=' ')
...
0.0 1.0 2.0 3.0 4.0 5.0
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['int32'], casting='same_kind'):
... print(x, end=' ')
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype('int32') according to the rule 'same_kind'
需要注意的一点是，在使用读写或只写操作数时，转换回原始数据类型。一个常见的情况是用64位浮点数实现内循环，并使用“same_kind”转换来允许处理其他浮点类型。在只读模式下，可以提供整数数组，但读写模式将引发异常，因为转换回数组将违反转换规则。
示例
>>> import numpy as np
>>> a = np.arange(6)
>>> for x in np.nditer(a, flags=['buffered'], op_flags=['readwrite'],
... op_dtypes=['float64'], casting='same_kind'):
... x[...] = x / 2.0
...
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
TypeError: Iterator requested dtype could not be cast from dtype('float64') to dtype('int64'), the operand 0 dtype, according to the rule 'same_kind'
广播数组迭代#
NumPy有一套处理形状不同的数组的规则，这些规则在函数采用多个按元素组合的操作数时应用。这称为广播。nditer对象可以在您需要编写此类函数时为您应用这些规则。
例如，我们打印出一维数组和二维数组一起广播的结果。
示例
>>> import numpy as np
>>> a = np.arange(3)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
... print("%d:%d" % (x,y), end=' ')
...
0:0 1:1 2:2 0:3 1:4 2:5
当发生广播错误时，迭代器会引发异常，其中包含输入形状以帮助诊断问题。
示例
>>> import numpy as np
>>> a = np.arange(2)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
... print("%d:%d" % (x,y), end=' ')
...
Traceback (most recent call last):
...
ValueError: operands could not be broadcast together with shapes (2,) (2,3)
迭代器分配的输出数组#
NumPy函数中的一个常见情况是根据输入的广播分配输出，并且另外还有一个名为“out”的可选参数，当提供该参数时，结果将被放置在其中。nditer对象提供了一种方便的习惯用法，使支持这种机制变得非常容易。
我们将通过创建一个对输入进行平方运算的函数square来展示其工作原理。让我们从一个不包含“out”参数支持的最小函数定义开始。
示例
>>> import numpy as np
>>> def square(a):
... with np.nditer([a, None]) as it:
... for x, y in it:
... y[...] = x*x
... return it.operands[1]
...
>>> square([1,2,3])
array([1, 4, 9])
默认情况下，nditer对作为None传入的操作数使用标志“allocate”和“writeonly”。这意味着我们只需向迭代器提供这两个操作数，它就能处理其余部分。
添加“out”参数时，我们必须显式地提供这些标志，因为如果有人将数组作为“out”传入，迭代器将默认为“readonly”，而我们的内循环将失败。“readonly”是输入数组的默认值的原因是为了防止意外触发归约操作的混淆。如果默认值为“readwrite”，任何广播操作也将触发归约，这将在本文档后面讨论。
顺便说一下，我们还将介绍“no_broadcast”标志，它将阻止输出被广播。这很重要，因为我们每个输出只想要一个输入值。聚合多个输入值是需要特殊处理的归约操作。它已经会引发错误，因为归约必须在迭代器标志中显式启用，但是禁用广播所产生的错误消息对于最终用户来说更容易理解。要了解如何将平方函数推广到归约，请查看关于Cython部分中的平方和函数。
为了完整起见，我们还将添加“external_loop”和“buffered”标志，因为这些标志通常是出于性能原因而需要的。
示例
>>> import numpy as np
>>> def square(a, out=None):
... it = np.nditer([a, out],
... flags = ['external_loop', 'buffered'],
... op_flags = [['readonly'],
... ['writeonly', 'allocate', 'no_broadcast']])
... with it:
... for x, y in it:
... y[...] = x*x
... return it.operands[1]
...
>>> square([1,2,3])
array([1, 4, 9])
>>> b = np.zeros((3,))
>>> square([1,2,3], out=b)
array([1., 4., 9.])
>>> b
array([1., 4., 9.])
>>> square(np.arange(6).reshape(2,3), out=b)
Traceback (most recent call last):
...
ValueError: non-broadcastable output operand with shape (3,) doesn't
match the broadcast shape (2,3)
外积迭代#
任何二元运算都可以像在outer中一样扩展到外积形式的数组运算，并且nditer对象提供了一种方法，可以通过显式映射操作数的轴来实现此目的。也可以使用newaxis索引来实现这一点，但我们将向您展示如何直接使用nditer的op_axes参数来实现这一点，而无需中间视图。
我们将做一个简单的外积，将第一个操作数的维度放在第二个操作数的维度之前。op_axes参数需要每个操作数一个轴列表，并提供从迭代器的轴到操作数的轴的映射。
假设第一个操作数是一维的，第二个操作数是二维的。迭代器将具有三个维度，因此op_axes将有两个3元素列表。第一个列表挑选出第一个操作数的一个轴，对于迭代器的其余轴为-1，最终结果为[0，-1，-1]。第二个列表挑选出第二个操作数的两个轴，但不应与第一个列表中挑选出的轴重叠。其列表为[-1，0，1]。输出操作数以标准方式映射到迭代器轴，因此我们可以提供None而不是构造另一个列表。
内循环中的操作是简单的乘法。与外积有关的一切都由迭代器设置处理。
示例
>>> import numpy as np
>>> a = np.arange(3)
>>> b = np.arange(8).reshape(2,4)
>>> it = np.nditer([a, b, None], flags=['external_loop'],
... op_axes=[[0, -1, -1], [-1, 0, 1], None])
>>> with it:
... for x, y, z in it:
... z[...] = x*y
... result = it.operands[2] # same as z
...
>>> result
array([[[ 0, 0, 0, 0],
[ 0, 0, 0, 0]],
[[ 0, 1, 2, 3],
[ 4, 5, 6, 7]],
[[ 0, 2, 4, 6],
[ 8, 10, 12, 14]]])
请注意，一旦迭代器关闭，我们就无法访问operands，并且必须使用在上下文管理器内部创建的引用。
归约迭代#
每当可写操作数的元素少于完整的迭代空间时，该操作数就会进行归约。nditer对象要求任何归约操作数都被标记为读写，并且只有在提供“reduce_ok”作为迭代器标志时才允许归约。
对于一个简单的例子，考虑对数组中所有元素求和。
示例
>>> import numpy as np
>>> a = np.arange(24).reshape(2,3,4)
>>> b = np.array(0)
>>> with np.nditer([a, b], flags=['reduce_ok'],
... op_flags=[['readonly'], ['readwrite']]) as it:
... for x,y in it:
... y[...] += x
...
>>> b
array(276)
>>> np.sum(a)
276
当组合归约和分配的操作数时，事情会变得有点棘手。在开始迭代之前，必须将任何归约操作数初始化为其起始值。以下是我们可以执行此操作的方法，沿着a的最后一个轴求和。
示例
>>> import numpy as np
>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, [0,1,-1]])
>>> with it:
... it.operands[1][...] = 0
... for x, y in it:
... y[...] += x
... result = it.operands[1]
...
>>> result
array([[ 6, 22, 38],
[54, 70, 86]])
>>> np.sum(a, axis=2)
array([[ 6, 22, 38],
[54, 70, 86]])
要进行缓冲归约，需要在设置过程中进行另一次调整。通常，迭代器构造涉及将可读数组的第一个数据缓冲区复制到缓冲区中。任何归约操作数都是可读的，因此可以将其读入缓冲区。不幸的是，在这个缓冲操作完成后对操作数的初始化将不会反映在迭代开始使用的缓冲区中，并且会产生垃圾结果。
迭代器标志“delay_bufalloc”允许迭代器分配的归约操作数与缓冲一起存在。当设置此标志时，迭代器将保留其缓冲区未初始化，直到它收到重置，之后它将准备好进行常规迭代。以下是如果我们还启用缓冲，则前面的示例的外观。
示例
>>> import numpy as np
>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok',
... 'buffered', 'delay_bufalloc'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, [0,1,-1]])
>>> with it:
... it.operands[1][...] = 0
... it.reset()
... for x, y in it:
... y[...] += x
... result = it.operands[1]
...
>>> result
array([[ 6, 22, 38],
[54, 70, 86]])
将内循环放入Cython#
对于希望充分发挥低级运算性能的用户，强烈建议直接使用 C 语言提供的迭代 API。但对于不熟悉 C 或 C++ 的用户，Cython 是一种性能折衷方案，可以获得不错的性能。
对于nditer对象，这意味着让迭代器处理广播、dtype 转换和缓冲，同时将内部循环交给 Cython。
示例
>>> def axis_to_axeslist(axis, ndim):
... if axis is None:
... return [-1] * ndim
... else:
... if type(axis) is not tuple:
... axis = (axis,)
... axeslist = [1] * ndim
... for i in axis:
... axeslist[i] = -1
... ax = 0
... for i in range(ndim):
... if axeslist[i] != -1:
... axeslist[i] = ax
... ax += 1
... return axeslist
...
>>> def sum_squares_py(arr, axis=None, out=None):
... axeslist = axis_to_axeslist(axis, arr.ndim)
... it = np.nditer([arr, out], flags=['reduce_ok',
... 'buffered', 'delay_bufalloc'],
... op_flags=[['readonly'], ['readwrite', 'allocate']],
... op_axes=[None, axeslist],
... op_dtypes=['float64', 'float64'])
... with it:
... it.operands[1][...] = 0
... it.reset()
... for x, y in it:
... y[...] += x*x
... return it.operands[1]
...
>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_py(a)
array(55.)
>>> sum_squares_py(a, axis=-1)
array([ 5., 50.])
在本例中，我们将创建一个平方和函数。首先，让我们用简单的 Python 实现此函数。我们希望支持类似于 NumPy sum 函数的“axis”参数，因此我们需要为op_axes参数构造一个列表。以下是实现方式。
要将此函数 Cython 化，我们将内部循环 (y[…] += x*x) 替换为针对 float64 dtype 优化的 Cython 代码。启用“external_loop”标志后，提供给内部循环的数组将始终是一维的，因此只需要进行很少的检查。
import numpy as np
cimport numpy as np
cimport cython
def axis_to_axeslist(axis, ndim):
if axis is None:
return [-1] * ndim
else:
if type(axis) is not tuple:
axis = (axis,)
axeslist = [1] * ndim
for i in axis:
axeslist[i] = -1
ax = 0
for i in range(ndim):
if axeslist[i] != -1:
axeslist[i] = ax
ax += 1
return axeslist
@cython.boundscheck(False)
def sum_squares_cy(arr, axis=None, out=None):
cdef np.ndarray[double] x
cdef np.ndarray[double] y
cdef int size
cdef double value
axeslist = axis_to_axeslist(axis, arr.ndim)
it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop',
'buffered', 'delay_bufalloc'],
op_flags=[['readonly'], ['readwrite', 'allocate']],
op_axes=[None, axeslist],
op_dtypes=['float64', 'float64'])
with it:
it.operands[1][...] = 0
it.reset()
for xarr, yarr in it:
x = xarr
y = yarr
size = x.shape[0]
for i in range(size):
value = x[i]
y[i] = y[i] + value * value
return it.operands[1]
以下是 sum_squares.pyx 的代码清单。
$ cython sum_squares.pyx
$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -I/usr/include/python2.7 -fno-strict-aliasing -o sum_squares.so sum_squares.c
在本机上，将 .pyx 文件构建成模块的过程如下所示，但您可能需要查找一些 Cython 教程来了解您的系统配置的具体细节。
示例
>>> from sum_squares import sum_squares_cy
>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_cy(a)
array(55.0)
>>> sum_squares_cy(a, axis=-1)
array([ 5., 50.])
从 Python 解释器运行此代码将产生与我们的原生 Python/NumPy 代码相同的答案。
>>> a = np.random.rand(1000,1000)
>>> timeit sum_squares_py(a, axis=-1)
10 loops, best of 3: 37.1 ms per loop
>>> timeit np.sum(a*a, axis=-1)
10 loops, best of 3: 20.9 ms per loop
>>> timeit sum_squares_cy(a, axis=-1)
100 loops, best of 3: 11.8 ms per loop
>>> np.all(sum_squares_cy(a, axis=-1) == np.sum(a*a, axis=-1))
True
>>> np.all(sum_squares_py(a, axis=-1) == np.sum(a*a, axis=-1))
True