NumPy 2.0.0 版本说明#

NumPy 2.0.0 是自 2006 年以来的第一个主要版本。它是自上次功能版本发布以来 11 个月开发的结果，由 212 位贡献者完成，提交了 1078 个拉取请求。它包含大量令人兴奋的新功能以及对 Python 和 C API 的更改。

此主要版本包含在常规次要（功能）版本中无法发生的重大更改——包括 ABI 中断、类型提升规则的更改以及在 1.26.x 中可能未发出弃用警告的 API 更改。除了这些发行说明之外，与如何适应 NumPy 2.0 中更改相关的关键文档包括：

亮点#

此版本的亮点包括：

  • 新功能

    • 新的变长字符串 dtype，StringDType 和一个新的 numpy.strings 命名空间，其中包含用于字符串操作的高性能 ufunc（通用函数），

    • 在所有 numpy.fft 函数中支持 float32 和 longdouble，

    • 在主 numpy 命名空间中支持数组 API 标准。

  • 性能改进

    • 排序函数（sort，argsort，partition，argpartition）通过使用 Intel x86-simd-sort 和 Google Highway 库得到了加速，并且可能会看到很大的（特定于硬件的）速度提升，

    • macOS Accelerate 支持和适用于 macOS >=14 的二进制轮子，对 macOS 上的线性代数运算有显著的性能改进，并且轮子大小约小 3 倍，

    • numpy.char 定长字符串操作通过实现也支持 StringDType 的 ufunc（除了定长字符串 dtype 之外）而得到了加速，

    • 一个新的追踪和内省 API，opt_func_info，用于确定哪些特定于硬件的内核可用并将被调度。

    • numpy.save 现在使用 pickle 协议版本 4 来保存具有对象 dtype 的数组，这允许 pickle 对象大于 4GB，并且对于大型数组可以将保存速度提高约 5%。

  • Python API 改进

    • 公共 API 和私有 API 之间的清晰划分，具有新的模块结构，并且每个公共函数现在都位于一个位置，

    • 删除了许多不推荐使用的函数和别名。这应该使学习和使用 NumPy 变得更容易。主命名空间中的对象数量减少了约 10%，numpy.lib 中减少了约 80%，

    • 规范的 dtype 名称 和一个新的 isdtype 内省函数，

  • C API 改进

  • 改进的行为

    • 通过采用NEP 50 更改了类型提升行为的改进。这修复了许多用户对提升的意外情况，这些意外情况以前通常取决于输入数组的数据值而不是仅取决于它们的 dtype。请参阅 NEP 和NumPy 2.0 迁移指南以了解详细信息，因为此更改可能会导致输出 dtype 的更改以及混合 dtype 操作的精度降低。

    • Windows 上的默认整数类型现在是 int64 而不是 int32，与其他平台上的行为匹配，

    • 数组维度的最大数量已从 32 更改为 64。

  • 文档

此外，NumPy 内部还有许多更改，包括继续将代码从 C 迁移到 C++，这将使将来更容易改进和维护 NumPy。

“没有免费午餐”定理表明，所有这些 API 和行为改进以及更好的未来可扩展性都需要付出代价。

  1. 向后兼容性。对 Python 和 C API 都有大量的重大更改。在大多数情况下，都会有清晰的错误消息告知用户如何调整其代码。但是，也有一些行为更改无法提供此类错误消息——这些情况都在下面的弃用和兼容性部分以及NumPy 2.0 迁移指南中进行了介绍。

    请注意，有一个 ruff 模式可以自动修复 Python 代码中的许多问题。

  2. 对 NumPy ABI 的重大更改。因此，使用 NumPy C API 并针对 NumPy 1.xx 版本构建的包的二进制文件将无法与 NumPy 2.0 一起使用。导入时，此类包将看到一个带有关于二进制不兼容性消息的 ImportError。

    可以针对 NumPy 2.0 构建在运行时可与 NumPy 2.0 和 1.x 都兼容的二进制文件。有关更多详细信息，请参阅NumPy 2.0 特定建议。

    建议所有依赖于 NumPy ABI 的下游包进行针对 NumPy 2.0 构建的新版本发布，并验证该版本是否可与 2.0 和 1.26 都兼容——理想情况下，在 2.0.0rc1（将是 ABI 稳定的）和最终 2.0.0 版本之间，以避免其用户出现问题。

此版本支持的 Python 版本为 3.9-3.12。

