数组 API 标准兼容性

注意

numpy.array_api 模块仍处于实验阶段。请参阅 NEP 47。

NumPy 在 numpy.array_api 中包含 array API 标准 的参考实现。 NEP 47 描述了在 NumPy 中实现 array API 标准的动机和范围。

numpy.array_api 模块作为 array API 标准的最小参考实现。作为最小实现，该模块仅实现规范中明确要求的内容。规范允许某些内容，但在 numpy.array_api 中明确禁止。这是为了让该模块可以作为 array API 标准用户的参考实现。array API 的任何使用者都可以针对 numpy.array_api 测试其代码，并确保他们没有使用任何未由规范保证且可能不存在于其他符合规范的库中的功能。

numpy.array_api 模块在此处未记录。有关 array API 规范中存在的函数的列表，请参阅 array API 标准。 numpy.array_api 实现功能齐全，因此实现了标准中描述的所有功能。

numpy.array_api 和 numpy 之间的差异表

此表概述了 numpy.array_api 与主 numpy 命名空间之间的主要差异。有三种类型的差异

1. 严格性。仅执行此操作以使 numpy.array_api 成为严格的最小实现。规范实际上并不需要它们，其他符合规范的库可能不会遵循它们。在大多数情况下，规范不会指定或要求给定域之外的任何行为。主 numpy 命名空间无需以任何方式更改以实现这些规范的兼容性。

2. 兼容性。可以在不破坏向后兼容性的情况下添加到主 numpy 命名空间的内容。

3. 破坏性更改。如果在主 numpy 命名空间中实现，将破坏向后兼容性。

名称差异

规范中已重命名许多 NumPy 函数。这些函数在行为上完全相同，因此都是兼容性更改，除非另有说明。

函数名称更改

以下函数在 array API 中的名称不同

Array API 名称	NumPy 命名空间名称	备注
acos	arccos
acosh	arccosh
asin	arcsin
asinh	arcsinh
atan	arctan
atan2	arctan2
atanh	arctanh
bitwise_left_shift	left_shift
bitwise_invert	invert
bitwise_right_shift	right_shift
bool	bool_	这是破坏性更改，因为 np.bool 目前是内置 bool 的弃用别名。
concat	concatenate
matrix_norm 和 vector_norm	norm	matrix_norm 和 vector_norm 各执行 np.norm 执行的有限子集。
permute_dims	transpose	与 np.transpose 不同，permute_dims 中的 axis 关键字参数是必需的。
pow	power
unique_all、unique_counts、unique_inverse 和 unique_values	unique	每个都等效于设置了特定标志的 np.unique。

函数而非方法

• astype 是 array API 中的函数，而它是 numpy 中 ndarray 上的方法。

linalg 命名空间差异

这些函数在 array API 中的 linalg 子命名空间中，但在 NumPy 中仅在顶级命名空间中

• 交叉

• 对角线

• 矩阵乘法 (*)

• 外积

• 张量点积 (*)

• 迹

(*): 这些函数也在数组 API 的顶级命名空间中。

关键字参数重命名

以下函数具有已重命名的关键字参数。除非另有说明，否则关键字参数的功能相同。具有相同语义定义的重命名关键字参数可以视为 **兼容** 或 **破坏**，具体取决于更改的实现方式。

请注意，此页面未列出主 numpy 命名空间中但不在数组 API 中的函数关键字参数。此类关键字参数从 numpy.array_api 中省略，以确保 **严格性**，因为规范允许函数包含必需关键字参数之外的其他关键字参数。

函数	数组 API 关键字名称	NumPy 关键字名称	备注
argsort 和 sort	stable	kind	stable 和 kind 的定义不同，默认值也不同。默认值更改使此项 **破坏**。请参阅 集合函数差异。
matrix_rank	rtol	tol	rtol 和 tol 的定义不同，默认值也不同。默认值更改使此项 **破坏**。请参阅 线性代数差异。
pinv	rtol	rcond	rtol 和 rcond 的定义相同，但默认值不同，使此项 **破坏**。请参阅 线性代数差异。
std 和 var	correction	ddof
reshape	shape	newshape	对于 NumPy 和数组 API，该参数可以作为位置参数或关键字参数传递。

类型提升差异

类型提升是 NumPy 偏离规范的最大领域。最显著的差异是 NumPy 在许多情况下执行基于值的转换。该规范明确禁止基于值的转换。在数组 API 中，任何操作的结果类型始终完全由输入类型决定，与值或形状无关。

