NumPy 1.24 版本说明#

NumPy 1.24.0 版本继续改进数据类型处理和提升，提高执行速度，并阐明文档。由于提升和清理方面的更改，还存在大量新的和已过期的弃用警告。这可能被称为弃用版本。亮点包括：

  • 许多新的弃用警告，请查看。

  • 许多已过期的弃用警告。

  • 新的 F2PY 功能和修复。

  • 堆叠函数的新“dtype”和“casting”关键字。

详情请见下文。

此版本支持 Python 3.8-3.11 版本。

弃用警告#

弃用 numpy.fastCopyAndTranspose 和 PyArray_CopyAndTranspose#

numpy.fastCopyAndTranspose 函数已被弃用。请直接使用相应的复制和转置方法。

arr.T.copy()

NumPy C-API 中的底层 C 函数 PyArray_CopyAndTranspose 也已被弃用。

(gh-22313)

超出范围的 Python 整数的转换#

尝试将 Python 整数转换为 NumPy 值时，现在将始终检查 NumPy 是否可以表示结果。这意味着以下示例将来会失败，现在会给出 DeprecationWarning 警告。

np.uint8(-1)
np.array([3000], dtype=np.int8)

其中许多在以前是成功的。此类代码主要用于具有负值的无符号整数，例如 np.uint8(-1) 给出 np.iinfo(np.uint8).max。

请注意，NumPy 整数之间的转换不受影响，因此 np.array(-1).astype(np.uint8) 继续工作并使用 C 整数溢出逻辑。对于负值，查看数组也能正常工作：np.array(-1, dtype=np.int8).view(np.uint8)。在某些情况下，使用 np.iinfo(np.uint8).max 或 val % 2**8 也可能有效。

在极少数情况下，输入数据可能会混合负值和非常大的无符号值（即 -1 和 2**63）。不幸的是，在这种情况下，必须对 Python 值使用 % 运算符，或者根据是否预期负值使用有符号或无符号转换。

(gh-22385)

弃用 msort#

numpy.msort 函数已被弃用。请改用 np.sort(a, axis=0)。

(gh-22456)

np.str0 等现在已被弃用#

以 0 位大小结尾的标量类型别名：np.object0、np.str0、np.bytes0、np.void0、np.int0、np.uint0 以及 np.bool8 现在已被弃用，最终将被移除。

(gh-22607)

已过期的弃用警告#

  • normed 关键字参数已从 np.histogram、np.histogram2d 和 np.histogramdd 中移除。请改用 density。如果 normed 是通过位置传递的，现在将使用 density。

    (gh-21645)

  • 除非传递 dtype=object，否则参差不齐的数组创建现在将始终引发 ValueError。这包括非常深层嵌套的序列。

    (gh-22004)

  • 已删除对 Visual Studio 2015 及更早版本的支持。

  • 已删除对 Windows Interix POSIX 互操作层面的支持。

    (gh-22139)

  • 已删除对 Cygwin < 3.3 的支持。

    (gh-22159)

  • np.ma.MaskedArray 的 mini() 方法已被移除。请改用 np.ma.MaskedArray.min() 或 np.ma.minimum.reduce()。

  • np.ma.minimum 和 np.ma.maximum 的单参数形式已被移除。请改用 np.ma.minimum.reduce() 或 np.ma.maximum.reduce()。

    (gh-22228)

  • 现在，将除规范的（主要是本机字节序）dtype 实例以外的 dtype 实例传递给 ufunc 中的 dtype= 或 signature= 将引发 TypeError。我们建议传递字符串 "int8" 或标量类型 np.int8，因为从不强制执行字节序、日期时间/时间增量单位等。（最初在 NumPy 1.21 中弃用。）

    (gh-22540)

  • 比较 ufunc 的 dtype= 参数现在已正确应用。这意味着只有 bool 和 object 是有效值，并且强制执行 dtype=object。

    (gh-22541)

  • 对别名 np.object、np.bool、np.float、np.complex、np.str 和 np.int 的弃用已过期（引入 NumPy 1.20）。其中一些现在除了引发错误外还会给出 FutureWarning 警告，因为将来它们将映射到 NumPy 标量。

    (gh-22607)