NumPy 2.0 Python API 删除#

  • np.geterrobj、np.seterrobj 和相关的 ufunc 关键字参数 extobj= 已被删除。所有这些的首选替换是使用上下文管理器 with np.errstate():。

    (gh-23922)

  • np.cast 已被删除。np.cast[dtype](arg) 的字面替换是 np.asarray(arg, dtype=dtype)。

  • np.source 已被删除。首选替换是 inspect.getsource。

  • 已移除 np.lookfor。

    (gh-24144)

  • 已移除 numpy.who。作为替代方案，可以使用Spyder或Jupyter Notebook等IDE中提供的变量浏览器。

    (gh-24321)

  • numpy.exceptions 中的警告和异常（例如，ComplexWarning，VisibleDeprecationWarning）不再在主命名空间中公开。

  • 多个小众枚举、已失效的成员和函数已从主命名空间中移除，例如：ERR_*，SHIFT_*，np.fastCopyAndTranspose，np.kernel_version，np.numarray，np.oldnumeric 和 np.set_numeric_ops。

    (gh-24316)

  • 将numpy/__init__.py中的from ... import *替换为显式导入。结果，这些主命名空间成员被移除：np.FLOATING_POINT_SUPPORT，np.FPE_*，np.NINF，np.PINF，np.NZERO，np.PZERO，np.CLIP，np.WRAP，np.WRAP，np.RAISE，np.BUFSIZE，np.UFUNC_BUFSIZE_DEFAULT，np.UFUNC_PYVALS_NAME，np.ALLOW_THREADS，np.MAXDIMS，np.MAY_SHARE_EXACT，np.MAY_SHARE_BOUNDS，add_newdoc，np.add_docstring 和 np.add_newdoc_ufunc。

    (gh-24357)

  • 已移除别名 np.float_。请使用 np.float64 代替。

  • 已移除别名 np.complex_。请使用 np.complex128 代替。

  • 已移除别名 np.longfloat。请使用 np.longdouble 代替。

  • 已移除别名 np.singlecomplex。请使用 np.complex64 代替。

  • 已移除别名 np.cfloat。请使用 np.complex128 代替。

  • 已移除别名 np.longcomplex。请使用 np.clongdouble 代替。

  • 已移除别名 np.clongfloat。请使用 np.clongdouble 代替。

  • 已移除别名 np.string_。请使用 np.bytes_ 代替。

  • 已移除别名 np.unicode_。请使用 np.str_ 代替。

  • 已移除别名 np.Inf。请使用 np.inf 代替。

  • 已移除别名 np.Infinity。请使用 np.inf 代替。

  • 已移除别名 np.NaN。请使用 np.nan 代替。

  • 已移除别名 np.infty。请使用 np.inf 代替。

  • 已移除别名 np.mat。请使用 np.asmatrix 代替。

  • 已移除 np.issubclass_。请使用内置函数 issubclass 代替。

  • 已移除 np.asfarray。请使用带有适当dtype的 np.asarray 代替。

  • 已移除 np.set_string_function。请使用 np.set_printoptions 代替，并使用格式化程序来自定义 NumPy 对象的打印方式。

  • np.tracemalloc_domain 现在只能从 np.lib 访问。

  • 已从主命名空间移除 np.recfromcsv 和 np.recfromtxt。请使用带有逗号分隔符的 np.genfromtxt 代替。

  • 已从主命名空间移除 np.issctype，np.maximum_sctype，np.obj2sctype，np.sctype2char，np.sctypes，np.issubsctype，因为它们是小众成员。

  • 已从主命名空间移除已弃用的 np.deprecate 和 np.deprecate_with_doc。请使用 DeprecationWarning 代替。

  • 已从主命名空间移除已弃用的 np.safe_eval。请使用 ast.literal_eval 代替。

    (gh-24376)

  • 已移除 np.find_common_type。请使用 numpy.promote_types 或 numpy.result_type 代替。要实现 scalar_types 参数的语义，请使用 numpy.result_type 并传递 0、0.0 或 0j 作为 Python 标量。

  • 已移除 np.round_。请使用 np.round 代替。

  • 已移除 np.nbytes。请使用 np.dtype(<dtype>).itemsize 代替。

    (gh-24477)

  • 已从主命名空间移除 np.compare_chararrays。请使用 np.char.compare_chararrays 代替。

  • 主命名空间中的 charrarray 已弃用。目前可以从 np.char.chararray 导入它而不会出现弃用警告，但我们计划将来完全弃用并移除 chararray。

  • 已从主命名空间移除 np.format_parser。请使用 np.rec.format_parser 代替。

    (gh-24587)

  • 已从 np.dtype 中移除对七个数据类型字符串别名的支持：int0，uint0，void0，object0，str0，bytes0 和 bool8。

    (gh-24807)

  • 已移除实验性的 numpy.array_api 子模块。请改为使用主 numpy 命名空间进行常规使用，或者使用单独的 array-api-strict 包进行合规性测试用例（numpy.array_api 主要用于此）。

    (gh-25911)

已移除 __array_prepare__#

在对普通 ufunc 调用（而不是广义 ufunc、约简等）进行计算之前，UFuncs 会调用 __array_prepare__。该函数还会在某些线性代数函数的结果上代替 __array_wrap__ 被调用。

现在已将其移除。如果您使用它，请迁移到 __array_ufunc__ 或依赖于 __array_wrap__，它在所有情况下都会被调用，尽管仅在结果数组填充后才会被调用。在这些代码路径中，__array_wrap__ 现在将传递一个基类，而不是一个子类数组。

(gh-25105)

弃用#

  • 由于不再支持 Python 2，因此已弃用 np.compat。

  • numpy.int8 及类似类将不再支持将超出范围的 Python 整数转换为整数数组。例如，将 255 转换为 int8 将不会返回 -1。numpy.iinfo(dtype) 可用于检查数据类型的机器限制。例如，np.iinfo(np.uint16) 返回 min = 0 和 max = 65535。

    np.array(value).astype(dtype) 将给出所需的结果。

  • np.safe_eval 已弃用。应改用ast.literal_eval。

    (gh-23830)

  • np.recfromcsv、np.recfromtxt、np.disp、np.get_array_wrap、np.maximum_sctype、np.deprecate 和 np.deprecate_with_doc 已弃用。

    (gh-24154)

  • np.trapz 已弃用。请改用np.trapezoid 或scipy.integrate 中的函数。

  • np.in1d 已弃用。请改用np.isin。

  • 别名np.row_stack 已弃用。请直接使用np.vstack。

    (gh-24445)

  • __array_wrap__ 现在传递arr, context, return_scalar，并且不支持接受所有三个参数的实现已被弃用。其签名应为__array_wrap__(self, arr, context=None, return_scalar=False)

    (gh-25409)

  • np.cross 的二维向量数组已弃用。请改用三维向量数组。

    (gh-24818)

  • np.dtype("a")（np.dtype(np.bytes_) 的别名）已弃用。请改用别名np.dtype("S")。

    (gh-24854)

  • 函数assert_array_equal 和 assert_array_almost_equal 中使用关键字参数x 和 y 已弃用。请改将前两个参数作为位置参数传递。

    (gh-24978)

numpy.fft 中参数为 None 值的 n 维变换弃用说明#

根据数组 API 标准，使用fftn、ifftn、rfftn、irfftn、fft2、ifft2、rfft2 或 irfft2 并将s 参数设置为非None 值且axes 参数设置为None 已弃用。要保留当前行为，请为维度为 k 的数组将序列 [0, …, k-1] 传递给axes。

此外，将包含None 值的数组传递给s 已弃用，因为该参数在 NumPy 文档和数组 API 规范中都被记录为接受整数序列。要使用相应的一维变换的默认行为，请传递与其n 参数默认值匹配的值。要对每个轴使用默认行为，可以省略s 参数。

(gh-25495)

np.linalg.lstsq 现在默认为新的rcond 值#

