Array API Standard Compatibility#
Note
The numpy.array_api
module is still experimental. See NEP 47.
NumPy includes a reference implementation of the array API standard in numpy.array_api
. NEP 47 describes the
motivation and scope for implementing the array API standard in NumPy.
The numpy.array_api
module serves as a minimal, reference implementation
of the array API standard. In being minimal, the module only implements those
things that are explicitly required by the specification. Certain things are
allowed by the specification but are explicitly disallowed in
numpy.array_api
. This is so that the module can serve as a reference
implementation for users of the array API standard. Any consumer of the array
API can test their code against numpy.array_api
and be sure that they
aren’t using any features that aren’t guaranteed by the spec, and which may
not be present in other conforming libraries.
The numpy.array_api
module is not documented here. For a listing of the
functions present in the array API specification, refer to the array API
standard. The numpy.array_api
implementation is functionally complete, so all functionality described in the
standard is implemented.
Table of Differences between numpy.array_api
and numpy
#
This table outlines the primary differences between numpy.array_api
from
the main numpy
namespace. There are three types of differences:
Strictness. Things that are only done so that
numpy.array_api
is a strict, minimal implementation. They aren’t actually required by the spec, and other conforming libraries may not follow them. In most cases, spec does not specify or require any behavior outside of the given domain. The mainnumpy
namespace would not need to change in any way to be speccompatible for these.Compatible. Things that could be added to the main
numpy
namespace without breaking backwards compatibility.Breaking. Things that would break backwards compatibility if implemented in the main
numpy
namespace.
Name Differences#
Many functions have been renamed in the spec from NumPy. These are otherwise identical in behavior, and are thus all compatible changes, unless otherwise noted.
Function Name Changes#
The following functions are named differently in the array API
Array API name 
NumPy namespace name 
Notes 

































This is breaking because 








Unlike 





Each is equivalent to 
Function instead of method#
astype
is a function in the array API, whereas it is a method onndarray
innumpy
.
linalg
Namespace Differences#
These functions are in the linalg
subnamespace in the array API, but are
only in the toplevel namespace in NumPy:
cross
diagonal
matmul
(*)outer
tensordot
(*)trace
(*): These functions are also in the toplevel namespace in the array API.
Keyword Argument Renames#
The following functions have keyword arguments that have been renamed. The functionality of the keyword argument is identical unless otherwise stated. Renamed keyword arguments with the same semantic definition may be considered either compatible or breaking, depending on how the change is implemented.
Note, this page does not list function keyword arguments that are in the main
numpy
namespace but not in the array API. Such keyword arguments are
omitted from numpy.array_api
for strictness, as the spec allows
functions to include additional keyword arguments from those required.
Function 
Array API keyword name 
NumPy keyword name 
Notes 




The definitions of 



The definitions of 



The definitions of 







The argument may be passed as a positional or keyword argument for both NumPy and the array API. 
Type Promotion Differences#
Type promotion is the biggest area where NumPy deviates from the spec. The most notable difference is that NumPy does valuebased casting in many cases. The spec explicitly disallows valuebased casting. In the array API, the result type of any operation is always determined entirely by the input types, independently of values or shapes.
Feature 
Type 
Notes 

Limited set of dtypes. 
Strictness 

