NumPy 1.26 中文文档（五）

原文：numpy.org/doc/

NumPy 许可证

原文：numpy.org/doc/1.26/license.html

Copyright (c) 2005-2023, NumPy Developers.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

    * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above
       copyright notice, this list of conditions and the following
       disclaimer in the documentation and/or other materials provided
       with the distribution.

    * Neither the name of the NumPy Developers nor the names of any
       contributors may be used to endorse or promote products derived
       from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

NumPy 参考

原文：numpy.org/doc/1.26/reference/index.html

发布：

1.26

日期：

2023 年 9 月 16 日

此参考手册详细介绍了 NumPy 中包含的函数、模块和对象，描述了它们的作用和功能。要了解如何使用 NumPy，请参阅完整文档。

• 数组对象
  • N 维数组 (ndarray)
  • 标量
  • 数据类型对象 (dtype)
  • 索引例程
  • 对数组进行迭代
  • 标准数组子类
  • 掩码数组
  • 数组接口协议
  • 日期时间和时间增量
• 数组 API 标准兼容性
  • numpy.array_api 和 numpy 之间的差异表
• 常量
  • Inf
  • Infinity
  • NAN
  • NINF
  • NZERO
  • NaN
  • PINF
  • PZERO
  • e
  • euler_gamma
  • inf
  • infty
  • nan
  • newaxis
  • pi
• 通用函数 (ufunc)
  • ufunc
  • 可用的通用函数
• 例程
  • 数组创建例程
  • 数组操作例程
  • 二进制操作
  • 字符串操作
  • C 类型外部函数接口 (numpy.ctypeslib)
  • 日期时间支持函数
  • 数据类型例程
  • 带有自动域的数学函数
  • 浮点数错误处理
  • 离散傅里叶变换 (numpy.fft)
  • 函数式编程
  • NumPy 特定的帮助函数
  • 输入和输出
  • 线性代数 (numpy.linalg)
  • 逻辑函数
  • 掩码数组操作
  • 数学函数
  • 矩阵库 (numpy.matlib)
  • 杂项例程
  • 填充数组
  • 多项式
  • 随机抽样 (numpy.random)
  • 集合例程
  • 排序、搜索和计数
  • 统计
  • 测试支持（numpy.testing）
  • 对测试覆盖（numpy.testing.overrides）的支持
  • 窗口函数
• 键入（numpy.typing）
  • Mypy 插件
  • 与运行时 NumPy API 的差异
  • API
• 全局状态](global_state.html)
  • 与性能相关的选项
  • 与调试相关的选项
  • 测试计划的未来行为
• 打包（numpy.distutils）
  • numpy.distutils 中的模块
  • 配置类
  • 构建可安装的 C 库
  • .src 文件的转换
• NumPy distutils - 用户指南
  • SciPy 结构
  • SciPy 包的要求
  • The setup.py 文件
  • The __init__.py 文件
  • NumPy Distutils 的额外功能
• numpy.distutils 的状态和迁移建议
  • 迁移建议
  • numpy.distutils 与 setuptools 的交互
• NumPy C-API
  • Python 类型和 C 结构
  • 系统配置
  • 数据类型 API
  • 数组 API
  • 数组迭代器 API
  • 通用函数 API
  • 广义通用函数 API
  • NumPy 核心库
  • C API 弃用
  • NumPy 的内存管理
• CPU/SIMD 优化
  • CPU 构建选项
  • CPU 调度程序如何工作？
• NumPy 安全性
  • 在不受信任的数据上使用 NumPy 的建议
• NumPy 和 SWIG
  • numpy.i：NumPy 的 SWIG 接口文件
  • 测试 numpy.i 类型映射

致谢