特性	类型	备注
有限的 dtypes 集合。	严格性	numpy.array_api 仅实现规范要求的那些 dtypes。
具有 Python 标量的运算符（如 +）仅接受匹配的标量类型。	严格性	例如，<int32 array> + 1.0 不被允许。请参阅 将数组与 Python 标量混合的规范规则。
具有 Python 标量的运算符（如 +）始终返回与数组相同的 dtype。	中断	例如，numpy.array_api.asarray(0., dtype=float32) + 1e64 是一个 float32 数组。
当左侧会被提升时，不允许就地运算符。	中断	示例：a = np.array(1, dtype=np.int8); a += np.array(1, dtype=np.int16)。该规范明确禁止这一点。
当右侧操作数无法广播到左侧操作数的形状时，不允许就地运算符。	严格性	这种所谓的“反向广播”不应该被允许。示例：a = np.empty((2, 3, 4)); a += np.empty((3, 4)) 应该出错。请参阅 https://github.com/numpy/numpy/issues/10404。
运算符的int 提升仅针对 dtype 范围内的整数指定。	严格性	numpy.array_api 回退到 np.ndarray 行为（转换或引发 OverflowError）。
__pow__ 和 __rpow__ 不对 0-D 数组执行基于值的转换。	中断	例如，np.array(0., dtype=float32)**np.array(0., dtype=float64) 是 float32。请注意，这是对 0-D 数组的基于值的转换，而不是标量。
没有跨类型转换。	严格性	即，布尔值、整数和浮点数据类型不会相互转换，除非使用 astype 显式转换（这与 Python 标量行为不同）。
没有将无符号整数数据类型转换为浮点数据类型（例如，int64 + uint64 -> float64。	严格性
can_cast 和 result_type 受到限制。	严格性	numpy.array_api 实现不允许跨类型转换。
sum 和 prod 在 dtype=None 时始终将 float32 提升为 float64。	中断

索引差异

该规范仅要求使用部分索引，但规范中的所有索引规则都与 NumPy 更广泛的索引规则兼容。

特性	类型	备注
没有隐式省略号 (...)。	严格性	如果索引不包含省略号，则必须对所有轴进行索引。
切片的开始和结束不能超出界限。	严格性	对于切片 i:j:k，仅允许以下情况 i 或 j 省略（None）。 -n <= i <= max(0, n - 1). 对于 k > 0 或 k 省略（None），-n <= j <= n。 对于 k < 0，-n - 1 <= j <= max(0, n - 1)。
布尔数组索引仅允许作为唯一索引。	严格性
完全不允许整数数组索引。	严格性	0-D 数组除外，它们被视为整数。

类型严格性

numpy.array_api 中的函数将它们的输入限制为规范明确要求的那些数据类型，即使包装的相应 NumPy 函数允许更广泛的集合。在此，我们列出每个函数和 numpy.array_api 中允许的数据类型。这些是严格性差异，因为规范不要求其他数据类型导致错误。此处定义的类别如下

• 浮点数：float32 或 float64。

• 整数：任何有符号或无符号整数数据类型（int8、int16、int32、int64、uint8、uint16、uint32 或 uint64）。

• 布尔值：bool。

• 整数或布尔值：任何有符号或无符号整数数据类型或 bool。对于双参数函数，两个参数都必须是整数或都必须是 bool。

• 数值：任何整数或浮点数数据类型。对于双参数函数，两个参数都必须是整数或都必须是浮点数。

• 全部：上述任何数据类型类别。对于双参数函数，两个参数必须是同类（整数、浮点数或布尔值）。

在所有情况下，返回数据类型根据 规范中概述的规则 选择，并且对于任何允许的输入数据类型，它与 NumPy 的返回数据类型没有区别，除了以下小节中特别提到的情况。

逐元素函数

