N 维数组 (`ndarray`)#

ndarray 是一个（通常是固定大小的）多维容器，包含相同类型和大小的项目。数组的维度和项目数由其 shape 定义，shape 是一个包含 N 个非负整数的 tuple，指定每个维度的尺寸。数组中项目的类型由单独的数据类型对象 (dtype) 指定，每个 ndarray 都关联一个数据类型对象。

与 Python 中的其他容器对象一样，可以通过索引或切片数组（例如，使用 N 个整数）以及 ndarray 的方法和属性来访问和修改 ndarray 的内容。

不同的 ndarrays 可以共享相同的数据，因此在一个 ndarray 中进行的更改可能会在另一个 ndarray 中可见。也就是说，ndarray 可以是另一个 ndarray 的 “视图”，它引用的数据由 “基础” ndarray 管理。ndarrays 也可以是 Python 字符串 或实现 memoryview 或数组接口的对象所拥有的内存的视图。

示例

一个大小为 2 x 3 的二维数组，由 4 字节整数元素组成

>>> import numpy as np

>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
<class 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')

可以使用 Python 容器式语法对数组进行索引

>>> # The element of x in the *second* row, *third* column, namely, 6.
>>> x[1, 2]
   6

例如，切片可以生成数组的视图

>>> y = x[:,1]
>>> y
array([2, 5], dtype=int32)
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5], dtype=int32)
>>> x
array([[1, 9, 3],
       [4, 5, 6]], dtype=int32)

构建数组#

可以使用数组创建例程中详述的例程以及低级 ndarray 构造函数来构建新的数组

ndarray(shape[, dtype, buffer, offset, ...])

数组对象表示一个多维、同构的固定大小项目数组。

索引数组#

可以使用扩展的 Python 切片语法 array[selection] 对数组进行索引。类似的语法也用于访问结构化数据类型中的字段。

另请参阅

数组索引.

ndarray 的内部内存布局#

类 ndarray 的实例由计算机内存的一个连续的一维片段（由数组或其他对象拥有）以及一个索引方案组成，该索引方案将 N 个整数映射到块中项目的地址。索引可以变化的范围由数组的 shape 指定。每个项目占用多少字节以及如何解释这些字节由与数组关联的数据类型对象定义。

内存段本质上是一维的，并且有许多不同的方案用于在连续的一维块中排列 N 维数组的项目。NumPy 具有灵活性，ndarray 对象可以适应任何 步长索引方案。在步长方案中，N 维索引 \((n_0, n_1, ..., n_{N-1})\) 对应于偏移量（以字节为单位）

\[n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k\]

从与数组关联的内存块的开头开始。这里，\(s_k\) 是指定数组 strides 的整数。列主序（例如，在 Fortran 语言和 Matlab 中使用）和行主序（在 C 中使用）方案只是特定类型的步长方案，并且对应于可以通过步长寻址的内存

\[s_k^{\mathrm{column}} = \mathrm{itemsize} \prod_{j=0}^{k-1} d_j , \quad s_k^{\mathrm{row}} = \mathrm{itemsize} \prod_{j=k+1}^{N-1} d_j .\]

其中 \(d_j\) = self.shape[j]。

C 和 Fortran 顺序都是连续的，即，单段内存布局，其中内存块的每个部分都可以通过索引的某种组合来访问。

注意

连续数组和 单段数组是同义词，在整个文档中可以互换使用。

虽然设置了相应标志的 C 样式和 Fortran 样式的连续数组可以通过上述步长进行寻址，但实际的步长可能不同。这可能发生在以下两种情况下

如果 self.shape[k] == 1，则对于任何合法索引 index[k] == 0。这意味着在偏移量公式中 \(n_k = 0\)，因此 \(s_k n_k = 0\)，并且 \(s_k\) = self.strides[k] 的值是任意的。
如果数组没有元素 (self.size == 0)，则没有合法索引，并且步长从未使用过。任何没有元素的数组都可以被认为是 C 样式和 Fortran 样式的连续的。