本手册的大部分内容源自特拉维斯·E·奥利芬特（Travis E. Oliphant）的书籍《NumPy 指南》(https://archive.org/details/NumPyBook)（于 2008 年 8 月慷慨地进入公共领域）。许多函数的参考文档是由众多 NumPy 的贡献者和开发人员编写的。

致谢

本手册的大部分内容来源于 Travis E. Oliphant 的书籍《NumPy 指南》（这本书在 2008 年 8 月慷慨地进入了公有领域）。许多函数的参考文档由 NumPy 的许多贡献者和开发人员编写。

数组对象

原文：numpy.org/doc/1.26/reference/arrays.html

NumPy 提供了一个 N 维数组类型，即 ndarray，它描述了相同类型的“项”的集合。这些项可以使用 N 个整数之类的值进行索引。

所有 ndarrays 都是同构的：每个项目占用相同大小的内存块，并且所有块的解释方式完全相同。如何解释数组中的每个项目由一个单独的数据类型对象指定，其中每个数组都关联有一个数据类型对象。除了基本类型（整数、浮点数等），数据类型对象还可以表示数据结构。

通过索引等方式从数组中提取的项目由一个 Python 对象表示，其类型是 NumPy 中内置的数组标量类型之一。数组标量可以轻松操作更复杂的数据排列。

../_images/threefundamental.png

图：概念图展示了描述数组中数据的三个基本对象之间的关系：1）ndarray 本身，2）描述数组中单个固定大小元素布局的数据类型对象，3）当访问数组的单个元素时返回的数组标量 Python 对象。

• N 维数组(ndarray)
  • 构造数组
  • 数组索引
  • ndarray 的内部内存布局
  • 数组属性
  • 数组方法
  • 算术、矩阵乘法和比较操作
  • 特殊方法
• 标量
  • 内置标量类型
  • 属性
  • 索引
  • 方法
  • 定义新类型
• 数据类型对象(dtype)
  • 指定和构造数据类型
  • dtype
• 索引例程
  • 生成索引数组
  • 类似索引的操作
  • 向数组中插入数据
  • 数组遍历
• 数组遍历
  • 单数组迭代
  • 广播数组迭代
  • 将内循环置于 Cython 中
• 标准数组子类
  • 特殊属性和方法
  • 矩阵对象
  • 内存映射文件数组
  • 字符数组 (numpy.char)
  • 记录数组 (numpy.rec)
  • 掩码数组 (numpy.ma)
  • 标准容器类
  • 数组迭代器
• 掩码数组
  • numpy.ma 模块
  • 使用 numpy.ma
  • 示例
  • numpy.ma 模块的常量
  • MaskedArray 类
  • MaskedArray 方法
  • 掩码数组操作
• 数组接口协议
  • Python 端
  • C 结构访问
  • 类型描述示例
  • 与数组接口（版本 2）的差异
• 日期时间和时间增量
  • Datetime64 约定和假设
  • 基本日期时间
  • 日期时间和时间增量算术
  • 日期时间单位
  • 工作日功能
  • Datetime64 的缺点

N 维数组（ndarray）

译文：numpy.org/doc/1.26/reference/arrays.ndarray.html

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

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

不同的ndarrays可以共享相同的数据，因此在一个ndarray中所做的更改可能在另一个中可见。也就是说，ndarray 可以是另一个 ndarray 的*“视图”，它所引用的数据由“基本”* ndarray 处理。ndarray 也可以是 Python字符串或实现buffer或 array 接口的对象的内存视图。

例子

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

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

构建数组

可以使用 Array creation routines 中详细介绍的例程构建新数组，也可以使用低级ndarray构造函数：

数组索引

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

另请参阅

数组索引。## ndarray 的内部内存布局

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

内存的一部分本质上是 1 维的，对于N维数组，有许多不同的方案来在 1 维块中排列数组的元素。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 顺序都是连续的，即单片段的内存布局，其中内存块的每个部分都可以通过一些索引的组合来访问。

注意

Contiguous arrays 和 single-segment arrays 是同义词，在整个文档中可以互换使用。

虽然 C 风格和 Fortran 风格的连续数组拥有相应的标志位，可以通过上述步幅来访问，但实际步幅可能是不同的。这种情况可能出现在两种情况下：

1. 如果 self.shape[k] == 1，那么对于任何合法的索引 index[k] == 0。这意味着在偏移量的公式中 (n_k = 0)，因此 (s_k n_k = 0)，而 (s_k) = self.strides[k] 是任意的值。
2. 如果一个数组没有元素（self.size == 0），那么没有合法的索引，步幅也不会被使用。任何没有元素的数组都可以被视为 C 风格和 Fortran 风格的连续数组。

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

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

警告

对于 C 风格连续数组，通常不成立self.strides[-1] == self.itemsize或者对于 Fortran 风格连续数组self.strides[0] == self.itemsize。

NPY_RELAXED_STRIDES_DEBUG=1可用于帮助找到在 C 扩展代码中错误地依赖步幅时的错误（见下面的警告）。

新ndarrays中的数据按行主序©存储，除非另有规定，但是，例如，基本数组切片通常会产生不同方案的视图。

注意

NumPy 中的多种算法适用于任意步幅的数组。然而，一些算法需要单段数组。当不规则步幅的数组传递给此类算法时，将自动进行复制。## 数组属性

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

内存布局

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

数据类型

另请参见

数据类型对象

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

其他属性

数组接口

另请参阅

数组接口协议.

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, ptp, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.

数组转换

Shape manipulation

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

项目选择和操作

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

计算

许多方法都带有名为 axis 的参数。在这种情况下，

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

axis 参数的示例

一个大小为 3 x 3 x 3 的三维数组，沿着其三个轴进行求和

>>> 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，并且具有相同数量的元素。 它可以具有不同的数据类型，在这种情况下将执行强制转换。

算术运算、矩阵乘法和比较操作

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

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

比较运算符：

数组的布尔值（bool()）：

注意

对数组的真值测试调用ndarray.__bool__，如果数组中的元素数量大于 1，会引发错误，因为这些数组的真值是不明确的。在这种情况下，应该使用.any()和.all()来明确表示意思（如果元素的数量为 0，则数组的值为False）。

一��操作：

算术运算：

注意

• pow 的第三个参数被悄悄忽略，因为底层的 ufunc 只接受两个参数。
• 因为 ndarray 是一个内置类型（用 C 编写），__r{op}__ 特殊方法不是直接定义的。
• 通过使用 __array_ufunc__ 可以修改为数组实现许多算术特殊方法的函数。

算术，原地：

警告

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

矩阵乘法：

注意

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

特殊方法

对于标准库函数：

基本自定义：

容器定制：（参见索引）

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

字符串表示：

输入数组的实用方法：

构建数组

可以使用数组创建例程中详细描述的例程构建新数组，也可以使用低级别的ndarray构造器：

数组索引

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

另请参见

数组索引。

ndarray 的内部内存布局

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

内存段本质上是一维的，有许多不同的方案可以将 N 维数组的条目排列在一维块中。NumPy 是灵活的，ndarray 对象可以适应任何跨步索引方案。在跨步方案中，N 维索引 ((n_0, n_1, …, n_{N-1})) 对应于偏移量（以字节表示）：

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

从与数组关联的内存块的起始位置开始计算。这里，(s_k) 是指定数组的 strides 的整数。列优先顺序（例如，在 Fortran 语言和* Matlab 中使用）和行优先顺序（在 C 中使用）方案只是特定类型的跨步方案，并且对应于可以通过跨步寻址*的内存：

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

这里的 (d_j) = self.shape[j]。

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

注意

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

尽管 C 风格和 Fortran 风格的连续数组具有相应的标志设置，可以通过上述步幅进行寻址，但实际的步幅可能不同。这种情况可能发生在两种情况下：

1. 如果 self.shape[k] == 1，则对于任何合法索引 index[k] == 0。这意味着在偏移量的公式中 (n_k = 0)，因此 (s_k n_k = 0)，而 (s_k) 的值 = self.strides[k] 是任意的。
3. 如果一个数组没有元素（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 风格连续数组是正确的。

可以使用NPY_RELAXED_STRIDES_DEBUG=1来帮助找到在 C 扩展代码中错误依赖步幅时的错误（见下面的警告）。

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

注意

NumPy 中的几个算法适用于任意步幅的数组。然而，一些算法需要单一段数组。当一个不规则步幅的数组传递给这样的算法时，会自动进行复制。

数组属性

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

内存布局

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

数据类型

另请参见

数据类型对象

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

其他属性

数组接口

另请参见

数组接口协议。

ctypes 外部函数接口

内存布局

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

数据类型

另请参见

数据类型对象

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

其他属性

数组接口

另请参见

数组接口协议。

ctypes 外部函数接口

数组方法

一个ndarray对象具有许多操作数组的方法，通常以某种方式返回数组结果。以下简要解释了这些方法（每个方法的文档字符串有更完整的描述）。

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

数组转换

形状操作

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

项目选择和操作

对于带有 axis 关键字的数组方法，默认为 None。如果 axis 为 None，则将数组视为 1-D 数组。axis 的任何其他值表示应沿其进行操作的维度。

计算

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

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

axis参数的示例

一个尺寸为 3 x 3 x 3 的 3 维数组，对其三个轴进行求和

>>> 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，并且具有相同数量的元素。 它可以具有不同的数据类型，在这种情况下将执行强制转换。

数组转换

形状操作

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

项目选择和操作

对于带有axis关键字的数组方法，默认值为None。如果axis为None，则将数组视为 1-D 数组。对于axis的任何其他值表示应该进行操作的维度。

计算

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

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

axis参数的示例

大小为 3 x 3 x 3 的三维数组，沿其三个轴求和

>>> 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，并且具有相同数量的元素。它可以具有不同的数据类型，这种情况下会执行强转换。

算术，矩阵乘法和比较操作

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

每个算术操作(+, -, *, /, //, %, divmod(), **或pow(), <<, >>, &, ^, |, ~)和比较(==, <, >, <=, >=, !=)都等同于 NumPy 中相应的通用函数(或 ufunc)。更多信息，请参见通用函数部分。

比较运算符:

数组的真值（bool())：

注意

对数组进行真值测试时会调用 ndarray.__bool__，如果数组中的元素数量大于 1，则会引发错误，因为这种情况下数组的真值是不确定的。可以使用.any()和.all()来明确表示在这种情况下的意思。（如果元素数量为 0，则数组的值为False。）

一元操作：

算术运算：

注意

• pow 的第三个参数被默默忽略，因为底层的 ufunc 只接受两个参数。
• 因为 ndarray 是一个内置类型（用 C 编写），因此直接定义了 __r{op}__ 特殊方法。
• 通过使用 __array_ufunc__，可以修改数组的许多算术特殊方法调用的函数。

算术，就地运算：

警告

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

矩阵乘法：

注意

在 Python 3.5 中引入了矩阵运算符@和@=，遵循了PEP 465，而@操作符在 NumPy 1.10.0 中被引入。更多信息可以在matmul文档中找到。

特殊方法

对于标准库函数：

基本定制：

容器定制：（参见 Indexing）

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

字符串表示:

类型的实用方法:

numpy.ndarray

numpy.org/doc/1.26/reference/generated/numpy.ndarray.html

class numpy.ndarray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

一个数组对象表示固定大小项的多维、同构数组。一个关联的数据类型对象描述了数组中每个元素的格式（它的字节顺序、它在内存中占用多少字节、它是整数、浮点数还是其他内容等等）。

数组应该使用 array、zeros 或 empty 来构造（请参阅下面的参考部分）。这里给出的参数指的是用于实例化数组的低级方法（*ndarray(…)）。

更多信息，请参考 numpy 模块并检查数组的方法和属性。

参数：

（对于 new 方法；看下面的注意）**

shape 一组整数

创建数组的形状。

dtype 数据类型，可选

任何可以被解释为 numpy 数据类型的对象。

buffer 暴露缓冲区接口的对象，可选

用于用数据填充数组。

offset 整数，可选

数组数据在缓冲区中的偏移量。

strides 一组整数，可选

内存中数据的步幅。

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

行主要（C 风格）或列主要（Fortran 风格）顺序。

参见

array

构造一个数组。

zeros

创建一个每个元素都为零的数组。

empty

创建一个数组，但不改变其已分配的内存（也就是说，它包含“垃圾”）。

dtype

创建数据类型。

numpy.typing.NDArray

一个关于其 dtype.type 的别名的 ndarray 泛型。

注意事项

有两种使用 __new__ 创建数组的模式：

1. 如果 buffer 为 None，则只使用 shape、dtype 和 order。
2. 如果 buffer 是一个暴露缓冲区接口的对象，则所有关键字都会被解释。

不需要 __init__ 方法，因为在 __new__ 方法之后数组已完全初始化。

例子

这些示例说明了使用底层 ndarray 构造函数。请参考上面的 参考 部分以了解更简单的构建 ndarray 的方法。

第一种模式，buffer 为 None：

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
 [     nan, 2.5e-323]]) 

