数组 API 标准兼容性#

笔记

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

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

该numpy.array_api模块充当数组 API 标准的最小参考实现。在最小化中，该模块仅实现规范明确要求的那些内容。某些事情是规范允许的，但在 numpy.array_api.这样该模块就可以作为数组 API 标准用户的参考实现。数组 API 的任何使用者都可以测试他们的代码，numpy.array_api并确保他们没有使用规范未保证的任何功能，以及其他符合标准的库中可能不存在的功能。

numpy.array_api此处未记录该模块。有关数组 API 规范中存在的函数列表，请参阅数组 API 标准。该numpy.array_api 实现在功能上是完整的，因此标准中描述的所有功能都已实现。

numpy.array_api和#之间的差异表numpy

numpy.array_api此表概述了与主命名空间之间的主要区别numpy。差异可分为三类：

  1. 严格。所做的事情只是为了numpy.array_api严格、最低限度的实施。规范实际上并不要求它们，并且其他符合标准的库可能不遵循它们。在大多数情况下，规范不指定或要求给定域之外的任何行为。主numpy命名空间无需以任何方式更改即可与这些规范兼容。

  2. 兼容的。可以添加到主命名numpy空间而不破坏向后兼容性的东西。

  3. 打破。如果在主命名空间中实现，则会破坏向后兼容性numpy。

名称差异#

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

函数名称更改#

以下函数在数组 API 中的命名不同

数组 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，axis关键字参数 to permute_dims是必需的。

pow

power

unique_all，unique_counts，unique_inverse， 和 unique_values

unique

每个都相当于np.unique设置了某些标志。

函数而不是方法#

  • astype是数组 API 中的函数，而它是 ndarrayin中的方法numpy。

linalg命名空间差异#

这些函数位于linalg数组 API 的子命名空间中，但仅位于 NumPy 的顶级命名空间中：

  • cross

  • diagonal

  • matmul(*)

  • outer

  • tensordot(*)

  • trace

(*)：这些函数也位于数组 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 中，任何操作的结果类型始终完全由输入类型决定，与值或形状无关。

特征

类型

笔记

有限的数据类型集。

严格

numpy.array_api仅实现规范所需的数据类型。

Python 标量的运算符（如+）仅接受匹配的标量类型。

严格

例如，不允许。请参阅混合数组和 Python 标量的规范规则。<int32 array> + 1.0

Python 标量的运算符（如+）始终返回与数组相同的数据类型。

打破

例如，是一个 数组。numpy.array_api.asarray(0., dtype=float32) + 1e64float32

当提升左侧时，不允许使用就地运算符。

打破

例子：。规范明确不允许这样做。a = np.array(1, dtype=np.int8); a += np.array(1, dtype=np.int16)

当右侧操作数无法广播到左侧操作数的形状时，不允许使用就地运算符。

严格

这种所谓的“反向传播”是不应该被允许的。示例： 应该错误。请参阅 https://github.com/numpy/numpy/issues/10404。a = np.empty((2, 3, 4)); a += np.empty((3, 4))

int运算符的提升仅针对数据类型范围内的整数指定。

严格

numpy.array_api回退到np.ndarray行为（cast 或 raise OverflowError）。

__pow__并且__rpow__不对 0 维数组进行基于值的转换。

打破

例如，是。请注意，这是对 0 维数组而不是标量进行基于值的转换。np.array(0., dtype=float32)**np.array(0., dtype=float64)float32

无跨种铸造。

严格

也就是说，布尔、整数和浮点数据类型不会相互转换，除非显式使用astype（这与 Python 标量的行为不同）。

不能将无符号整数数据类型转换为浮点数据类型（例如，.int64 + uint64 -> float64

严格

can_cast并result_type受到限制。

严格

这些numpy.array_api实现不允许跨种类铸造。

sum并prod总是昂首阔步float32到float64什么时候 dtype=None。

打破

索引差异#

该规范仅需要索引的子集，但规范中的所有索引规则都与 NumPy 更广泛的索引规则兼容。

特征

类型

笔记

没有隐式省略号 ( ...)。

严格

如果索引不包含省略号，则必须对所有轴进行索引。

切片的开始和结束不得越界。

严格

对于 slice i:j:k，仅允许以下内容：

  • i或j省略( None)。

  • -n <= i <= max(0, n - 1)。

  • 对于或省略 ( ), .k > 0kNone-n <= j <= n

  • 为了，。k < 0-n - 1 <= j <= max(0, n - 1)

布尔数组索引仅允许作为唯一索引。

严格

根本不允许整数数组索引。

严格

0 维数组除外，它们被视为整数。

类型严格#

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

  • 浮点数:float32或float64.

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

  • 布尔值：bool.

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

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

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

在所有情况下，返回数据类型都是根据规范 中概述的规则进行选择的，并且与任何允许的输入数据类型的 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

浮点

cross

数字

det

浮点

diagonal

任何

eigh

浮点

eighvals

浮点

inv

浮点

matmul

数字

matrix_norm(*)