第 1 点意味着 self 和 self.squeeze() 始终具有相同的连续性和 aligned 标志值。这也意味着，即使是高维数组也可以同时是 C 样式和 Fortran 样式的连续的。

如果所有元素的内存偏移量以及基础偏移量本身都是 self.itemsize 的倍数，则认为数组是已对齐的。了解 内存对齐 可以在大多数硬件上获得更好的性能。

警告

通常情况下，self.strides[-1] == self.itemsize 对于 C 样式的连续数组或 self.strides[0] == self.itemsize 对于 Fortran 样式的连续数组是成立的。

新 ndarrays 中的数据按行主序（C）排序，除非另有指定，但是，例如，基本数组切片通常会生成采用不同方案的视图。

注意

NumPy 中的几种算法适用于任意步长的数组。但是，某些算法需要单段数组。当将不规则步长的数组传递给此类算法时，会自动创建副本。

数组属性#

数组属性反映了数组本身固有的信息。通常，通过其属性访问数组允许您获取并有时设置数组的固有属性，而无需创建新的数组。公开的属性是数组的核心部分，并且只有其中一些属性可以在不创建新数组的情况下有意义地重置。下面提供了有关每个属性的信息。

内存布局#

以下属性包含有关数组内存布局的信息

`ndarray.flags`	有关数组内存布局的信息。
`ndarray.shape`	数组维度的元组。
`ndarray.strides`	遍历数组时每个维度需要步进的字节数的元组。
`ndarray.ndim`	数组维度的数量。
`ndarray.data`	指向数组数据开头的 Python 缓冲区对象。
`ndarray.size`	数组中元素的数量。
`ndarray.itemsize`	一个数组元素的字节长度。
`ndarray.nbytes`	数组元素消耗的总字节数。
`ndarray.base`	如果内存来自其他对象，则为基对象。

数据类型#

另请参阅

数据类型对象

与数组关联的数据类型对象可以在dtype属性中找到

ndarray.dtype

数组元素的数据类型。

其他属性#

`ndarray.T`	转置数组的视图。
`ndarray.real`	数组的实部。
`ndarray.imag`	数组的虚部。
`ndarray.flat`	数组的 1 维迭代器。

数组接口#

另请参阅

数组接口协议.

`__array_interface__`	数组接口的 Python 端
`__array_struct__`	数组接口的 C 端

`ctypes` 外部函数接口#

ndarray.ctypes

一个用于简化数组与 ctypes 模块交互的对象。

数组方法#

一个ndarray对象有许多方法可以以某种方式操作数组或与数组一起操作，通常返回数组结果。这些方法在下面简要说明。（每个方法的文档字符串都有更完整的描述。）

对于以下方法，在numpy中也有相应的函数：all、any、argmax、argmin、argpartition、argsort、choose、clip、compress、copy、cumprod、cumsum、diagonal、imag、max、mean、min、nonzero、partition、prod、put、ravel、real、repeat、reshape、round、searchsorted、sort、squeeze、std、sum、swapaxes、take、trace、transpose、var。

数组转换#

`ndarray.item`(*args)	将数组的一个元素复制到标准 Python 标量并返回它。
`ndarray.tolist`()	将数组作为`a.ndim`级深度的嵌套 Python 标量列表返回。
`ndarray.tostring`([order])	与`tobytes`完全相同的行为的兼容别名。
`ndarray.tobytes`([order])	构造包含数组中原始数据字节的 Python 字节。
`ndarray.tofile`(fid[, sep, format])	将数组作为文本或二进制（默认）写入文件。
`ndarray.dump`(file)	将数组的 pickle 存储到指定的文件中。
`ndarray.dumps`()	将数组的 pickle 作为字符串返回。
`ndarray.astype`(dtype[, order, casting, ...])	数组的副本，转换为指定的类型。
`ndarray.byteswap`([inplace])	交换数组元素的字节
`ndarray.copy`([order])	返回数组的副本。
`ndarray.view`([dtype][, type])	具有相同数据的数组的新视图。
`ndarray.getfield`(dtype[, offset])	将给定数组的字段作为特定类型返回。
`ndarray.setflags`([write, align, uic])	分别设置数组标志 WRITEABLE、ALIGNED、WRITEBACKIFCOPY。
`ndarray.fill`(value)	用标量值填充数组。