函数名称	数据类型
abs	数值
acos	浮点数
acosh	浮点数
add	数值
asin (*)	浮点数
asinh (*)	浮点数
atan (*)	浮点数
atan2 (*)	浮点数
atanh (*)	浮点数
bitwise_and	整数或布尔值
bitwise_invert	整数或布尔值
bitwise_left_shift (*)	整数
bitwise_or	整数或布尔值
bitwise_right_shift (*)	整数
bitwise_xor	整数或布尔值
ceil	数值
cos	浮点数
cosh	浮点数
divide	浮点数
equal	全部
exp	浮点数
expm1	浮点数
floor	数值
floor_divide	数值
greater	数值
greater_equal	数值
isfinite	数值
isinf	数值
isnan	数值
less	数值
less_equal	数值
log	浮点数
logaddexp	浮点数
log10	浮点数
log1p	浮点数
log2	浮点数
logical_and	布尔值
logical_not	布尔值
logical_or	布尔值
logical_xor	布尔值
multiply	数值
negative	数值
not_equal	全部
positive	数值
pow (*)	数值
remainder	数值
round	数值
sign	数值
sin	浮点数
sinh	浮点数
sqrt	浮点数
square	数值
subtract	数值
tan	浮点数
tanh	浮点数
trunc	数值

(*) 这些函数与主 numpy 命名空间中的名称不同。请参见 函数名称更改。

创建函数

函数名称	数据类型
meshgrid	任何（所有输入数据类型必须相同）

线性代数函数

函数名称	数据类型
cholesky	浮点数
交叉	数值
det	浮点数
对角线	任何
eigh	浮点数
eighvals	浮点数
inv	浮点数
矩阵乘法	数值
matrix_norm (*)	浮点数
matrix_power	浮点数
matrix_rank	浮点数
matrix_transpose (**)	任何
外积	数值
pinv	浮点数
qr	浮点数
slogdet	浮点数
solve	浮点数
svd	浮点数
svdvals (**)	浮点数
张量点积	数值
迹	数值
vecdot (**)	数值
vector_norm (*)	浮点数

(*) 这些函数从主 numpy 命名空间中的 norm 中拆分出来。请参见 函数名称更改。

(**) 这些函数是 array API 中的新增函数，不在主 numpy 命名空间中。

数组对象

数组对象上的所有特殊 __operator__ 方法的行为与其对应的函数完全相同（请参见 规范，了解哪些方法对应哪些函数）。例外情况是，运算符根据 规范中概述的规则 明确允许使用 Python 标量（请参见 类型提升差异）。

数组对象差异

特性	类型	备注
无数组标量	严格性	规范中没有数组标量，只有 0-D 数组。但是，除了 类型提升差异 中概述的提升差异之外，标量会将类型转换为 0-D 数组，以用于规范的目的。它们是不可变的，但规范不要求可变性。
bool()、int() 和 float() 仅适用于 0-D 数组。	严格性	参见 https://github.com/numpy/numpy/issues/10404。
__imatmul__	兼容	np.ndarray 当前未实现 __imatmul。请注意，a @= b 仅应在不更改 a 的形状时定义。
矩阵转置的 mT 属性。	兼容	参见 规范定义，了解 mT。
如果输入不是二维，则 T 属性应出错。	中断	参见 规范中的注释。
新方法 to_device 和属性 device	兼容	由于 NumPy 仅限于 CPU，因此这些方法实际上不会执行任何操作

创建函数差异

特性	类型	备注
copy 关键字参数到 asarray	兼容
所有数组创建函数（asarray、arange、empty、empty_like、eye、full、full_like、linspace、ones、ones_like、zeros 和 zeros_like）的新 device 关键字参数。	兼容	device 实际上不会执行任何操作，因为 NumPy 仅限于 CPU。

逐元素函数差异

特性	类型	备注
已重命名各种函数。	兼容	请参阅 函数名称更改。
仅针对给定的输入类型组合定义逐元素函数。	严格性	请参阅 类型严格性。
bitwise_left_shift 和 bitwise_right_shift 仅针对 x2 非负数定义。	严格性
ceil、floor 和 trunc 返回带有整数输入的整数。	中断	np.ceil、np.floor 和 np.trunc 返回带有整数数据类型输入的浮点数据类型。

线性代数差异