第二种模式：

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3]) 

属性：

T ndarray

转置数组的视图。

data 缓冲区

指向数组数据起始位置的 Python 缓冲区对象。

dtypedtype 对象

数组元素的数据类型。

flagsdict

数组的内存布局信息。

flatnumpy.flatiter 对象

数组的一维迭代器。

imagndarray

数组的虚部。

realndarray

数组的实部。

sizeint

数组中的元素数。

itemsizeint

一个数组元素的字节数。

nbytesint

数组元素所消耗的总字节数。

ndimint

数组的维度数。

shapeint 元组

数组的维度的元组。

stridesint 元组

在遍历数组时在每个维度中步进的字节数元组。

ctypesctypes 对象

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

basendarray

如果内存来自其他对象，则是基础对象。

方法

numpy.ndarray.flags

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.flags.html

属性

ndarray.flags

数组的内存布局信息。

注意事项

flags 对象可以像字典一样访问（如a.flags['WRITEABLE']），也可以使用小写属性名称（如a.flags.writeable）。只支持字典访问的短标志名称。

只能通过直接分配给属性或字典条目，或通过调用ndarray.setflags来更改 WRITEBACKIFCOPY、WRITEABLE 和 ALIGNED 标志。

数组的标志不能随意设置：

• WRITEBACKIFCOPY 只能设置为False。
• 只有数据真正对齐时，ALIGNED 才能设置为True。
• 只有当数组拥有自己的内存或内存的最终所有者暴露了可写入的缓冲区接口，或者是一个字符串时，WRITEABLE 才能设置为True。