形状操作#

对于 reshape、resize 和 transpose，单个元组参数可以用n个整数替换，这些整数将被解释为 n 元组。

`ndarray.reshape`(shape, /, *[, order, copy])	返回一个包含相同数据但具有新形状的数组。
`ndarray.resize`(new_shape[, refcheck])	就地更改数组的形状和大小。
`ndarray.transpose`(*axes)	返回具有转置轴的数组的视图。
`ndarray.swapaxes`(axis1, axis2)	返回一个交换了axis1和axis2的数组视图。
`ndarray.flatten`([order])	返回折叠成一维的数组的副本。
`ndarray.ravel`([order])	返回一个扁平化的数组。
`ndarray.squeeze`([axis])	从a中删除长度为一的轴。

项目选择和操作#

对于采用axis关键字的数组方法，它默认为None。如果 axis 为None，则数组被视为一维数组。axis的任何其他值都表示操作应进行的维度。

`ndarray.take`(indices[, axis, out, mode])	返回一个由给定索引处的a元素组成的数组。
`ndarray.put`(indices, values[, mode])	对于所有n在索引中，将`a.flat[n] = values[n]`。
`ndarray.repeat`(repeats[, axis])	重复数组的元素。
`ndarray.choose`(choices[, out, mode])	使用索引数组从一组选项中构造一个新数组。
`ndarray.sort`([axis, kind, order])	就地排序数组。
`ndarray.argsort`([axis, kind, order])	返回将此数组排序的索引。
`ndarray.partition`(kth[, axis, kind, order])	部分排序数组中的元素，以便第 k 个位置的元素的值位于它在已排序数组中的位置。
`ndarray.argpartition`(kth[, axis, kind, order])	返回将此数组分区的索引。
`ndarray.searchsorted`(v[, side, sorter])	查找应在 a 中插入 v 的元素以保持顺序的索引。
`ndarray.nonzero`()	返回非零元素的索引。
`ndarray.compress`(condition[, axis, out])	沿给定轴返回此数组的选定切片。
`ndarray.diagonal`([offset, axis1, axis2])	返回指定的对角线。

计算#

许多这些方法都采用名为axis的参数。在这种情况下，

如果axis为None（默认值），则数组被视为一维数组，并且操作在整个数组上执行。如果self是一个零维数组或数组标量，此行为也是默认行为。（数组标量是类型/类float32、float64等的实例，而零维数组是包含精确一个数组标量的ndarray实例。）
如果axis是一个整数，则操作在给定的轴上执行（对于沿给定轴可以创建的每个一维子数组）。

axis参数示例

一个大小为3 x 3 x 3的三维数组，在其三个轴上分别求和

>>> import numpy as np