特性	类型	备注
cholesky 包含一个 upper 关键字参数。	兼容
cross 不允许大小为 2 的向量（仅允许大小为 3）。	中断
diagonal 对最后两个轴进行操作。	中断	严格来说，这可以是兼容的，因为 diagonal 已移至 linalg 命名空间。
eigh、qr、slogdet 和 svd 返回一个命名元组。	兼容	相应的 numpy 函数返回一个 tuple，其中结果数组按相同顺序排列。
新函数 matrix_norm 和 vector_norm。	兼容	norm 函数已从数组 API 中省略，并拆分为 matrix_norm（用于矩阵范数）和 vector_norm（用于向量范数）。请注意，vector_norm 支持任意数量的轴，而 np.linalg.norm 仅支持向量范数的单个轴。
matrix_rank 具有 rtol 关键字参数，而不是 tol。	中断	在数组 API 中，rtol 筛选小于 rtol * largest_singular_value 的奇异值。在 np.linalg.matrix_rank 中，tol 筛选小于 tol 的奇异值。此外，rtol 的默认值为 max(M, N) * eps，而 np.linalg.matrix_rank 中 tol 的默认值为 S.max() * max(M, N) * eps，其中 S 是输入的奇异值。新标志名称兼容，但默认更改会中断
matrix_rank 不支持一维数组。	中断
新函数 matrix_transpose。	兼容	与 np.transpose 不同，matrix_transpose 仅转置最后两个轴。请参阅 规范定义
outer 仅支持一维数组。	中断	规范目前仅指定一维数组上的行为，但未来的行为很可能是广播，而不是扁平化，而这正是 np.outer 所做的。
pinv 具有 rtol 关键字参数，而不是 rcond	中断	rtol 和 rcond 的含义相同，但 rtol 的默认值为 max(M, N) * eps，而 rcond 的默认值为 1e-15。新标志名称兼容，但默认更改会中断。
solve 仅当 x2 为一维时才接受其作为向量。	中断	np.linalg.solve 行为不明确。有关更多详细信息，请参阅 此 numpy 问题 和 此 array API 规范问题。
新函数 svdvals。	兼容	相当于 np.linalg.svd(compute_uv=False)。
tensordot 的 axis 关键字必须是一个元组。	兼容	在 np.tensordot 中，它还可以是一个数组或类数组。
trace 在最后两个轴上运行。	中断	np.trace 默认情况下在最初两个轴上运行。请注意，数组 API trace 不允许指定在哪些轴上运行。

操作函数差异

特性	类型	备注
各种函数已重命名	兼容	请参阅 函数名称更改。
concat 具有不同于 np.concatenate 的默认转换规则	严格性	无交叉类型转换。标量上无基于值转换（当 axis=None 时）。
stack 具有不同于 np.stack 的默认转换规则	严格性	没有跨类型转换。
新函数 permute_dims。	兼容	与 np.transpose 不同，permute_dims 的 axis 关键字参数是必需的。
reshape 函数具有 copy 关键字参数	兼容	请参见 https://github.com/numpy/numpy/issues/9818。

设置函数差异

特性	类型	备注
新函数 unique_all、unique_counts、unique_inverse 和 unique_values。	兼容	请参阅 函数名称更改。
四个 unique_* 函数返回一个命名元组。	兼容
unique_all 和 unique_indices 返回与 x 形状相同的索引。	兼容	请参见 https://github.com/numpy/numpy/issues/20638。

设置函数差异

特性	类型	备注
argsort 和 sort 具有 stable 关键字参数，而不是 kind。	中断	stable 是一个布尔关键字参数，默认为 True。 kind 采用一个字符串，默认为 "quicksort"。 stable=True 等效于 kind="stable"，kind=False 等效于 kind="quicksort"，尽管当 stable=False 时，规范允许任何排序算法。新标志名称兼容，但默认更改会中断。
argsort 和 sort 有一个 descending 关键字参数。	兼容

统计函数差异

特性	类型	备注
sum 和 prod 在 dtype=None 时始终将 float32 提升为 float64。	中断
std 和 var 函数有一个 correction 关键字参数，而不是 ddof。	兼容

其他差异

特性	类型	备注
数据类型只能拼写为数据类型对象。	严格性	例如，numpy.array_api.asarray([0], dtype='int32') 不被允许。
asarray 不会在任何函数中隐式调用。	严格性	例外是 Python 运算符，它在某些情况下接受 Python 标量（请参阅 类型提升差异）。
tril 和 triu 要求输入至少为 2 维。	严格性
finfo() 返回类型对各种属性使用 float。	严格性	规范允许鸭子类型，因此 finfo 返回数据类型标量被认为与 float 类型兼容。
每个函数中的位置参数都是仅位置的。	中断	请参阅规范以了解每个函数的确切签名。请注意，NumPy ufunc 已使用仅位置参数，但非 ufunc（如 asarray）通常不使用。