NumPy 1.24 发行说明#

NumPy 1.24.0 版的发布延续了正在进行的改进 dtypes 处理和提升、提高执行速度以及澄清文档的工作。由于提升和清理方面的变化，还有大量新增和过期的弃用。这或许可以称之为一次弃用版本。主要亮点包括：

  • 许多新的弃用，请查阅。

  • 许多已过期的弃用，

  • F2PY 新增功能和修复。

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

详情请见下文，

此版本支持 Python 3.8-3.11。

弃用#

弃用 fastCopyAndTranspose 和 PyArray_CopyAndTranspose#

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

arr.T.copy()

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

(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 实例传递给 ufuncs 中的 dtype= 或 signature= 将引发 TypeError。我们建议传递字符串 "int8" 或标量类型 np.int8，因为字节序、日期时间/时间差单位等从未强制执行。（最初在 NumPy 1.21 中弃用。）

    (gh-22540)

  • 现在，比较 ufuncs 的 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)

现在总是为 false。而以前，对于特定转换，它曾为 true。

(gh-21925)

返回的数组尊重 dtype 关键字参数对象的唯一性#

当 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 弃用，且 GCC-6 在 Ubuntu 20.04 上不可用，因此使用该编译器的构建不再进行测试。我们仍然测试使用 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²

请注意，多项式类仅支持 1D 多项式，因此当结果为多元时，涉及不同符号的多项式操作是不允许的

>>> 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 选项#

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

(gh-21595)

向 np.unique 添加新参数 equal_nan#

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

(gh-21623)

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

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

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

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

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

casting 和 dtype 关键字参数现已可用于 numpy.hstack。要使用它们，请编写 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 来直接构造结构化空标量。

(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 格式已扩展，允许每个位生成器在 pickle 过程中提供自己的构造函数。NumPy 的早期版本只支持 unpickling 使用 NumPy 提供的核心位生成器集合之一创建的 Generator 实例。尝试 unpickle 使用第三方位生成器的 Generator 会失败，因为 unpickling 期间使用的构造函数只知道 NumPy 中包含的位生成器。

(gh-22014)

arange() 现在明确支持 dtype=str 的失败#

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

>>> 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，整数、浮点和布尔数据类型（N=50000）的性能提升分别高达 2.57 倍、1.65 倍和 19.15 倍。

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