Operators (like 
Strictness 
For example, 
Operators (like 
Breaking 
For example, 
Inplace operators are disallowed when the lefthand side would be promoted. 
Breaking 
Example: 
Inplace operators are disallowed when the righthand side operand cannot broadcast to the shape of the lefthand side operand. 
Strictness 
This socalled “reverse broadcasting” should not be allowed. Example:


Strictness 


Breaking 
For example, 
No crosskind casting. 
Strictness 
Namely, boolean, integer, and floatingpoint data types do not cast to
each other, except explicitly with 
No casting unsigned integer dtypes to floating dtypes (e.g., 
Strictness 


Strictness 
The 

Breaking 
Indexing Differences#
The spec requires only a subset of indexing, but all indexing rules in the spec are compatible with NumPy’s more broad indexing rules.
Feature 
Type 
Notes 

No implicit ellipses ( 
Strictness 
If an index does not include an ellipsis, all axes must be indexed. 
The start and stop of a slice may not be out of bounds. 
Strictness 
For a slice

Boolean array indices are only allowed as the sole index. 
Strictness 

Integer array indices are not allowed at all. 
Strictness 
With the exception of 0D arrays, which are treated like integers. 
Type Strictness#
Functions in numpy.array_api
restrict their inputs to only those dtypes
that are explicitly required by the spec, even when the wrapped corresponding
NumPy function would allow a broader set. Here, we list each function and the
dtypes that are allowed in numpy.array_api
. These are strictness
differences because the spec does not require that other dtypes result in an
error. The categories here are defined as follows:
Floatingpoint:
float32
orfloat64
.Integer: Any signed or unsigned integer dtype (
int8
,int16
,int32
,int64
,uint8
,uint16
,uint32
, oruint64
).Boolean:
bool
.Integer or boolean: Any signed or unsigned integer dtype, or
bool
. For twoargument functions, both arguments must be integer or both must bebool
.Numeric: Any integer or floatingpoint dtype. For twoargument functions, both arguments must be integer or both must be floatingpoint.
All: Any of the above dtype categories. For twoargument functions, both arguments must be the same kind (integer, floatingpoint, or boolean).
In all cases, the return dtype is chosen according to the rules outlined in the spec, and does not differ from NumPy’s return dtype for any of the allowed input dtypes, except in the cases mentioned specifically in the subsections below.
Elementwise Functions#
Function Name 
Dtypes 


Numeric 

Floatingpoint 

Floatingpoint 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Integer or boolean 

Integer or boolean 

Integer 

Integer or boolean 

Integer 

Integer or boolean 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

All 

Floatingpoint 

Floatingpoint 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Boolean 

Boolean 

Boolean 

Boolean 

Numeric 

Numeric 

All 

Numeric 

Numeric 

Numeric 

Numeric 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Numeric 

Numeric 

Floatingpoint 

Floatingpoint 

Numeric 
(*) These functions have different names from the main numpy
namespace.
See Function Name Changes.
Creation Functions#
Function Name 
Dtypes 


Any (all input dtypes must be the same) 
Linear Algebra Functions#
Function Name 
Dtypes 


Floatingpoint 

Numeric 

Floatingpoint 

Any 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Any 

Numeric 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Floatingpoint 

Numeric 

Numeric 

Numeric 

Floatingpoint 
(*) These functions are split from norm
from the main numpy
namespace.
See Function Name Changes.
(**) These functions are new in the array API and are not in the main
numpy
namespace.
Array Object#
All the special __operator__
methods on the array object behave
identically to their corresponding functions (see the spec
for a list of which methods correspond to which functions). The exception is
that operators explicitly allow Python scalars according to the rules
outlined in the spec
(see Type Promotion Differences).
Array Object Differences#
Feature 
Type 
Notes 

No array scalars 
Strictness 
The spec does not have array scalars, only 0D arrays. However, other than the promotion differences outlined in Type Promotion Differences, scalars duck type as 0D arrays for the purposes of the spec. The are immutable, but the spec does not require mutability. 

Strictness 
See numpy/numpy#10404. 

Compatible 

The 
Compatible 
See the spec definition
for 
The 
Breaking 
See the note in the spec. 
New method 
Compatible 
The methods would effectively not do anything since NumPy is CPU only 
Creation Functions Differences#
Feature 
Type 
Notes 


Compatible 

New 
Compatible 

Elementwise Functions Differences#
Feature 
Type 
Notes 

Various functions have been renamed. 
Compatible 

Elementwise functions are only defined for given input type combinations. 
Strictness 
See Type Strictness. 

Strictness 


Breaking 

Linear Algebra Differences#
Feature 
Type 
Notes 


Compatible 


Breaking 


Breaking 
Strictly speaking this can be compatible because 

Compatible 
The corresponding 
New functions 
Compatible 
The 

Breaking 
In the array API, 

Breaking 

New function 
Compatible 
Unlike 

Breaking 
The spec currently only specifies behavior on 1D arrays but future
behavior will likely be to broadcast, rather than flatten, which is
what 

Breaking 
The meaning of 

Breaking 
The 
New function 
Compatible 
Equivalent to 
The 
Compatible 
In 

Breaking 

Manipulation Functions Differences#
Feature 
Type 
Notes 

Various functions have been renamed 
Compatible 


Strictness 
No crosskind casting. No valuebased casting on scalars (when axis=None). 

Strictness 
No crosskind casting. 
New function 
Compatible 
Unlike 

Compatible 
See numpy/numpy#9818. 
Set Functions Differences#
Feature 
Type 
Notes 

New functions 
Compatible 

The four 
Compatible 


Compatible 
See numpy/numpy#20638. 
Set Functions Differences#
Feature 
Type 
Notes 


Breaking 


Compatible 
Statistical Functions Differences#
Feature 
Type 
Notes 


Breaking 

The 
Compatible 
Other Differences#
Feature 
Type 
Notes 

Dtypes can only be spelled as dtype objects. 
Strictness 
For example, 

Strictness 
The exception is Python operators, which accept Python scalars in certain cases (see Type Promotion Differences). 

Strictness 

finfo() return type uses 
Strictness 
The spec allows duck typing, so 
Positional arguments in every function are positionalonly. 
Breaking 
See the spec for the exact signature of each function. Note that NumPy
ufuncs already use positionalonly arguments, but nonufuncs like
