Numba 0.64.0 版本解析:NumPy 2.4 支持、np.moveaxis 新增与关键 Bug 修复详解

原创2026-09-23 17:01:441,733 阅读
文章标签:编译器高性能计算

Numba 0.64.0 版本解析:NumPy 2.4 支持、np.moveaxis 新增与关键 Bug 修复详解

Numba 0.64.0 是一个重要的主版本发布,核心亮点是正式支持 NumPy 2.4,同时新增了对 np.moveaxis 的 nopython 模式支持,并修复了 np.all / np.any 标量处理、数组布局转换 readonly 处理、s390x 整数类型提升、Python 3.11 大整数幂运算精度等一系列问题。本文以官方发布说明(docs/source/release/0.64.0-notes.rst)为骨架,结合仓库源码与测试用例,逐项剖析这些变更的实现原理与迁移影响,帮助读者在升级到 0.64.0 时顺利完成 NumPy 兼容性切换并规避潜在陷阱。

版本概览与兼容性声明

Numba 0.64.0 发布于 2026 年 2 月 18 日,属于主版本(major release)发布。发布说明开篇即点明本版本的核心能力变化:

Numba now supports NumPy 2.4.

这一定位意味着:使用 0.64.0 的开发者可以在已经升级到 NumPy 2.4 的 Python 环境中继续使用 Numba 的 nopython 模式对数组操作进行 JIT 编译,而无需回退 NumPy 版本。与 NumPy 支持同步推进的还有对 Python 3.14 的持续适配(见 PR #10256、#10339 的 CI/依赖更新),以及 CI 从 Azure 向 GitHub Actions 迁移、osx-64 被列入 Tier 2 支持列表等工程化调整(PR #10347、#10384)。

从发布说明的 PR 列表看,0.64.0 汇聚了来自社区十余名贡献者的约 30 个合并请求,内容涵盖 NumPy 兼容、新功能、缺陷修复、CI/文档维护四大类。本文聚焦其中的功能性变更,逐个展开源码级分析。

NumPy 2.4 支持:两个必须注意的 API 移除

NumPy 2.4 对 Numba 最直接的影响是移除了两个旧 API,若代码中仍在调用它们,升级后会在 nopython 模式下直接报错。官方建议如下:

np.trapz 已被移除,改用 np.trapezoid

  • NumPy 2.4 中 np.trapz 被彻底移除;
  • 替代方案是 np.trapezoid,该函数自 NumPy 2.0 起即已可用;
  • 迁移时只需将调用名从 np.trapz 替换为 np.trapezoid,参数签名(y、x、dx、axis)保持一致。

np.in1d 已被移除,改用 np.isin

  • NumPy 2.4 中 np.in1d 被彻底移除;
  • 替代方案是 np.isin,语义等价:判断第一个数组中的元素是否出现在第二个数组中;
  • 迁移时替换函数名即可,np.isin 同样支持 assume_unique、invert 等参数。

这两项调整的落地由 PR #10393(add Numpy 2.4 support)完成,并配套 PR #10417(Fix: NumPy2.4 CI test error)修复了 CI 中的兼容性测试问题。对于 Numba 使用者来说,这是升级 0.64.0 时最需要主动执行的代码迁移动作——因为 Numba 的 nopython 模式并不拦截对已移除 API 的调用,错误会以 TypingError 或运行时错误的形式暴露出来,提前替换更稳妥。

新功能:np.moveaxis 的 nopython 模式支持

np.moveaxis 是 NumPy 中用于将数组的轴移动到新位置的高频函数,常用于维度重排。此前 Numba 的 nopython 模式并不支持它,0.64.0 通过 PR #10366 补齐了这一能力。

实现原理:基于 transpose 的轴重排

Numba 对 np.moveaxis 的实现位于 numba/np/arrayobj.py,通过 @overload(np.moveaxis) 注册:

@overload(np.moveaxis)
def numpy_moveaxis(a, source, destination):
    if not isinstance(a, types.Array):
        raise errors.TypingError('The first argument "a" must be an array')
    ...
    def impl(a, source, destination):
        source = normalize_axis_tuple("np.moveaxis", "source", ndim, source)
        destination = normalize_axis_tuple("np.moveaxis", "destination", ndim, destination)
        if len(source) != len(destination):
            raise ValueError(...)
        order_list = [n for n in range(a.ndim) if n not in source]
        for dest, src in sorted(zip(destination, source)):
            order_list.insert(dest, src)
        order = order_init
        for i, o in enumerate(order_list):
            order = tuple_setitem(order, i, o)
        return a.transpose(order)
    return impl

从源码结构可以清晰地看出其设计思路:np.moveaxis 在 Numba 中不是独立实现的高维搬移逻辑,而是先计算一个轴置换顺序(order),再复用底层已经高度优化的 a.transpose(order)。这既避免了重复实现内存搬移逻辑,又保证了与 NumPy 语义的一致性——np.moveaxis 本身在 NumPy 中的实现也是基于转置的视图操作,不复制数据。

类型检查方面,实现严格约束了三类参数:

参数 允许类型 非法输入时的报错信息
a 数组(types.Array) The first argument "a" must be an array
source 整数或整数序列(types.Integer / types.Sequence) The second argument "source" must be an integer or sequence of integers
destination 整数或整数序列(types.Integer / types.Sequence) The third argument "destination" must be an integer or sequence of integers

支持负数轴索引与元组形式的 source/destination,与 NumPy 行为对齐。

测试覆盖:边界条件与异常路径

测试位于 numba/tests/test_np_functions.py,分为功能与异常两组:

功能测试(test_moveaxis_basic) 使用 np.arange(120).reshape(1, 2, 3, 4, 5) 这一 5 维数组,覆盖了多组 source/destination 组合:

for source, destination in (
    (0, -1),              # 负轴索引
    (1, 3),               # 单轴移动
    ((0, 1), (-1, -2)),   # 多轴 + 负索引
    ((0, 1), (-2, -1)),   # 多轴顺序交换
    ((1, -3), (-2, 4)),   # 混合正负索引
):
    expected = pyfunc(a, source, destination)
    got = cfunc(a, source, destination)
    self.assertPreciseEqual(expected, got)

每组结果都与纯 Python 版 NumPy 调用做 assertPreciseEqual 精确比对,验证 nopython 编译结果与 NumPy 语义完全一致。

异常测试(test_moveaxis_exception) 则验证了四条错误路径:

  • 非数组输入、非整数 source/destination 触发 TypingError,并断言了对应的报错文案;
  • cfunc(np.arange(4), 1, 0) 触发 ValueError: np.moveaxis: Argument source out of bounds;
  • (0, 1) -> (1, -3) 触发 np.moveaxis: Argument destination out of bounds;
  • (0, 0) 重复轴触发 np.moveaxis: repeated axis in source argument;
  • (0, 1) -> (1, -1) 触发 np.moveaxis: repeated axis in destination argument。

这些测试一方面保证了实现的正确性,另一方面也表明越界与重复轴的报错文案与 NumPy 保持一致,便于开发者排错。

使用示例

import numpy as np
from numba import njit

@njit
def shift_axis(a):
    # 将第 0 轴移动到最后一维
    return np.moveaxis(a, 0, -1)

a = np.arange(24).reshape(2, 3, 4)
print(shift_axis(a).shape)  # (3, 4, 2)

Bug 修复详解

0.64.0 共修复了五类功能性缺陷,其中多数影响面较大,值得逐一关注。

np.all 与 np.any 的标量输入处理

问题背景:在 0.64.0 之前,np.all 和 np.any 在 nopython 模式下被传入标量(如 np.all(5)、np.any(0))时会失败。这是因为此前的 overload 实现只考虑了数组输入,标量路径缺失。

修复内容(PR #10223、#10224):以 np.all 为例,修复后的实现在 numba/np/arraymath.py 中为标量增加了独立分支:

@overload(np.all)
@overload_method(types.Array, "all")
def np_all(a):
    # for scalar
    if isinstance(a, (types.Number, types.Boolean)):
        def scalar_all(a):
            return bool(a)
        return scalar_all

    if isinstance(a, (NPDatetime, NPTimedelta)):
        def temporal_scalar_all(a):
            return np.int64(a) != 0
        return temporal_scalar_all

    # for array
    if isinstance(a, types.Array):
        def flat_all(a):
            for v in np.nditer(a):
                if not v.item():
                    return False
            return True
        return flat_all
    return None

np.any 的修复(PR #10224)与之对称,同样增加了标量分支,将标量转换为布尔值。从源码看,该 overload 同时服务于 np.all 函数与数组方法 .all()(通过 @overload_method 注册),因此这一修复对两种调用形式都生效。

修复后的行为语义为:

  • 标量输入:np.all(x) 等价于 bool(x),np.any(x) 同样等价于 bool(x)(对 NPDatetime/NPTimedelta 则比较其 int64 表示是否为 0);
  • 数组输入:维持原有逻辑,遍历所有元素判断是否全真/存在真值。

np.asfortranarray / np.ascontiguousarray 的 readonly 处理

问题背景(对应 issue #10357):此前当输入数组是只读(readonly)时,即使通过 np.asfortranarray 或 np.ascontiguousarray 产生了新的拷贝,返回的数组仍然继承 readonly 标志。这与 NumPy 语义不符——拷贝理应产生可写的新数组。

修复内容(PR #10390):核心修改在 numba/np/arrayobj.py 的 _as_layout_array 与新增的 _as_layout_array_intrinsic 中。布局转换的内在逻辑是:

  1. 0 维输入:asfortranarray() 返回 1 维数组(shape 为 (1,));
  2. 输入布局与目标布局一致(或 1 维且为 C/F 任一连续布局):直接返回原数组(借用,不拷贝);
  3. 输入布局未知(layout == 'A'):编译期无法确定,运行时用 is_contiguous / is_fortran 检查,已连续则直接返回,否则拷贝;
  4. 其余情况:拷贝为指定布局的新数组。

修复的关键在于拷贝路径:新增的 intrinsic _as_layout_array_intrinsic 在构造返回类型时显式指定:

ret = a.copy(
    layout=output_layout.literal_value,
    ndim=max(a.ndim, 1),
    readonly=False)   # 拷贝结果必须是可写的

即:凡是通过拷贝得到的新数组,其 readonly 一律置为 False;而直接借用原数组的路径(布局已匹配)则保留原数组的属性。这样既符合 NumPy 语义(拷贝产生可写数组),又避免了不必要的拷贝开销。

两个 overload 的完整行为:

  • np.ascontiguousarray(a):标量/布尔输入先 np.array(a) 再转 C 连续布局;数组输入走 _as_layout_array_intrinsic(a, 'C');
  • np.asfortranarray(a):标量/布尔输入先 np.array(a) 再转 Fortran 连续布局;数组输入走 _as_layout_array_intrinsic(a, 'F')。

同时 _as_layout_array 中明确断言返回类型布局与目标布局一致(assert retty.layout == output_layout),保证编译期类型与运行时行为相符。

s390x 上整数类型提升(SystemZ ABI 兼容)

问题背景:在 s390x(IBM Z)架构上,pythonapi 相关路径存在段错误(segmentation fault)。根因是 SystemZ ABI 要求整数参数在传入函数时须提升到完整的寄存器宽度,而 Numba 在 CPU 与 Python API 的 lowering 层没有执行这一提升。

修复内容(PR #10396):在 CPU 与 Python API 的 lowering 层为整数类型补充了完整的寄存器宽度提升逻辑,确保在 s390x 上按 ABI 规范传递整数。这一修复对大多数 x86/ARM 用户无感知,但对 IBM Z 上的部署而言是关键的正确性补丁。

Python 3.11 大整数幂运算精度丢失

问题背景(对应 issue #9931):在 Python 3.11 上,nopython 模式中执行整数幂运算(如 x ** 2)时,当结果大于 2^53 会出现精度丢失。2^53 正是 IEEE 754 double 可以无损表示的最大整数,说明幂运算路径中存在隐式的浮点转换。

修复内容(PR #10398):修复后,整数幂运算在结果大于 2^53 时仍保持完整整数精度。此修复针对 Python 3.11 生效,修复后的行为可验证如下:

import numpy as np
from numba import njit

@njit
def power2(x):
    return x ** 2

# 2^53 之上,必须保持精确整数结果
x = 2**27 + 1          # 大于 2^53 开方后的整数
print(power2(x))       # 结果不再丢失精度
print(power2(x) == (2**27 + 1) ** 2)  # True

对于依赖大整数精确运算的数值代码,这一修复避免了静默的精度污染。

工程与 CI 层面的变更

发布说明的 PR 列表中还包含若干不直接改变用户可见功能、但对项目演进有意义的工程调整,简述如下:

  • CI 迁移与清理:将 osx64 相关的 Azure 流水线移除并迁移至 GitHub Actions(PR #10347),删除 pre-commit 配置(PR #10351),新增 numba 定时测试工作流(PR #10324);
  • 依赖与工具链升级:Python 依赖版本提升至 3.14(PR #10339),wheel 构建工作流改为安装预发布的 llvmlite 版本(PR #10391),并对 conda-libmamba-solver 添加版本约束(PR #10359);
  • 版本支持表更新:为 0.64.0rc1 及正式版更新版本支持矩阵(PR #10422、#10438),并将 osx-64 加入 Tier 2 支持列表(PR #10384);
  • 文档修正:修正 macOS 上 OpenMP 依赖说明与正文不一致的问题(PR #10369);
  • 0.63.x 补丁回移:将 0.63.0 与 0.63.1 的修复 cherry-pick 进入本版本线(PR #10371、#10378)。

升级到 0.64.0 的行动清单

结合发布说明与源码分析,从 0.63.x 升级到 0.64.0 时建议按以下顺序核对:

  1. NumPy 版本:确认环境中的 NumPy 已升级到 2.4(本版本的核心能力);
  2. API 迁移:全局搜索并替换 np.trapz → np.trapezoid、np.in1d → np.isin;
  3. 标量断言:如代码中大量使用 np.all(...) / np.any(...) 且可能传入标量,0.64.0 后行为与 NumPy 对齐(标量转 bool),可放心移除以往的规避写法;
  4. 布局转换:如依赖 np.asfortranarray / np.ascontiguousarray 的结果可写性,0.64.0 的拷贝路径已保证返回可写数组;
  5. 平台验证:若在 s390x(IBM Z)部署,务必升级以修复 pythonapi 段错误;若在 Python 3.11 上做超大整数幂运算,升级后可获得完整精度;
  6. 新能力:np.moveaxis 现在可直接在 @njit 函数中使用,替代手动 transpose 的繁琐写法。

关键源码与测试索引

登录后查看全文
numba