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 adhering to the following conventions.

• Positional parameters must be positional-only parameters. Positional-only parameters have no externally-usable name. When a method accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.

• Optional parameters must be keyword-only arguments.

• Broadcasting semantics must follow the semantics defined in Broadcasting.

• Unless stated otherwise, methods must support the data types defined in Data Types.

• Unless stated otherwise, methods must adhere to the type promotion rules defined in Type Promotion Rules.

• Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.

Furthermore, a conforming implementation of the array API standard must support array objects of arbitrary rank N (i.e., number of dimensions), where N is greater than or equal to zero.

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__()

  • operator.pos(x)

  • operator.__pos__(x)

• -x: array.__neg__()

  • operator.neg(x)

  • operator.__neg__(x)

• x1 + x2: array.__add__()

  • operator.add(x1, x2)

  • operator.__add__(x1, x2)

• x1 - x2: array.__sub__()

  • operator.sub(x1, x2)

  • operator.__sub__(x1, x2)

• x1 * x2: array.__mul__()

  • operator.mul(x1, x2)

  • operator.__mul__(x1, x2)

• x1 / x2: array.__truediv__()

  • operator.truediv(x1,x2)

  • operator.__truediv__(x1, x2)

• x1 // x2: array.__floordiv__()

  • operator.floordiv(x1, x2)

  • operator.__floordiv__(x1, x2)

• x1 % x2: array.__mod__()

  • operator.mod(x1, x2)

  • operator.__mod__(x1, x2)

• x1 ** x2: array.__pow__()

  • operator.pow(x1, x2)

  • operator.__pow__(x1, x2)

Arithmetic operators should be defined for arrays having numeric 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.

• x1 @ x2: array.__matmul__()

  • operator.matmul(x1, x2)

  • operator.__matmul__(x1, x2)

The matmul @ operator should be defined for arrays having numeric 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.

• ~x: array.__invert__()

  • operator.inv(x)

  • operator.invert(x)

  • operator.__inv__(x)

  • operator.__invert__(x)

• x1 & x2: array.__and__()

  • operator.and(x1, x2)

  • operator.__and__(x1, x2)

• x1 | x2: array.__or__()

  • operator.or(x1, x2)

  • operator.__or__(x1, x2)

• x1 ^ x2: array.__xor__()

  • operator.xor(x1, x2)

  • operator.__xor__(x1, x2)

• x1 << x2: array.__lshift__()

  • operator.lshift(x1, x2)

  • operator.__lshift__(x1, x2)

• x1 >> x2: array.__rshift__()

  • operator.rshift(x1, x2)

  • operator.__rshift__(x1, x2)

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__()

  • operator.lt(x1, x2)

  • operator.__lt__(x1, x2)

• x1 <= x2: array.__le__()

  • operator.le(x1, x2)

  • operator.__le__(x1, x2)

• x1 > x2: array.__gt__()

  • operator.gt(x1, x2)

  • operator.__gt__(x1, x2)

• x1 >= x2: array.__ge__()

  • operator.ge(x1, x2)

  • operator.__ge__(x1, x2)

• x1 == x2: array.__eq__()

  • operator.eq(x1, x2)

  • operator.__eq__(x1, x2)

• x1 != x2: array.__ne__()

  • operator.ne(x1, x2)

  • operator.__ne__(x1, x2)

Comparison operators should be defined for arrays having any data type.

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

array.dtype	Data type of the array elements.
array.device	Hardware device the array data resides on.
array.mT	Transpose of a matrix (or a stack of matrices).
array.ndim	Number of array dimensions (axes).
array.shape	Array dimensions.
array.size	Number of elements in an array.
array.T	Transpose of the array.

---

Methods

array.__abs__()	Calculates the absolute value for each element of an array instance (i.e., the element-wise result has the same magnitude as the respective element but has positive sign).
array.__add__(other, /)	Calculates the sum for each element of an array instance with the respective element of the array other.
array.__and__(other, /)	Evaluates self_i & other_i for each element of an array instance with the respective element of the array other.
array.__array_namespace__(*, api_version=None)	Returns an object that has all the array API functions on it.
array.__bool__()	Converts a zero-dimensional boolean array to a Python bool object.
array.__dlpack__(*, stream=None)	Exports the array for consumption by from_dlpack() as a DLPack capsule.
array.__dlpack_device__()	Returns device type and device ID in DLPack format.
array.__eq__(other, /)	Computes the truth value of self_i == other_i for each element of an array instance with the respective element of the array other.
array.__float__()	Converts a zero-dimensional floating-point array to a Python float object.
array.__floordiv__(other, /)	Evaluates self_i // other_i for each element of an array instance with the respective element of the array other.
array.__ge__(other, /)	Computes the truth value of self_i >= other_i for each element of an array instance with the respective element of the array other.
array.__getitem__(key, /)	Returns self[key].
array.__gt__(other, /)	Computes the truth value of self_i > other_i for each element of an array instance with the respective element of the array other.
array.__index__()	Converts a zero-dimensional integer array to a Python int object.
array.__int__()	Converts a zero-dimensional integer array to a Python int object.
array.__invert__()	Evaluates ~self_i for each element of an array instance.
array.__le__(other, /)	Computes the truth value of self_i <= other_i for each element of an array instance with the respective element of the array other.
array.__lshift__(other, /)	Evaluates self_i << other_i for each element of an array instance with the respective element of the array other.
array.__lt__(other, /)	Computes the truth value of self_i < other_i for each element of an array instance with the respective element of the array other.
array.__matmul__(other, /)	Computes the matrix product.
array.__mod__(other, /)	Evaluates self_i % other_i for each element of an array instance with the respective element of the array other.
array.__mul__(other, /)	Calculates the product for each element of an array instance with the respective element of the array other.
array.__ne__(other, /)	Computes the truth value of self_i != other_i for each element of an array instance with the respective element of the array other.
array.__neg__()	Evaluates -self_i for each element of an array instance.
array.__or__(other, /)	Evaluates self_i | other_i for each element of an array instance with the respective element of the array other.
array.__pos__()	Evaluates +self_i for each element of an array instance.
array.__pow__(other, /)	Calculates an implementation-dependent approximation of exponentiation by raising each element (the base) of an array instance to the power of other_i (the exponent), where other_i is the corresponding element of the array other.
array.__rshift__(other, /)	Evaluates self_i >> other_i for each element of an array instance with the respective element of the array other.
array.__setitem__(key, value, /)	Sets self[key] to value.
array.__sub__(other, /)	Calculates the difference for each element of an array instance with the respective element of the array other.
array.__truediv__(other, /)	Evaluates self_i / other_i for each element of an array instance with the respective element of the array other.
array.__xor__(other, /)	Evaluates self_i ^ other_i for each element of an array instance with the respective element of the array other.
array.to_device(device, /, *, stream=None)	Copy the array from the device on which it currently resides to the specified device.