数组可以同时是 C 风格和 Fortran 风格连续的。这对于 1 维数组是清楚的，但对于更高维数组也可能为真。

即使对于连续的数组，对于给定维度arr.strides[dim]的步幅可能是任意的，如果arr.shape[dim] == 1或数组没有元素。对于 C 风格连续数组或 Fortran 风格连续数组，通常不成立self.strides[-1] == self.itemsize（对于 C 风格连续数组）或self.strides[0] == self.itemsize（对于 Fortran 风格连续数组）。

属性：

C_CONTIGUOUS ©

数据在一个单一的、符合 C 风格的连续段中。

F_CONTIGUOUS (F)

数据在一个单一的、符合 Fortran 风格的连续段中。

OWNDATA (O)

数组拥有它使用的内存或从另一个对象借用它。

WRITEABLE (W)

数据区域可以被写入。将其设置为 False 会锁定数据，使之为只读。视图（切片等）在创建时从其基础数组继承 WRITEABLE，但对于可写数组的视图可以随后被锁定，而基础数组保持可写。 （相反则不成立，即不能将视图从只读数组改为可写。但是，目前锁定基对象不会锁定已引用它的任何视图，因此在这种情况下，通过之前创建的视图可以更改被锁定数组的内容。）尝试更改不可写数组会引发 RuntimeError 异常。