兼容性说明#

array.fill(scalar) 的行为可能略有不同#

由于逻辑与项目赋值保持一致，numpy.ndarray.fill 在某些情况下行为可能略有不同。

arr = np.array([1])  # with any dtype/value
arr.fill(scalar)
# is now identical to:
arr[0] = scalar

以前，当使用目标 dtype 中无法表示的值或目标具有 object dtype 时，转换可能会产生略微不同的结果。

(gh-20924)

子数组到对象的转换现在会复制#

将包含子数组的 dtype 转换为对象现在将确保复制子数组。以前返回的是不安全的视图。

arr = np.ones(3, dtype=[("f", "i", 3)])
subarray_fields = arr.astype(object)[0]
subarray = subarray_fields[0]  # "f" field

np.may_share_memory(subarray, arr)

现在始终为假。而以前对于特定的转换来说是真。

(gh-21925)

返回的数组尊重 dtype kwarg 对象的唯一性#

当 dtype 关键字参数与 array 或 asarray 一起使用时，返回数组的 dtype 现在始终与调用者提供的 dtype 完全匹配。

在某些情况下，此更改意味着返回的是 _视图_ 而不是输入数组。以下是在 64 位 Linux 上的示例，其中 long 和 longlong 精度相同，但 dtypes 不同。

>>> arr = np.array([1, 2, 3], dtype="long")
>>> new_dtype = np.dtype("longlong")
>>> new = np.asarray(arr, dtype=new_dtype)
>>> new.dtype is new_dtype
True
>>> new is arr
False

在更改之前，dtype 不匹配，因为 new is arr 为 True。

(gh-21995)

DLPack 导出引发 BufferError#

当无法通过 DLPack 导出数组缓冲区时，现在始终会引发 BufferError，而以前会引发 TypeError 或 RuntimeError。这允许在首先尝试 DLPack 后回退到缓冲区协议或 __array_interface__。

(gh-22542)

NumPy 构建不再在 GCC-6 上进行测试#

Ubuntu 18.04 已被 GitHub Actions 弃用，并且 Ubuntu 20.04 上没有 GCC-6，因此不再测试使用该编译器的构建。我们仍然测试使用 GCC-7 和 GCC-8 的构建。

(gh-22598)

新功能#

向多项式类添加了新的属性 symbol#

numpy.polynomial 包中的多项式类新增了一个 symbol 属性，用于表示多项式的未定元。这可以用于在打印时更改变量的值。

>>> P_y = np.polynomial.Polynomial([1, 0, -1], symbol="y")
>>> print(P_y)
1.0 + 0.0·y¹ - 1.0·y²

请注意，多项式类仅支持一维多项式，因此当结果为多元时，涉及具有不同符号的多项式的运算是不允许的。

>>> P = np.polynomial.Polynomial([1, -1])  # default symbol is "x"
>>> P_z = np.polynomial.Polynomial([1, 1], symbol="z")
>>> P * P_z
Traceback (most recent call last)
   ...
ValueError: Polynomial symbols differ

符号可以是任何有效的 Python 标识符。默认值为 symbol=x，与现有行为一致。

(gh-16154)

F2PY 对 Fortran character 字符串的支持#

F2PY 现在支持包装具有以下类型的 Fortran 函数：

  • 字符型 (例如 character x)

  • 字符型数组 (例如 character, dimension(n) :: x)

  • 字符型字符串 (例如 character(len=10) x)

  • 以及字符型字符串数组 (例如 character(len=10), dimension(n, m) :: x)

参数，包括将 Python Unicode 字符串作为 Fortran 字符串参数传递。

(gh-19388)

新函数 np.show_runtime#

新增了一个函数 numpy.show_runtime，用于显示机器的运行时信息，此外还有 numpy.show_config 用于显示与构建相关的信 息。

(gh-21468)

testing.assert_array_equal 的 strict 选项#

testing.assert_array_equal 现在可以使用 strict 选项。设置 strict=True 将禁用标量的广播行为，并确保输入数组具有相同的数据类型。

(gh-21595)

为 np.unique 添加了新参数 equal_nan#

