Array object¶
Array API specification for array object attributes and methods.
A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods.
Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) 0
, 1
, 2
, 3
, and 4
and must explicitly document their maximum supported rank N
.
Note
Conforming implementations must support zero-dimensional arrays.
Apart from array object attributes, such as ndim
, device
, and dtype
, all operations in this standard return arrays (or tuples of arrays), including those operations, such as mean
, var
, and std
, from which some common array libraries (e.g., NumPy) return scalar values.
Rationale: always returning arrays is necessary to (1) support accelerator libraries where non-array return values could force device synchronization and (2) support delayed execution models where an array represents a future value.
Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators.
Arithmetic Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following Python arithmetic operators.
+x
:array.__pos__()
-x
:array.__neg__()
x1 + x2
:array.__add__()
x1 - x2
:array.__sub__()
x1 * x2
:array.__mul__()
x1 / x2
:array.__truediv__()
x1 // x2
:array.__floordiv__()
x1 % x2
:array.__mod__()
x1 ** x2
:array.__pow__()
Arithmetic operators should be defined for arrays having real-valued data types.
Array Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following Python array operators.
The matmul @
operator should be defined for arrays having real-valued data types.
Bitwise Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following Python bitwise operators.
x1 & x2
:array.__and__()
x1 | x2
:array.__or__()
x1 ^ x2
:array.__xor__()
x1 << x2
:array.__lshift__()
x1 >> x2
:array.__rshift__()
Bitwise operators should be defined for arrays having integer and boolean data types.
Comparison Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following Python comparison operators.
x1 < x2
:array.__lt__()
x1 <= x2
:array.__le__()
x1 > x2
:array.__gt__()
x1 >= x2
:array.__ge__()
x1 == x2
:array.__eq__()
x1 != x2
:array.__ne__()
array.__lt__()
, array.__le__()
, array.__gt__()
, array.__ge__()
are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type.
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see Complex Number Ordering).
In-place Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following in-place Python operators.
An in-place operation must not change the data type or shape of the in-place array as a result of Type Promotion Rules or Broadcasting.
An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition x1 += x2
, the modified array x1
must always equal the result of the equivalent binary arithmetic operation x1 = x1 + x2
.
Note
In-place operators must be supported as discussed in Copy-view behaviour and mutability.
Arithmetic Operators¶
+=
. May be implemented via__iadd__
.-=
. May be implemented via__isub__
.*=
. May be implemented via__imul__
./=
. May be implemented via__itruediv__
.//=
. May be implemented via__ifloordiv__
.**=
. May be implemented via__ipow__
.%=
. May be implemented via__imod__
.
Array Operators¶
@=
. May be implemented via__imatmul__
.
Bitwise Operators¶
&=
. May be implemented via__iand__
.|=
. May be implemented via__ior__
.^=
. May be implemented via__ixor__
.<<=
. May be implemented via__ilshift__
.>>=
. May be implemented via__irshift__
.
Reflected Operators¶
A conforming implementation of the array API standard must provide and support an array object supporting the following reflected operators.
The results of applying reflected operators must match their non-reflected equivalents.
Note
All operators for which array <op> scalar
is implemented must have an equivalent reflected operator implementation.
Arithmetic Operators¶
__radd__
__rsub__
__rmul__
__rtruediv__
__rfloordiv__
__rpow__
__rmod__
Array Operators¶
__rmatmul__
Bitwise Operators¶
__rand__
__ror__
__rxor__
__rlshift__
__rrshift__
Attributes¶
Data type of the array elements. |
|
Hardware device the array data resides on. |
|
Transpose of a matrix (or a stack of matrices). |
|
Number of array dimensions (axes). |
|
Array dimensions. |
|
Number of elements in an array. |
|
Transpose of the array. |
Methods¶
Calculates the absolute value for each element of an array instance. |
|
|
Calculates the sum for each element of an array instance with the respective element of the array |
|
Evaluates |
|
Returns an object that has all the array API functions on it. |
Converts a zero-dimensional array to a Python |
|
Converts a zero-dimensional array to a Python |
|
|
Exports the array for consumption by |
Returns device type and device ID in DLPack format. |
|
|
Computes the truth value of |
Converts a zero-dimensional array to a Python |
|
|
Evaluates |
|
Computes the truth value of |
|
Returns |
|
Computes the truth value of |
Converts a zero-dimensional integer array to a Python |
|
Converts a zero-dimensional array to a Python |
|
Evaluates |
|
|
Computes the truth value of |
|
Evaluates |
|
Computes the truth value of |
|
Computes the matrix product. |
|
Evaluates |
|
Calculates the product for each element of an array instance with the respective element of the array |
|
Computes the truth value of |
Evaluates |
|
|
Evaluates |
Evaluates |
|
|
Calculates an implementation-dependent approximation of exponentiation by raising each element (the base) of an array instance to the power of |
|
Evaluates |
|
Sets |
|
Calculates the difference for each element of an array instance with the respective element of the array |
|
Evaluates |
|
Evaluates |
|
Copy the array from the device on which it currently resides to the specified |