ALIGNED (A)

数据和所有元素都与硬件适当地对齐。

WRITEBACKIFCOPY (X)

这个数组是另一个数组的副本。在释放内存之前必须调用 C-API 函数 PyArray_ResolveWritebackIfCopy，以便将基础数组更新为此数组的内容。

FNC

F_CONTIGUOUS 而不是 C_CONTIGUOUS。

FORC

F_CONTIGUOUS 或 C_CONTIGUOUS���单一段测试）。

BEHAVED (B)

ALIGNED 和 WRITEABLE。

CARRAY (CA)

BEHAVED 和 C_CONTIGUOUS。

FARRAY (FA)

BEHAVED 和 F_CONTIGUOUS，但不是 C_CONTIGUOUS。

numpy.ndarray.shape

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.shape.html

attribute

ndarray.shape

Tuple of array dimensions.

The shape property is usually used to get the current shape of an array, but may also be used to reshape the array in-place by assigning a tuple of array dimensions to it. As with numpy.reshape, one of the new shape dimensions can be -1, in which case its value is inferred from the size of the array and the remaining dimensions. Reshaping an array in-place will fail if a copy is required.

Warning

Setting arr.shape is discouraged and may be deprecated in the future. Using ndarray.reshape is the preferred approach.

See also

numpy.shape