浮点

matrix_power

浮点

matrix_rank

浮点

matrix_transpose(**)

任何

outer

数字

pinv

浮点

qr

浮点

slogdet

浮点

solve

浮点

svd

浮点

svdvals(**)

浮点

tensordot

数字

trace

数字

vecdot(**)

数字

vector_norm(*)

浮点

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

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

数组对象#

__operator__数组对象上的所有特殊方法的行为与其相应的函数相同（ 有关哪些方法对应于哪些函数的列表，请参阅规范）。例外情况是，运算符根据规范中概述的规则显式允许 Python 标量 （请参阅类型提升差异）。

数组对象差异#

特征

类型

笔记

没有数组标量

严格

该规范没有数组标量，只有 0 维数组。但是，除了 类型提升差异中概述的提升差异之外，出于规范的目的，标量将类型鸭为 0 维数组。它们是不可变的，但规范 不要求可变性。

bool()、int()、 且float()仅适用于 0 维数组。

严格

请参阅https://github.com/numpy/numpy/issues/10404。

__imatmul__

兼容的

np.ndarray目前没有实施__imatmul。请注意， 仅当它不改变 的形状时才应定义 。a @= ba

mT矩阵转置的属性。

兼容的

请参阅 的规范定义mT。

T如果输入不是二维的，该属性应该出错。

打破

请参阅规范中的注释。

新方法to_device和属性device

兼容的

这些方法实际上不会执行任何操作，因为 NumPy 仅适用于 CPU

创建函数差异#

特征

类型

笔记

copy关键字参数asarray

兼容的

所有数组创建函数的新device关键字参数（asarray、arange、empty、empty_like、eye、full、 full_like、linspace、ones、ones_like、zeros和 zeros_like）。

兼容的

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函数返回 a tuple，结果数组的顺序相同。

新功能matrix_norm和vector_norm.

兼容的

该norm函数已从数组 API 中省略，并分为matrix_norm矩阵范数和vector_norm向量范数。请注意，vector_norm支持任意数量的轴，而 np.linalg.norm矢量范数仅支持单个轴。

matrix_rank有一个rtol关键字参数而不是tol.

打破

在数组 API 中，rtol过滤小于 的奇异值 。在 中， 过滤小于 的奇异值。此外， 的默认值为，而in的默认值为，其中是输入的奇异值。新的标志名称是兼容的，但默认的更改正在破坏rtol * largest_singular_valuenp.linalg.matrix_ranktoltolrtolmax(M, N) * epstolnp.linalg.matrix_rankS.max() * max(M, N) * epsS

matrix_rank不支持一维数组。

打破

新功能matrix_transpose。

兼容的

与 不同np.transpose，matrix_transpose仅转置最后两个轴。请参阅规范定义

outer仅支持一维数组。

打破

该规范目前仅指定一维数组上的行为，但未来的行为可能是广播，而不是展平，这正是所做的np.outer。

pinv有一个rtol关键字参数而不是rcond

打破

rtol和的含义rcond相同，但 的默认值为rtol，而 的默认值为。新的标志名称是兼容的，但默认的更改会被破坏。max(M, N) * epsrcond1e-15

solve仅当它恰好是一维时才接受x2作为向量。

打破

行为np.linalg.solve是模棱两可的。有关更多详细信息，请参阅此 numpy 问题和此数组 API 规范问题。

新功能svdvals。

兼容的

相当于np.linalg.svd(compute_uv=False)。

关键字axistotensordot必须是元组。

兼容的

在 中np.tensordot，它也可以是数组或类数组。

trace在最后两个轴上运行。

打破

np.trace默认情况下在前两个轴上运行。请注意，数组 APItrace不允许指定要操作的轴。

操作函数差异#

特征

类型

笔记

各种功能已重命名

兼容的

请参阅函数名称更改。

concat具有不同的默认转换规则np.concatenate

严格

无跨种铸造。标量上没有基于值的转换（当 axis=None 时）。

stack具有不同的默认转换规则np.stack

严格

无跨种铸造。

新功能permute_dims。

兼容的

与 不同np.transpose，axis关键字参数 to permute_dims是必需的。

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总是昂首阔步float32到float64什么时候 dtype=None。

打破

stdand函数var有一个correction关键字参数而不是ddof。

兼容的

其他差异#

特征

类型

笔记

Dtype 只能拼写为 dtype 对象。

严格

例如，不允许。numpy.array_api.asarray([0], dtype='int32')

asarray不会在任何函数中隐式调用。

严格

Python 运算符是个例外，它在某些情况下接受 Python 标量（请参阅类型提升差异）。

tril并triu要求输入至少是二维的。

严格

finfo() 返回类型用于float各种属性。

严格

该规范允许鸭子类型，因此finfo返回 dtype 标量被认为是与float.

每个函数中的位置参数都是位置参数。

打破

请参阅规范以了解每个函数的确切签名。请注意，NumPy ufunc 已经使用仅位置参数，但非 ufunc 通常 asarray不使用。