lstsq 现在使用新的 rcond 值：机器精度乘以max(M, N)。以前使用的是机器精度，但会发出 FutureWarning 以通知最终会发生此更改。通过传递rcond=-1 仍然可以实现旧的行为。

(gh-25721)

已过期弃用#

  • np.core.umath_tests 子模块已从公共 API 中移除。（在 NumPy 1.15 中弃用）

    (gh-23809)

  • PyDataMem_SetEventHook 的弃用已过期，现已移除。请改用tracemalloc 和np.lib.tracemalloc_domain 域。（在 NumPy 1.23 中弃用）

    (gh-23921)

  • set_numeric_ops 和 C 函数PyArray_SetNumericOps 和 PyArray_GetNumericOps 的弃用已过期，这些函数现已移除。（在 NumPy 1.16 中弃用）

    (gh-23998)

  • fasttake、fastclip 和 fastputmask ArrFuncs 的弃用现已完成。

  • 已弃用的函数fastCopyAndTranspose 及其 C 对应函数现已移除。

  • PyArray_ScalarFromObject 的弃用现已完成。

    (gh-24312)

  • np.msort 已移除。请改用np.sort(a, axis=0)。

    (gh-24494)

  • np.dtype(("f8", 1) 现在将返回形状为 1 的子数组 dtype，而不是非子数组 dtype。

    (gh-25761)

  • 不允许向 ndarray 的.data 属性赋值，将引发异常。

  • 如果 width 太小，np.binary_repr(a, width) 将引发异常。

  • 在PyArray_DescrFromType() 中使用NPY_CHAR 将引发异常，请改用NPY_STRING、NPY_UNICODE 或NPY_VSTRING。

    (gh-25794)

兼容性说明#

loadtxt 和 genfromtxt 默认编码已更改#

loadtxt 和 genfromtxt 现在都默认为encoding=None，这可能会主要修改converters 的工作方式。现在将向它们传递str 而不是bytes。显式传递编码以始终获得新的或旧的行为。对于genfromtxt，更改还意味着返回的值现在将是 unicode 字符串而不是字节。

(gh-25158)

f2py 兼容性说明#

  • f2py 将不再接受含糊的-m 和.pyf CLI 组合。当传递多个.pyf 文件时，将引发错误。当同时传递-m 和.pyf 时，将发出警告，并忽略提供的-m 名称。

    (gh-25181)

  • f2py.compile() 帮助程序已被移除，因为它存在内存泄漏问题，多年来一直被标记为实验性，并且实现为一个轻量级的subprocess.run 包装器。它也是测试瓶颈之一。有关完整理由，请参阅 gh-25122。它还使用了几个np.distutils 功能，这些功能过于脆弱，无法移植以与meson 一起使用。

  • 强烈建议用户将对f2py.compile 的调用替换为对subprocess.run("python", "-m", "numpy.f2py",... 的调用，并使用环境变量与meson 交互。原生文件也是一种选择。

    (gh-25193)

排序函数的行为细微更改#

由于算法更改和使用 SIMD 代码，与 1.26.x 相比，2.0.0 中使用非稳定方法的排序函数可能会返回略微不同的结果。这包括argsort 和argpartition 的默认方法。

在np.solve 中消除广播时的歧义#

当b的维度比a少1维时，np.solve(a, b)的广播规则不明确。此问题已以不兼容旧版本的方式解决，现在符合数组API规范。可以使用np.solve(a, b[..., None])[..., 0]来重现旧的行为。

(gh-25914)

修改了Polynomial的表示方法#

Polynomial的表示方法已更新，其中包含了定义域。纯文本和LaTeX表示现在一致。例如，str(np.polynomial.Polynomial([1, 1], domain=[.1, .2]))的输出以前是1.0 + 1.0 x，但现在是1.0 + 1.0 (-3.0000000000000004 + 20.0 x)。

(gh-21760)

C API变更#

  • 已移除PyArray_CGT、PyArray_CLT、PyArray_CGE、PyArray_CLE、PyArray_CEQ、PyArray_CNE宏。

  • PyArray_MIN和PyArray_MAX已从ndarraytypes.h移动到npy_math.h。

    (gh-24258)

  • 已公开用于处理numpy.dtypes.StringDType数组的C API。这包括用于获取和释放互斥锁的函数（这些互斥锁锁定对字符串数据的访问），以及用于从数组条目打包和解包UTF-8字节流的函数。

  • NPY_NTYPES已重命名为NPY_NTYPES_LEGACY，因为它不包含新的NumPy内置DType。特别是，新的字符串DType可能无法与处理旧版DType的代码正确配合使用。

    (gh-25347)

  • C API现在仅导出数组访问器的静态内联函数版本（以前这取决于使用“已弃用的API”）。虽然我们不鼓励这样做，但仍然可以直接使用结构体字段。

    (gh-25789)

  • NumPy现在定义了PyArray_Pack来设置单个内存地址。与PyArray_SETITEM不同，此函数等效于设置单个数组项，不需要NumPy数组输入。

    (gh-25954)

  • 已从PyArray_Descr中移除->f槽。如果使用此槽，请使用PyDataType_GetArrFuncs替换对它的访问（请参阅其文档和NumPy 2.0迁移指南）。在某些情况下，使用其他函数（如PyArray_GETITEM）可能是替代方案。

  • PyArray_GETITEM和PyArray_SETITEM现在需要导入NumPy API表才能使用，并且不再在ndarraytypes.h中定义。

    (gh-25812)

  • 由于运行时依赖关系，访问dtype标志的功能定义已从numpy/ndarraytypes.h移动，只有在包含numpy/ndarrayobject.h之后才可用，因为它需要import_array()。这包括PyDataType_FLAGCHK、PyDataType_REFCHK和NPY_BEGIN_THREADS_DESCR。

  • PyArray_Descr上的dtype标志现在必须通过PyDataType_FLAGS内联函数访问才能与1.x和2.x兼容。此函数在npy_2_compat.h中定义，以便进行反向移植。大多数或所有用户都应该使用PyDataType_FLAGCHK，它在1.x上可用，不需要反向移植。Cython用户应该使用Cython 3。否则，除非他们使用PyDataType_FLAGCHK，否则访问将通过Python进行。

    (gh-25816)

C API和Cython绑定中公开的日期时间功能#

已将函数NpyDatetime_ConvertDatetime64ToDatetimeStruct、NpyDatetime_ConvertDatetimeStructToDatetime64、NpyDatetime_ConvertPyDateTimeToDatetimeStruct、NpyDatetime_GetDatetimeISO8601StrLen、NpyDatetime_MakeISO8601Datetime和NpyDatetime_ParseISO8601Datetime添加到C API，以方便在外部库中在字符串、Python日期时间和NumPy日期时间之间进行转换。

(gh-21199)

广义ufunc C API的常量正确性#

NumPy C API用于构造广义ufunc的函数（PyUFunc_FromFuncAndData、PyUFunc_FromFuncAndDataAndSignature、PyUFunc_FromFuncAndDataAndSignatureAndIdentity）采用types和data参数，这些参数不会被NumPy的内部机制修改。与name和doc参数一样，第三方Python扩展模块也可能从静态常量提供这些参数。types和data参数现在具有常量正确性：它们分别声明为const char *types和void *const *data。C代码不会受到影响，但C++代码可能会受到影响。

(gh-23847)

更大的NPY_MAXDIMS和NPY_MAXARGS，引入了NPY_RAVEL_AXIS#

NPY_MAXDIMS现在是64，您可能需要检查其用法。这通常用于堆栈分配，其中增加应该是安全的。但是，我们鼓励您通常删除任何NPY_MAXDIMS和NPY_MAXARGS的使用，以便最终能够完全删除此约束。对于转换帮助程序和镜像Python函数（如take）的C API函数，NPY_MAXDIMS用于表示axis=None。此类用法必须替换为NPY_RAVEL_AXIS。另请参见增加的最大维度数。

(gh-25149)

NPY_MAXARGS不是常量，并且PyArrayMultiIterObject大小发生变化#

由于NPY_MAXARGS已增加，它现在是运行时常量，不再是编译时常量。我们预计几乎没有用户会注意到这一点。但是，如果用于堆栈分配，现在必须使用NPY_MAXARGS作为额外的运行时检查来替换自定义常量。

sizeof(PyArrayMultiIterObject)不再包含对象的完整大小。我们预计没有人会注意到此更改。这是为了避免与Cython出现问题而必要的。

(gh-25271)

自定义旧版用户dtype所需的更改#

为了改进我们的DTypes，不幸的是需要破坏ABI，这需要对使用PyArray_RegisterDataType注册的dtypes进行一些更改。请参阅PyArray_RegisterDataType的文档，了解如何调整代码并实现与1.x和2.x的兼容性。

(gh-25792)

新的公共DType API#

NEP 42 DType API的C实现现在是公开的。虽然DType API已经在NumPy中发布了几个版本，但它只能在设置了特殊环境变量的会话中使用。现在可以使用新的DType API和用于导入numpy C API的常规import_array()机制来编写NumPy之外的自定义DTypes。

有关API的更多详细信息，请参见自定义数据类型。与往常一样，对于新功能，请报告您在实现或使用新的DType时遇到的任何错误。下游与dtypes一起工作的C代码可能需要更新才能与新的DTypes正确配合使用。

(gh-25754)

新的C-API导入函数#

我们现在添加了PyArray_ImportNumPyAPI和PyUFunc_ImportUFuncAPI作为静态内联函数来导入NumPy C-API表。与import_array和import_ufunc相比，新函数有两个优点。

  • 它们检查是否已经执行了导入，如果没有则重量轻，允许谨慎地添加它们（尽管在大多数情况下这不是首选）。

  • 旧机制是宏而不是函数，其中包含return语句。

PyArray_ImportNumPyAPI()函数包含在npy_2_compat.h中，用于更简单的向后移植。

(gh-25866)

通过函数访问结构化dtype信息#

dtype结构字段c_metadata、names、fields和subarray现在必须通过遵循相同名称的新函数（例如PyDataType_NAMES）访问。直接访问字段是无效的，因为它们并不存在于所有PyArray_Descr实例中。metadata字段保留，但宏版本也应优先使用。

(gh-25802)

描述符elsize和alignment访问#

除非仅使用NumPy 2支持进行编译，否则现在必须通过PyDataType_ELSIZE、PyDataType_SET_ELSIZE和PyDataType_ALIGNMENT访问elsize和alignment字段。在描述符附加到数组的情况下，我们建议使用PyArray_ITEMSIZE，因为它存在于所有NumPy版本中。有关更多信息，请参见PyArray_Descr结构已更改。

(gh-25943)

NumPy 2.0 C API移除#

  • npy_interrupt.h和相应的宏（如NPY_SIGINT_ON）已被移除。我们建议定期查询PyErr_CheckSignals()或PyOS_InterruptOccurred()（这些目前确实需要持有GIL）。

  • noprefix.h头文件已被移除。用带前缀的对应项替换缺失的符号（通常是添加的NPY_或npy_）。

    (gh-23919)

  • PyUFunc_GetPyVals、PyUFunc_handlefperr和PyUFunc_checkfperr已被移除。如果需要，可以恢复一个新的向后兼容函数来引发浮点错误。移除原因：没有已知的使用者，并且这些函数会使with np.errstate()修复变得更加困难。

    (gh-23922)

  • 自NumPy 1.7以来已被弃用的API一部分的numpy/old_defines.h已被移除。这会移除PyArray_CONSTANT形式的宏。replace_old_macros.sed脚本可能有助于将其转换为NPY_CONSTANT版本。

    (gh-24011)

  • ufunc结构的legacy_inner_loop_selector成员已被移除，以简化对调度系统的改进。没有已知的用户覆盖或直接访问此成员。

    (gh-24271)

  • NPY_INTPLTR已被移除，以避免混淆（参见intp重新定义）。

    (gh-24888)

  • 高级索引MapIter和相关API已被移除。它的（真正）公共部分没有经过充分测试，只有一个已知的使用者（Theano）。将其设为私有将简化改进以加快ufunc.at的速度，使高级索引更容易维护，并且对于将数组的最大维数增加到64非常重要。如果您认为此API对您很重要，请告知我们，以便我们可以一起找到解决方案。

    (gh-25138)

  • NPY_MAX_ELSIZE宏已被移除，因为它仅反映内置数值类型，并且没有内部用途。

    (gh-25149)

  • PyArray_REFCNT和NPY_REFCOUNT已被移除。改用Py_REFCNT。

    (gh-25156)

  • PyArrayFlags_Type和PyArray_NewFlagsObject以及PyArrayFlagsObject现在是私有的。没有已知的用例；如果需要，请使用Python API。

  • PyArray_MoveInto、PyArray_CastTo、PyArray_CastAnyTo已被移除，请使用PyArray_CopyInto，如果绝对需要，请使用PyArray_CopyAnyInto（后者执行平面复制）。

  • PyArray_FillObjectArray已被移除，它唯一的真正用途是实现np.empty。创建一个新的空数组或使用PyArray_FillWithScalar()（递减现有对象的引用计数）。

  • PyArray_CompareUCS4和PyArray_CompareString已被移除。使用标准C字符串比较函数。

  • PyArray_ISPYTHON已被移除，因为它具有误导性，没有已知的用例，并且易于替换。

  • PyArray_FieldNames已被移除，因为它不清楚它有什么用。它在某些可能的用例中也具有不正确的语义。

  • PyArray_TypestrConvert已被移除，因为它似乎是一个误称，并且不太可能被任何人使用。如果您知道大小或仅限于少量类型，请直接使用它，否则请通过Python字符串。

    (gh-25292)

  • PyDataType_GetDatetimeMetaData已被移除，自NumPy 1.7以来它实际上什么也没做。

    (gh-25802)

  • PyArray_GetCastFunc已被移除。请注意，自定义旧版用户dtype仍然可以提供castfunc作为其实现，但是现在任何对其的访问都被移除了。原因是NumPy多年来从未在内部使用这些函数。如果您使用简单的数值类型，请直接使用C强制转换。如果您需要替代方案，请告知我们，以便我们可以创建新的API，例如PyArray_CastBuffer()，它可以使用旧的或新的强制转换函数，具体取决于NumPy版本。

    (gh-25161)

新功能#

np.add 函数现已扩展，支持unicode 和 bytes 数据类型。#

新增bitwise_count 函数#

此新函数用于统计数字中 1 的个数。 bitwise_count 支持所有 NumPy 整型和类似整数的对象。

>>> a = np.array([2**i - 1 for i in range(16)])
>>> np.bitwise_count(a)
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
      dtype=uint8)

(gh-19355)

macOS 加速支持，包括 ILP64#

已添加对更新的 macOS 13.3 中的 Accelerate BLAS/LAPACK 库的支持，包括 ILP64（64 位整数）支持。这带来了 arm64 支持，并显著提高了常用线性代数运算的性能，最高可达 10 倍。如果在构建时选择 Accelerate，或者没有显式选择 BLAS 库，则如果可用，系统将自动使用 13.3+ 版本。

(gh-24053)

同时也提供二进制轮子包。在 macOS >=14.0 上，从 PyPI 安装 NumPy 的用户将获得针对 Accelerate 而不是 OpenBLAS 构建的轮子包。

(gh-25255)

分位数和百分位数函数的权重选项#

现在 quantile、percentile、nanquantile 和 nanpercentile 函数都提供了一个weights 关键字参数。只有method="inverted_cdf" 支持权重。

(gh-24254)

改进的 CPU 优化跟踪#

提供了一种新的跟踪机制，可以跟踪 NumPy 库中每个优化函数（即使用特定于硬件的 SIMD 指令）的已启用目标。通过此增强功能，可以精确监控已分派函数的已启用 CPU 分派目标。

一个名为opt_func_info 的新函数已添加到新的命名空间 numpy.lib.introspect 中，提供此跟踪功能。此函数允许您根据函数名称和数据类型签名检索有关已启用目标的信息。

(gh-24420)

f2py 的新 Meson 后端#

编译模式下的 f2py（即 f2py -c）现在接受 --backend meson 选项。对于 Python >=3.12，这是默认选项。对于较旧的 Python 版本，f2py 仍默认为 --backend distutils。

为了在实际用例中支持这一点，在编译模式下，f2py 会多次使用 --dep 标志，该标志映射到 meson 后端中的 dependency() 调用，在 distutils 后端中则不执行任何操作。

对于仅作为代码生成器使用 f2py 的用户（即不使用 -c）没有任何更改。

(gh-24532)

f2py 的 bind(c) 支持#

函数和子程序都可以用 bind(c) 进行注释。f2py 将处理正确的类型映射，并保留其他 C 接口的唯一标签。

注意：bind(c, name = 'routine_name_other_than_fortran_routine') 并非 f2py 绑定故意支持，因为带有 name 的 bind(c) 只旨在保证 C 和 Fortran 中的名称相同，而不是 Python 和 Fortran 中的名称相同。

(gh-24555)

几个测试函数的新 strict 选项#

现在 assert_allclose、assert_equal 和 assert_array_less 函数都提供了一个strict 关键字参数。设置 strict=True 将禁用标量的广播行为，并确保输入数组具有相同的数据类型。

(gh-24680, gh-24770, gh-24775)

添加 np.core.umath.find 和 np.core.umath.rfind UFuncs#

添加了两个 find 和 rfind UFuncs，它们作用于 unicode 或字节字符串，并用于 np.char。它们的操作类似于 str.find 和 str.rfind。

(gh-24868)

numpy.linalg 的 diagonal 和 trace#

已添加 numpy.linalg.diagonal 和 numpy.linalg.trace，它们是与数组 API 标准兼容的 numpy.diagonal 和 numpy.trace 的变体。它们在定义二维子数组的默认轴选择方面有所不同。

(gh-24887)

新的 long 和 ulong 数据类型#

已添加 numpy.long 和 numpy.ulong 作为 NumPy 整数，映射到 C 的 long 和 unsigned long。在 NumPy 1.24 之前，numpy.long 是 Python 的 int 的别名。

(gh-24922)

numpy.linalg 的 svdvals#

已添加 numpy.linalg.svdvals。它计算（矩阵堆栈的）奇异值。执行 np.svdvals(x) 等同于调用 np.svd(x, compute_uv=False, hermitian=False)。此函数与数组 API 标准兼容。

(gh-24940)

新增 isdtype 函数#

已添加 numpy.isdtype 以提供一种规范的方法来对 NumPy 的数据类型进行分类，符合数组 API 标准。

(gh-25054)

新增 astype 函数#

已添加 numpy.astype 以提供与数组 API 标准兼容的 numpy.ndarray.astype 方法的替代方案。

(gh-25079)

与数组 API 兼容的函数别名#

为了提高与数组 API 标准的兼容性，新增了 13 个现有函数的别名。

  • 三角函数：acos、acosh、asin、asinh、atan、atanh、atan2。

  • 位运算：bitwise_left_shift、bitwise_invert、bitwise_right_shift。

  • 其他：concat、permute_dims、pow。

  • 在 numpy.linalg 中：tensordot、matmul。

(gh-25086)

新的 unique_* 函数#

新增了 unique_all、unique_counts、unique_inverse 和 unique_values 函数。它们提供了 unique 函数的不同标志功能。它们与数组 API 标准兼容，并且由于它们返回的数组数量不依赖于输入参数的值，因此更易于进行 JIT 编译。

(gh-25088)

对 ndarray 的矩阵转置支持#

NumPy 现在支持计算数组（或数组堆栈）的矩阵转置。矩阵转置等效于交换数组的最后两个轴。 np.ndarray 和 np.ma.MaskedArray 现在都公开了 .mT 属性，并且有一个匹配的新 numpy.matrix_transpose 函数。

(gh-23762)

用于 numpy.linalg 的与数组 API 兼容的函数#

新增了六个新函数和两个别名，以提高与 numpy.linalg 的数组 API 标准的兼容性。

用于 var 和 std 的 correction 参数#

在 var 和 std 中添加了一个 correction 参数，它是与数组 API 标准兼容的 ddof 替代方案。由于这两个参数具有相似的用途，因此一次只能提供其中一个。

(gh-25169)

ndarray.device 和 ndarray.to_device#

为了与数组 API 标准兼容，在 numpy.ndarray 中添加了 ndarray.device 属性和 ndarray.to_device 方法。

此外，还为以下函数添加了 device 关键字参数：asarray、arange、empty、empty_like、eye、full、full_like、linspace、ones、ones_like、zeros 和 zeros_like。

对于所有这些新参数，只支持 device="cpu"。

(gh-25233)

已向 NumPy 添加 StringDType#

我们添加了一种新的变长 UTF-8 编码字符串数据类型，实现了“Python 字符串的 NumPy 数组”，包括对用户提供的缺失数据哨兵的支持。它旨在作为使用 object dtype 的 Python 字符串和缺失数据哨兵数组的直接替代品。详情请参见 NEP 55 和 文档。

(gh-25347)

用于 cholesky 和 pinv 的新关键字#

为提高与数组 API 标准的兼容性，在 numpy.linalg.cholesky 和 numpy.linalg.pinv 中分别添加了 upper 和 rtol 关键字。

对于 pinv，如果没有指定 rcond 或 rtol，则使用 rcond 的默认值。我们计划将来弃用并移除 rcond。

(gh-25388)

sort、argsort 和 linalg.matrix_rank 的新关键字#

添加了新的关键字参数以提高与数组 API 标准的兼容性。

(gh-25437)

用于字符串 ufunc 的新的 numpy.strings 命名空间#

NumPy 现在将一些字符串操作实现为 ufunc。旧的 np.char 命名空间仍然可用，并且在可能的情况下，该命名空间中的字符串操作函数已更新为使用新的 ufunc，从而大大提高了它们的性能。

在可能的情况下，我们建议更新代码以使用 np.strings 中的函数，而不是 np.char。将来，我们可能会弃用 np.char 以支持 np.strings。

(gh-25463)

numpy.fft 对不同精度和原地计算的支持#

numpy.fft 中的各种 FFT 例程现在根据输入精度以单精度、双精度或长双精度本地进行计算，而不是始终以双精度进行计算。因此，对于单精度计算，精度会降低，而对于长双精度计算，精度会提高。输出数组的数据类型现在将相应调整。

此外，所有 FFT 例程都增加了一个 out 参数，可用于原地计算。

(gh-25536)

configtool 和 pkg-config 支持#

现在提供了一个新的 numpy-config CLI 脚本，可以查询 NumPy 版本以及使用 NumPy C API 所需的编译标志。这将使构建系统能够更好地支持 NumPy 作为依赖项的使用。此外，现在 NumPy 中包含一个 numpy.pc pkg-config 文件。为了找到其在 PKG_CONFIG_PATH 中的使用位置，请使用 numpy-config --pkgconfigdir。

(gh-25730)

主命名空间中的数组 API 标准支持#

主 numpy 命名空间现在支持数组 API 标准。有关详细信息，请参见 数组 API 标准兼容性。

(gh-25911)

改进#

any、all 和逻辑 ufunc 现在支持字符串。#

将整数序列作为 memmap 的 shape 参数#

现在可以使用任何整数序列（例如整数列表或 numpy 数组）作为 numpy.memmap 的 shape 参数。以前，只有元组和 int 类型可以使用，否则会引发错误。

(gh-23729)

errstate 现在更快且上下文安全#

numpy.errstate 上下文管理器/装饰器现在更快且更安全。以前，它不是上下文安全的，并且存在（罕见的）线程安全问题。

(gh-23936)

使用 Highway 的 VQSort 提高了 AArch64 快速排序速度#

首次引入 Google Highway 库，在 AArch64 上使用 VQSort。在某些情况下，执行时间最多提高了 16 倍，有关基准测试结果，请参见 PR。将来会扩展到其他平台。

(gh-24018)

复数类型 - 底层 C 类型更改#

  • 所有 NumPy 复数类型的底层 C 类型已更改为使用 C99 复数类型。

  • 此更改虽然不影响复数类型的内存布局，但它更改了用于直接检索或写入复数实部或虚部的 API，因为直接字段访问（如 c.real 或 c.imag）不再是一种选择。现在可以使用 numpy/npy_math.h 中提供的实用程序来执行这些操作，如下所示：

    npy_cdouble c;
npy_csetreal(&c, 1.0);
npy_csetimag(&c, 0.0);
printf("%d + %di\n", npy_creal(c), npy_cimag(c));

  • 为了方便跨版本兼容性，已添加等效的宏和兼容性层，下游包可以使用它们来继续支持 NumPy 1.x 和 2.x。有关更多信息，请参见 复数支持。

  • numpy/npy_common.h 现在包含 complex.h，这意味着 complex 现在是保留关键字。

(gh-24085)

iso_c_binding 支持以及 f2py 的改进公共块#

以前，用户必须定义他们自己的自定义 f2cmap 文件才能使用 Fortran2003 iso_c_binding 本身模块定义的类型映射。这些类型映射现在受 f2py 原生支持。

(gh-24555)

f2py 现在处理具有来自模块的 kind 规范的 common 块。这进一步扩展了诸如 iso_fortran_env 和 iso_c_binding 之类的本身函数的可用性。

(gh-25186)

自动对类似 assert_equal 的函数的第三个参数调用 str#

类似 assert_equal 的函数的第三个参数现在会自动调用 str。这样它就模仿了内置的 assert 语句，其中 assert_equal(a, b, obj) 的作用类似于 assert a == b, obj。

(gh-24877)

isclose、allclose 中支持类似数组的 atol/rtol#

isclose 和 allclose 中的关键字 atol 和 rtol 现在既接受标量也接受数组。如果给出数组，则必须将其广播到前两个数组参数的形状。

(gh-24878)

测试函数中一致的失败消息#

之前，一些numpy.testing断言会打印消息，将实际结果和预期结果分别称为x和y。现在，这些值始终被称为ACTUAL和DESIRED。

(gh-24931)

n-D FFT 变换允许s[i] == -1#

fftn、ifftn、rfftn、irfftn、fft2、ifft2、rfft2和irfft2函数现在如果s[i] == -1，则沿轴i使用整个输入数组，这与数组API标准一致。

(gh-25495)

为受限API保护PyArrayScalar_VAL和PyUnicodeScalarObject#

PyUnicodeScalarObject包含一个PyUnicodeObject，在使用Py_LIMITED_API时不可用。添加保护以隐藏它，并因此隐藏PyArrayScalar_VAL宏。

(gh-25531)

更改#

  • np.gradient()现在返回元组而不是列表，使返回值不可变。

    (gh-23861)

  • 完全上下文和线程安全，np.errstate现在只能进入一次。

  • np.setbufsize现在与np.errstate()绑定：离开np.errstate上下文也将重置bufsize。

    (gh-23936)

  • 引入了新的公共np.lib.array_utils子模块，它目前包含三个函数：byte_bounds（从np.lib.utils移动）、normalize_axis_tuple和normalize_axis_index。

    (gh-24540)

  • 引入numpy.bool作为NumPy布尔dtype的新规范名称，并使numpy.bool_成为它的别名。请注意，直到NumPy 1.24，np.bool是Python内置bool的别名。新名称有助于数组API标准兼容性，并且是一个更直观的名称。

    (gh-25080)

  • dtype.flags值以前存储为有符号整数。这意味着对齐的dtype结构标志导致设置负标志（-128而不是128）。此标志现在存储为无符号（正）整数。手动检查标志的代码可能需要调整。这可能包括使用Cython 0.29.x编译的代码。

    (gh-25816)

NumPy标量的表示方式已更改#

根据NEP 51，标量表示已更新为包含类型信息，以避免与Python标量混淆。

标量现在打印为np.float64(3.0)而不是仅3.0。这可能会破坏存储数字表示形式（例如，到文件）的工作流程，使其难以读取。它们应存储为显式字符串，例如使用str()或f"{scalar!s}"。目前，受影响的用户可以使用np.set_printoptions(legacy="1.25")来获得旧的行为（可能有一些例外）。如果测试了代码片段，则下游项目的文档可能需要更大的更新。我们正在为doctest-plus开发工具以方便更新。

(gh-22449)

NumPy字符串的真值已更改#

NumPy字符串以前在如何定义字符串是True还是False方面不一致，并且定义与Python使用的定义不匹配。字符串现在在非空时被认为是True，在空时被认为是False。这改变了以下不同的情况

  • 从字符串到布尔的转换以前大致等效于string_array.astype(np.int64).astype(bool)，这意味着只有有效的整数才能转换。现在"0"的字符串将被认为是True，因为它不是空的。如果您需要旧的行为，您可以使用上述步骤（首先转换为整数）或string_array == "0"（如果输入仅为0或1）。要在旧的NumPy版本上获得新的结果，请使用string_array != ""。

  • np.nonzero(string_array)以前忽略空格，因此仅包含空格的字符串被认为是False。空格现在被认为是True。

此更改不影响np.loadtxt、np.fromstring或np.genfromtxt。前两个仍然使用整数定义，而genfromtxt继续匹配"true"（忽略大小写）。但是，如果使用np.bool_作为转换器，结果将发生变化。

此更改确实会影响np.fromregex，因为它使用直接赋值。

(gh-23871)

向var和std函数添加了mean关键字#

通常，当需要标准差时，也需要平均值。方差和平均值也是如此。到目前为止，平均值计算了两次，这里为var和std函数引入的更改允许将预先计算的平均值作为关键字参数传递。有关详细信息和说明加速的示例，请参见文档字符串。

(gh-24126)

使用时区构造时删除datetime64弃用警告#

numpy.datetime64方法现在每当提供的日期时间字符串中包含时区时，都会发出UserWarning而不是DeprecationWarning。

(gh-24193)

64位Windows上的默认整数dtype现在为64位#

现在所有64位系统上的默认NumPy整数都是64位，因为Windows上历史的32位默认值是问题的常见来源。大多数用户不会注意到这一点。主要问题可能出现在与用C等编译语言编写的库交互的代码中。有关更多信息，请参阅Windows默认整数。

(gh-24224)

将numpy.core重命名为numpy._core#

访问numpy.core现在会发出DeprecationWarning。在实践中，我们发现大多数下游对numpy.core的使用是为了访问主numpy命名空间中可用的功能。如果您出于某种原因正在使用numpy.core中主numpy命名空间中不可用的功能，这意味着您可能正在使用私有的NumPy内部机制。您仍然可以通过numpy._core访问这些内部机制而不会出现弃用警告，但我们不对NumPy内部机制提供任何向后兼容性保证。如果您认为犯了错误并且需要公开某些内容，请创建一个问题。

(gh-24634)

已删除以前通过NPY_RELAXED_STRIDES_DEBUG环境变量或-Drelaxed-strides-debug配置设置标志启用的“宽松步幅”调试构建选项。

(gh-24717)

重新定义 np.intp/np.uintp (几乎不会改变)#

由于这些类型的实际使用几乎总是与 size_t/Py_ssize_t 的使用匹配，因此现在在 C 中的定义也是如此。以前，它与 intptr_t 和 uintptr_t 匹配，这往往会细微地不正确。这对绝大多数机器没有影响，因为这些类型的尺寸只在极少数平台上有所不同。

但是，这意味着

  • 指针可能不再一定适合于 intp 类型数组。但是，仍然可以使用 p 和 P 字符代码。

  • 在 C 中创建 intptr_t 或 uintptr_t 类型数组仍然可以通过 PyArray_DescrFromType('p') 以跨平台的方式实现。

  • 引入了新的字符代码 nN。

  • 现在在解析为 npy_intp 类型参数时使用 Python C-API 函数是正确的。

(gh-24888)

numpy.fft.helper 变为私有模块#

numpy.fft.helper 已重命名为 numpy.fft._helper，以指示它是一个私有子模块。它导出的所有公共函数都应该从 numpy.fft 访问。

(gh-24945)

numpy.linalg.linalg 变为私有模块#

numpy.linalg.linalg 已重命名为 numpy.linalg._linalg，以指示它是一个私有子模块。它导出的所有公共函数都应该从 numpy.linalg 访问。

(gh-24946)

越界轴不等于 axis=None#

在某些情况下，axis=32 或对于连接任何较大的值都与 axis=None 相同。除了 concatenate 之外，这已被弃用。任何越界轴值现在都会报错，请确保使用 axis=None。

(gh-25149)

array 和 asarray 构造函数的新 copy 关键字含义#

现在 numpy.array 和 numpy.asarray 支持 copy 参数的三个值

  • None - 只有在必要时才会进行复制。

  • True - 始终进行复制。

  • False - 从不进行复制。如果需要复制，则会引发 ValueError。

False 的含义已更改，因为它现在如果需要复制则会引发异常。

(gh-25168)

__array__ 特殊方法现在接受 copy 关键字参数。#

在将 copy 设置为非默认值的情况下（例如，在调用 np.asarray(some_object, copy=False) 时），NumPy 会将 copy 传递给 __array__ 特殊方法。目前，如果在此之后引发了意外的关键字参数错误，NumPy 将发出警告并尝试不使用 copy 关键字参数。实现 __array__ 协议的对象的实现应该接受一个 copy 关键字参数，其含义与传递给 numpy.array 或 numpy.asarray 时相同。

(gh-25168)

清理使用带逗号的字符串初始化 numpy.dtype#

带逗号的字符串的解释略有更改，因为尾随逗号现在将始终创建一个结构化 dtype。例如，以前 np.dtype("i") 和 np.dtype("i,") 被视为相同，现在 np.dtype("i,") 将创建一个结构化 dtype，只有一个字段。这类似于 np.dtype("i,i") 创建一个具有两个字段的结构化 dtype，并使行为与元组的预期行为一致。

同时，弃用了使用括号括起来的单个数字来表示子数组形状，例如在 np.dtype("(2)i,") 中。相反，应该使用 np.dtype("(2,)i") 或 np.dtype("2i")。最终，使用括号中的数字将引发异常，就像没有逗号的初始化一样，例如 np.dtype("(2)i")。

(gh-25434)

复数符号计算方式的更改#

遵循数组 API 标准，复数符号现在计算为 z / |z|（而不是相当不合理的案例，其中取实部的符号，除非实部为零，在这种情况下返回虚部的符号）。与实数一样，如果 z==0，则返回零。

(gh-25441)

返回 ndarray 列表的函数的返回类型#

返回 ndarray 列表的函数已更改为改为返回 ndarray 元组。在返回数组序列时始终返回元组，这使得像 Numba 这样的 JIT 编译器以及某些情况下的静态类型检查器更容易支持这些函数。已更改的函数为：atleast_1d，atleast_2d，atleast_3d，broadcast_arrays，meshgrid，ogrid，histogramdd。

np.unique 的 return_inverse 参数在多维输入下的形状#

当将多维输入传递给带有 return_inverse=True 的 np.unique 时，unique_inverse 输出现在具有这样的形状：当 axis=None 时，可以使用 np.take(unique, unique_inverse) 直接重建输入，否则使用 np.take_along_axis(unique, unique_inverse, axis=axis)。

注意

除了 axis=None 外，此更改已在 2.0.1 中恢复。正确的重建始终是 np.take(unique, unique_inverse, axis=axis)。当需要支持 2.0.0 时，请将 unique_inverse.reshape(-1) 添加到代码中。

(gh-25553, gh-25570)

any 和 all 对对象数组返回布尔值#

any 和 all 函数和方法现在也对对象数组返回布尔值。以前，它们进行归约，其行为类似于 Python 的 or 和 and 运算符，其结果为参数之一。可以使用 np.logical_or.reduce 和 np.logical_and.reduce 来实现以前的`行为。

(gh-25712)

无法对 Python int、float 或 complex 调用 np.can_cast#

np.can_cast 现在无法再使用 Python 的 int、float 或 complex 实例调用了。这是因为 NEP 50 意味着can_cast 的结果不能依赖于传入的值。不幸的是，对于 Python 标量，是否应该将转换视为"same_kind" 或"safe" 可能取决于上下文和值，因此目前尚未实现此功能。在某些情况下，这意味着您可能需要为以下情况添加特定的路径：if type(obj) in (int, float, complex): ...。

(gh-26393)

本页内容