Equivalent getter function.

numpy.reshape

Function similar to setting shape.

ndarray.reshape

Method similar to setting shape.

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
 [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
 [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged
>>> np.zeros((4,2))[::2].shape = (-1,)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: Incompatible shape for in-place modification. Use
`.reshape()` to make a copy with the desired shape. 

numpy.ndarray.strides

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.strides.html

属性

ndarray.strides

在遍历数组时，每个维度步进的字节数元组。

元素(i[0], i[1], ..., i[n])在数组a中的字节偏移量为：

offset = sum(np.array(i) * a.strides) 

在 NumPy 参考指南的“ndarray.rst”文件中可以找到更详细的关于步幅的解释。

警告

设置arr.strides是不鼓励的，可能会在将来被弃用。应该优先选择numpy.lib.stride_tricks.as_strided以更安全的方式创建同一数据的新视图。

另请参阅

numpy.lib.stride_tricks.as_strided

注意

想象一个 32 位整数数组（每个 4 个字节）：

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32) 

这个数组以 40 个字节的形式依次存储在内存中（称为连续的内存块）。数组的步幅告诉我们在内存中移动到特定轴上的下一个位置时需要跳过多少字节。例如，我们需要跳过 4 个字节（1 个值）才能移动到下一列，但是要跳过 20 个字节（5 个值）才能到达下一行的相同位置。因此，数组x的步幅将为(20, 4)。

实例

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
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]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17 

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813 

numpy.ndarray.ndim

numpy.org/doc/1.26/reference/generated/numpy.ndarray.ndim.html

属性

ndarray.ndim

数组的维度数量。

示例

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3 

numpy.ndarray.data

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.data.html

属性

ndarray.data

指向数组数据起始位置的 Python 缓冲对象。

numpy.ndarray.size

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.size.html

属性

ndarray.size

数组中的元素数量。

等同于np.prod(a.shape)，即数组维度的乘积。

注意事项

a.size 返回一个标准的任意精度 Python 整数。这在使用其他方法获取相同值时可能不成立（比如建议的np.prod(a.shape)，它返回一个np.int_的实例），这在进一步计算中可能会溢出固定大小的整数类型时可能会有影响。

示例

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30 