在 1.21 版本中，np.unique 将所有 NaN 值视为相等并返回单个 NaN。设置 equal_nan=False 将恢复 1.21 版本之前的行为，将 NaNs 视为唯一值。默认为 True。

(gh-21623)

numpy.stack 的 casting 和 dtype 关键字参数#

numpy.stack 现在可以使用 casting 和 dtype 关键字参数。要使用它们，请编写 np.stack(..., dtype=None, casting='same_kind')。

numpy.vstack 的 casting 和 dtype 关键字参数#

numpy.vstack 现在可以使用 casting 和 dtype 关键字参数。要使用它们，请编写 np.vstack(..., dtype=None, casting='same_kind')。

numpy.hstack 的 casting 和 dtype 关键字参数#

numpy.hstack 现在可以使用 casting 和 dtype 关键字参数。要使用它们，请编写 np.hstack(..., dtype=None, casting='same_kind')。

(gh-21627)

可以更改单例 RandomState 的底层位生成器#

在 numpy.random 模块中公开的单例 RandomState 实例在启动时使用 MT19937 位生成器初始化。新的函数 set_bit_generator 允许将默认位生成器替换为用户提供的位生成器。引入此函数是为了提供一种方法，允许在新代码中与使用单例提供的随机变量生成函数的现有代码无缝集成高质量的现代位生成器。配套函数 get_bit_generator 返回单例 RandomState 当前使用的位生成器。如果需要，这将简化恢复原始随机性来源的操作。

生成可重复随机数的首选方法是在 Generator 实例中使用现代位生成器。函数 default_rng 简化了实例化过程。

>>> rg = np.random.default_rng(3728973198)
>>> rg.random()

然后可以与单例实例共享相同的位生成器，以便 random 模块中的调用函数将使用相同的位生成器。

>>> orig_bit_gen = np.random.get_bit_generator()
>>> np.random.set_bit_generator(rg.bit_generator)
>>> np.random.normal()

交换是永久性的（直到反转），因此对 random 模块中函数的任何调用都将使用新的位生成器。如果需要代码正确运行，可以恢复原始的位生成器。

>>> np.random.set_bit_generator(orig_bit_gen)

(gh-21976)

np.void 现在具有 dtype 参数#

NumPy 现在允许通过将 dtype 参数传递给 np.void 来直接构造结构化 void 标量。

(gh-22316)

改进#

F2PY 改进#

  • 生成的扩展模块不再使用已弃用的 NumPy-C API。

  • 改进了 f2py 生成的异常消息。

  • 修复了许多 bug 和 flake8 警告。

  • 可以在签名文件的 C 表达式中使用的各种 CPP 宏都以 f2py_ 为前缀。例如，应该使用 f2py_len(x) 而不是 len(x)。

  • 引入了一个新的构造 character(f2py_len=...) 来支持从包装函数返回假定长度的字符型字符串 (例如 character(len=*))。

引入了一个钩子，用于在读取所有输入文件后支持重写 f2py 内部数据结构。例如，这对于 SciPy 支持的 BC 是必需的，其中字符参数在 C 表达式中被视为字符型字符串参数。

(gh-19388)

IBM zSystems 向量扩展功能 (SIMD)#

通过通用内在函数接口，增加了对 zSystem (z13、z14、z15) 的 SIMD 扩展的支持。此支持提高了使用通用内在函数实现的所有 SIMD 内核的性能，包括以下操作：rint、floor、trunc、ceil、sqrt、absolute、square、reciprocal、tanh、sin、cos、equal、not_equal、greater、greater_equal、less、less_equal、maximum、minimum、fmax、fmin、argmax、argmin、add、subtract、multiply、divide。

(gh-20913)

NumPy 现在会在类型转换时给出浮点错误#

在大多数情况下，NumPy 以前在类型转换期间发生浮点警告或错误时不会给出这些警告或错误。例如，像这样的转换：

np.array([2e300]).astype(np.float32)  # overflow for float32
np.array([np.inf]).astype(np.int64)

现在通常会给出浮点警告。这些警告应该会警告发生了浮点溢出。对于将浮点值转换为整数时的错误，用户应该会看到无效值警告。

用户可以使用 np.errstate 修改这些警告的行为。