>>> x = np.arange(27).reshape((3,3,3))
>>> x
array([[[ 0,  1,  2],
      [ 3,  4,  5],
      [ 6,  7,  8]],
      [[ 9, 10, 11],
      [12, 13, 14],
      [15, 16, 17]],
      [[18, 19, 20],
      [21, 22, 23],
      [24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
      [36, 39, 42],
      [45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
      [36, 39, 42],
      [45, 48, 51]]),
array([[ 9, 12, 15],
      [36, 39, 42],
      [63, 66, 69]]),
array([[ 3, 12, 21],
      [30, 39, 48],
      [57, 66, 75]]))

参数dtype指定应在其上进行归约操作（如求和）的数据类型。默认的归约数据类型与self的数据类型相同。为了避免溢出，可以使用更大的数据类型执行归约操作。

对于几种方法，还可以提供一个可选的out参数，结果将放置到给定的输出数组中。out参数必须是ndarray，并且具有相同数量的元素。它可以具有不同的数据类型，在这种情况下将执行强制转换。

`ndarray.max`([axis, out, keepdims, initial, ...])	返回沿给定轴的最大值。
`ndarray.argmax`([axis, out, keepdims])	返回沿给定轴的最大值的索引。
`ndarray.min`([axis, out, keepdims, initial, ...])	返回沿给定轴的最小值。
`ndarray.argmin`([axis, out, keepdims])	返回沿给定轴的最小值的索引。
`ndarray.clip`([min, max, out])	返回一个数组，其值限制在`[min, max]`。
`ndarray.conj`()	对所有元素进行复共轭。
`ndarray.round`([decimals, out])	返回a，其中每个元素都四舍五入到给定的十进制位数。
`ndarray.trace`([offset, axis1, axis2, dtype, out])	返回数组对角线上的元素之和。
`ndarray.sum`([axis, dtype, out, keepdims, ...])	返回数组元素沿给定轴的和。
`ndarray.cumsum`([axis, dtype, out])	返回数组元素沿给定轴的累积和。
`ndarray.mean`([axis, dtype, out, keepdims, where])	返回数组元素沿给定轴的平均值。
`ndarray.var`([axis, dtype, out, ddof, ...])	返回数组元素沿给定轴的方差。
`ndarray.std`([axis, dtype, out, ddof, ...])	返回数组元素沿给定轴的标准差。
`ndarray.prod`([axis, dtype, out, keepdims, ...])	返回数组元素沿给定轴的乘积。
`ndarray.cumprod`([axis, dtype, out])	返回数组元素沿给定轴的累积乘积。
`ndarray.all`([axis, out, keepdims, where])	如果所有元素都计算为True，则返回True。
`ndarray.any`([axis, out, keepdims, where])	如果a的任何元素计算为True，则返回True。

算术运算、矩阵乘法和比较运算#

ndarrays上的算术和比较运算被定义为逐元素运算，并且通常会产生ndarray对象作为结果。

每个算术运算（+、-、*、/、//、%、divmod()、**或pow()、<<、>>、&、^、|、~）和比较运算（==、<、>、<=、>=、!=）等价于NumPy中相应的通用函数（或简称ufunc）。有关更多信息，请参见有关通用函数的部分。

比较运算符

`ndarray.__lt__`(value, /)	返回self<value。
`ndarray.__le__`(value, /)	返回self<=value。
`ndarray.__gt__`(value, /)	返回self>value。
`ndarray.__ge__`(value, /)	返回self>=value。
`ndarray.__eq__`(value, /)	返回self==value。
`ndarray.__ne__`(value, /)	返回self!=value。

数组的真值(bool())

ndarray.__bool__(/)

如果self则为True，否则为False

注意

数组的真值测试调用ndarray.__bool__，如果数组中的元素数量大于1，则会引发错误，因为此类数组的真值不明确。使用.any()和.all()来明确在这种情况下意味着什么。（如果元素数量为0，则数组计算为False。）

一元运算

`ndarray.__neg__`(/)	-self
`ndarray.__pos__`(/)	+self
`ndarray.__abs__`(self)
`ndarray.__invert__`(/)	~self

算术运算

`ndarray.__add__`(value, /)	返回self+value。
`ndarray.__sub__`(value, /)	返回self-value。
`ndarray.__mul__`(value, /)	返回self*value。
`ndarray.__truediv__`(value, /)	返回self/value。
`ndarray.__floordiv__`(value, /)	返回self//value。
`ndarray.__mod__`(value, /)	返回self%value。
`ndarray.__divmod__`(value, /)	返回divmod(self, value)。
`ndarray.__pow__`(value[, mod])	返回pow(self, value, mod)。
`ndarray.__lshift__`(value, /)	返回self<<value。
`ndarray.__rshift__`(value, /)	返回self>>value。
`ndarray.__and__`(value, /)	返回self&value。
`ndarray.__or__`(value, /)	返回self\|value。
`ndarray.__xor__`(value, /)	返回self^value。

注意

对pow的任何第三个参数都会被静默忽略，因为底层的ufunc只接受两个参数。
因为ndarray是内置类型（用C编写），所以__r{op}__特殊方法没有直接定义。
用于实现数组的许多算术特殊方法的函数可以使用__array_ufunc__修改。

算术运算，就地运算

`ndarray.__iadd__`(value, /)	返回self+=value。
`ndarray.__isub__`(value, /)	返回self-=value。
`ndarray.__imul__`(value, /)	返回self*=value。
`ndarray.__itruediv__`(value, /)	返回self/=value。
`ndarray.__ifloordiv__`(value, /)	返回self//=value。
`ndarray.__imod__`(value, /)	返回self%=value。
`ndarray.__ipow__`(value, /)	返回self**=value。
`ndarray.__ilshift__`(value, /)	返回self<<=value。
`ndarray.__irshift__`(value, /)	返回self>>=value。
`ndarray.__iand__`(value, /)	返回self&=value。
`ndarray.__ior__`(value, /)	返回 self\|=value。
`ndarray.__ixor__`(value, /)	返回 self^=value。

警告

就地操作将使用两个操作数的数据类型决定的精度执行计算，但会（如果需要）静默地向下转换结果，以便使其可以放回数组中。因此，对于混合精度计算，A {op}= B 可能与 A = A {op} B 不同。例如，假设 a = ones((3,3))。那么，a += 3j 与 a = a + 3j 不同：虽然它们都执行相同的计算，但 a += 3 会将结果转换为适合放回 a 中的类型，而 a = a + 3j 会将名称 a 重新绑定到结果上。

矩阵乘法

ndarray.__matmul__(value, /)

返回 self@value。

注意

矩阵运算符 @ 和 @= 是在 Python 3.5 中引入的，遵循 PEP 465，并且 @ 运算符已在 NumPy 1.10.0 中引入。更多信息可以在 matmul 文档中找到。

特殊方法#

对于标准库函数

`ndarray.__copy__`()	如果在数组上调用 `copy.copy`，则使用此方法。
`ndarray.__deepcopy__`(memo, /)	如果在数组上调用 `copy.deepcopy`，则使用此方法。
`ndarray.__reduce__`()	用于序列化。
`ndarray.__setstate__`(state, /)	用于反序列化。

基本定制

`ndarray.__new__`(args, *kwargs)
`ndarray.__array__`([dtype], *[, copy])	对于 `dtype` 参数，如果未给出 `dtype` 或其与数组的数据类型匹配，则返回对 self 的新引用。
`ndarray.__array_wrap__`(array[, context], /)	返回 `array` 的视图，其类型与 self 相同。

容器定制：(参见索引)

`ndarray.__len__`(/)	返回 len(self)。
`ndarray.__getitem__`(key, /)	返回 self[key]。
`ndarray.__setitem__`(key, value, /)	将 self[key] 设置为 value。
`ndarray.__contains__`(key, /)	返回 key in self。

转换；操作 int()、float() 和 complex()。它们仅适用于包含一个元素的数组，并返回相应的标量。

`ndarray.__int__`(self)
`ndarray.__float__`(self)
`ndarray.__complex__`

字符串表示

`ndarray.__str__`(/)	返回 str(self)。
`ndarray.__repr__`(/)	返回 repr(self)。

用于类型的实用程序方法

ndarray.__class_getitem__(item, /)

返回围绕 ndarray 类型的参数化包装器。

N 维数组 (ndarray)#

构建数组#

索引数组#

ndarray 的内部内存布局#

数组属性#

内存布局#

数据类型#

其他属性#

数组接口#

ctypes 外部函数接口#

数组方法#

数组转换#

形状操作#

项目选择和操作#

计算#

算术运算、矩阵乘法和比较运算#

特殊方法#

N 维数组 (`ndarray`)#

`ctypes` 外部函数接口#