numpy.ndarray.itemsize

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.itemsize.html

属性

ndarray.itemsize

一个数组元素的长度（以字节为单位）。

示例

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16 

numpy.ndarray.nbytes

numpy.org/doc/1.26/reference/generated/numpy.ndarray.nbytes.html

属性

ndarray.nbytes

数组元素所占用的总字节数。

另请参见

sys.getsizeof

对象本身在视图情况下没有父级所占用的内存。这包括非元素属性所占用的内存。

注释

不包括数组对象的非元素属性所占用的内存。

例子

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480 

numpy.ndarray.base

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.base.html

属性

ndarray.base

如果内存来自其他对象，则为基本对象。

示例

拥有自己内存的数组的基本对象为 None：

>>> x = np.array([1,2,3,4])
>>> x.base is None
True 

切片创建一个视图，其内存与 x 共享：

>>> y = x[2:]
>>> y.base is x
True 

numpy.ndarray.dtype

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.dtype.html

属性

ndarray.dtype

数组元素的数据类型。

警告

不建议设置arr.dtype，未来可能会弃用。设置会替换dtype但不修改内存（另请参阅ndarray.view和ndarray.astype）。

参数：

None

返回：

dnumpy dtype 对象

另请参阅

ndarray.astype

将数组中包含的值强制转换为新的数据类型。

ndarray.view

创建一个相同数据的视图，但数据类型不同。

numpy.dtype

示例

>>> x
array([[0, 1],
 [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'> 

numpy.ndarray.T

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.T.html

属性

ndarray.T

转置数组的视图。

与 self.transpose() 相同。

参见

transpose

例子

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
 [3, 4]])
>>> a.T
array([[1, 3],
 [2, 4]]) 

>>> a = np.array([1, 2, 3, 4])
>>> a
array([1, 2, 3, 4])
>>> a.T
array([1, 2, 3, 4]) 

numpy.ndarray.real

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.real.html

属性

ndarray.real

数组的实部。

另请参阅

numpy.real

等效函数

示例

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1\.        ,  0.70710678])
>>> x.real.dtype
dtype('float64') 

s 480

np.prod(x.shape) * x.itemsize 480

# `numpy.ndarray.base`

> 原文：[`numpy.org/doc/1.26/reference/generated/numpy.ndarray.base.html`](https://numpy.org/doc/1.26/reference/generated/numpy.ndarray.base.html)

属性

```py
ndarray.base

如果内存来自其他对象，则为基本对象。

示例

拥有自己内存的数组的基本对象为 None：

>>> x = np.array([1,2,3,4])
>>> x.base is None
True 

切片创建一个视图，其内存与 x 共享：

>>> y = x[2:]
>>> y.base is x
True 

numpy.ndarray.dtype

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.dtype.html

属性

ndarray.dtype

数组元素的数据类型。

警告

不建议设置arr.dtype，未来可能会弃用。设置会替换dtype但不修改内存（另请参阅ndarray.view和ndarray.astype）。

参数：

None

返回：

dnumpy dtype 对象

另请参阅

ndarray.astype

将数组中包含的值强制转换为新的数据类型。

ndarray.view

创建一个相同数据的视图，但数据类型不同。

numpy.dtype

示例

>>> x
array([[0, 1],
 [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'> 

numpy.ndarray.T

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.T.html

属性

ndarray.T

转置数组的视图。

与 self.transpose() 相同。

参见

transpose

例子

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
 [3, 4]])
>>> a.T
array([[1, 3],
 [2, 4]]) 

>>> a = np.array([1, 2, 3, 4])
>>> a
array([1, 2, 3, 4])
>>> a.T
array([1, 2, 3, 4]) 

numpy.ndarray.real

原文：numpy.org/doc/1.26/reference/generated/numpy.ndarray.real.html

属性

ndarray.real

数组的实部。

另请参阅

numpy.real

等效函数

示例

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1\.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')