请注意，对于浮点到整数的转换，给出的确切警告可能取决于平台。例如：

arr = np.full(100, fill_value=1000, dtype=np.float64)
arr.astype(np.int8)

可能会给出等效于 (中间转换意味着没有给出警告) 的结果：

arr.astype(np.int64).astype(np.int8)

可能会返回未定义的结果，并设置警告。

RuntimeWarning: invalid value encountered in cast

精确的行为取决于 C99 标准及其在软件和硬件中的实现。

(gh-21437)

F2PY 支持 value 属性#

Fortran 标准要求声明为 value 属性的变量必须按值传递而不是按引用传递。F2PY 现在可以正确支持这种使用方法。因此，Fortran 代码中的 integer, intent(in), value :: x 将生成正确的包装器。

(gh-21807)

添加了对第三方 BitGenerators 的 pickle 支持#

位生成器的 pickle 格式已扩展，允许每个位生成器在 pickling 过程中提供自己的构造函数。以前版本的 NumPy 仅支持解 pickle 由 NumPy 提供的核心位生成器集合之一创建的 Generator 实例。尝试解 pickle 使用第三方位生成器的 Generator 将失败，因为解 pickling 过程中使用的构造函数只知道 NumPy 中包含的位生成器。

(gh-22014)

arange() 现在在 dtype=str 时显式失败#

以前，np.arange(n, dtype=str) 函数在 n=1 和 n=2 时有效，但对于 n 的其他值，会引发一条非特定的异常消息。现在，它会引发一个 TypeError，告知 arange 不支持字符串 dtype。

>>> np.arange(2, dtype=str)
Traceback (most recent call last)
   ...
TypeError: arange() not supported for inputs with DType <class 'numpy.dtype[str_]'>.

(gh-22055)

numpy.typing 协议现在可以在运行时进行检查#

numpy.typing.ArrayLike 和 numpy.typing.DTypeLike 中使用的协议现在被正确标记为可在运行时进行检查，这使得它们更容易用于运行时类型检查器。

(gh-22357)

性能改进和更改#

针对整数数组的 np.isin 和 np.in1d 的更快版本#

np.in1d（由 np.isin 使用）现在可以在传递两个整数数组时切换到更快的算法（速度提高可达 10 倍以上）。这通常会自动使用，但您可以使用 kind="sort" 或 kind="table" 来强制使用旧方法或新方法。

(gh-12065)

更快的比较运算符#

比较函数（numpy.equal、numpy.not_equal、numpy.less、numpy.less_equal、numpy.greater 和 numpy.greater_equal）现在速度快得多，因为它们现在使用通用内在函数进行矢量化。对于具有 SIMD 扩展 AVX512BW 的 CPU，整数、浮点和布尔数据类型的性能提升分别高达 2.57 倍、1.65 倍和 19.15 倍（N=50000）。

(gh-21483)

更改#

更好的整数除法溢出报告#

标量和数组的整数除法溢出过去会提供一个 RuntimeWarning，返回值未定义，导致在极少数情况下发生崩溃。

>>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1)
<stdin>:1: RuntimeWarning: divide by zero encountered in floor_divide
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0], dtype=int32)

整数除法溢出现在返回输入 dtype 的最小值并引发以下 RuntimeWarning

>>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1)
<stdin>:1: RuntimeWarning: overflow encountered in floor_divide
array([-2147483648, -2147483648, -2147483648, -2147483648, -2147483648,
       -2147483648, -2147483648, -2147483648, -2147483648, -2147483648],
      dtype=int32)

(gh-21506)

masked_invalid 现在就地修改掩码#

当与 copy=False 一起使用时，numpy.ma.masked_invalid 现在会就地修改输入掩码数组。这使其行为与 masked_where 完全相同，并且更符合文档。

(gh-22046)

nditer/NpyIter 允许分配所有操作数#

现在，可以通过 Python 中的 np.nditer 和 C 中的 NpyIter 使用的 NumPy 迭代器支持分配所有数组。在这种情况下，迭代器形状默认为 ()。必须提供操作数 dtype，因为无法从其他输入推断“公共 dtype”。

(gh-22457)