array_object.md

(array-object)=

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 {ref}broadcasting.
• Unless stated otherwise, methods must support the data types defined in {ref}data-types.
• Unless stated otherwise, methods must adhere to the type promotion rules defined in {ref}type-promotion.
• Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.

---

(operators)=

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: __pos__(x)

  • operator.pos(x)
  • operator.__pos__(x)

• -x: __neg__(x)

  • operator.neg(x)
  • operator.__neg__(x)

• x1 + x2: __add__(x1, x2)

  • operator.add(x1, x2)
  • operator.__add__(x1, x2)

• x1 - x2: __sub__(x1, x2)

  • operator.sub(x1, x2)
  • operator.__sub__(x1, x2)

• x1 * x2: __mul__(x1, x2)

  • operator.mul(x1, x2)
  • operator.__mul__(x1, x2)

• x1 / x2: __truediv__(x1, x2)

  • operator.truediv(x1,x2)
  • operator.__truediv__(x1, x2)

• x1 // x2: __floordiv__(x1, x2)

  • operator.floordiv(x1, x2)
  • operator.__floordiv__(x1, x2)

• x1 % x2: __mod__(x1, x2)

  • operator.mod(x1, x2)
  • operator.__mod__(x1, x2)

• x1 ** x2: __pow__(x1, x2)

  • 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: __matmul__(x1, x2)

  • 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: __invert__(x)

  • operator.inv(x)
  • operator.invert(x)
  • operator.__inv__(x)
  • operator.__invert__(x)

• x1 & x2: __and__(x1, x2)

  • operator.and(x1, x2)
  • operator.__and__(x1, x2)

• x1 | x2: __or__(x1, x2)

  • operator.or(x1, x2)
  • operator.__or__(x1, x2)

• x1 ^ x2: __xor__(x1, x2)

  • operator.xor(x1, x2)
  • operator.__xor__(x1, x2)

• x1 << x2: __lshift__(x1, x2)

  • operator.lshift(x1, x2)
  • operator.__lshift__(x1, x2)

• x1 >> x2: __rshift__(x1, x2)

  • 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: __lt__(x1, x2)

  • operator.lt(x1, x2)
  • operator.__lt__(x1, x2)

• x1 <= x2: __le__(x1, x2)

  • operator.le(x1, x2)
  • operator.__le__(x1, x2)

• x1 > x2: __gt__(x1, x2)

  • operator.gt(x1, x2)
  • operator.__gt__(x1, x2)

• x1 >= x2: __ge__(x1, x2)

  • operator.ge(x1, x2)
  • operator.__ge__(x1, x2)

• x1 == x2: __eq__(x1, x2)

  • operator.eq(x1, x2)
  • operator.__eq__(x1, x2)

• x1 != x2: __ne__(x1, x2)

  • 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 {ref}type-promotion or {ref}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.

In-place operators must be supported as discussed in {ref}`copyview-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.

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

(attribute-dtype)=

dtype

Data type of the array elements.

Returns

• out: <dtype>

  • array data type.

(attribute-device)=

device

Hardware device the array data resides on.

Returns

• out: <device>

  • a device object (see {ref}device-support).

(attribute-mT)=

mT

Transpose of a matrix (or a stack of matrices).

If an array instance has fewer than two dimensions, an error should be raised.

Returns

• out: <array>

  • array whose last two dimensions (axes) are permuted in reverse order relative to original array (i.e., for an array instance having shape (..., M, N), the returned array must have shape (..., N, M)). The returned array must have the same data type as the original array.

(attribute-ndim)=

ndim

Number of array dimensions (axes).

Returns

• out: int

  • number of array dimensions (axes).

(attribute-shape)=

shape

Array dimensions.

Returns

• out: Tuple[ Optional[ int ], ... ]

  • array dimensions. An array dimension must be None if and only if a dimension is unknown.

For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; `A[:, B > 0]`) and thus cannot be statically resolved without knowing array contents.

The returned value should be a tuple; however, where warranted, an array library may choose to return a custom shape object. If an array library returns a custom shape object, the object must be immutable, must support indexing for dimension retrieval, and must behave similarly to a tuple.

(attribute-size)=

size

Number of elements in an array.

This must equal the product of the array's dimensions.

Returns

• out: Optional[ int ]

  • number of elements in an array. The returned value must be None if and only if one or more array dimensions are unknown.

For array libraries having graph-based computational models, an array may have unknown dimensions due to data-dependent operations.

(attribute-T)=

T

Transpose of the array.

The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised.

Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional `permute_dims` interface found in this specification.

Returns

• out: <array>

  • two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.

---

Methods

(method-abs)=

__abs__(self, /)

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).

For signed integer data types, the absolute value of the minimum representable integer is implementation-dependent.

Special Cases

For floating-point operands, let self equal x.

• If x_i is NaN, the result is NaN.
• If x_i is -0, the result is +0.
• If x_i is -infinity, the result is +infinity.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise absolute value. The returned array must have the same data type as self.

Element-wise results must equal the results returned by the equivalent element-wise function [`abs(x)`](elementwise_functions.md#absx-).

(method-add)=

__add__(self, other, /)

Calculates the sum for each element of an array instance with the respective element of the array other.

Special Cases

For floating-point operands, let self equal x1 and other equal x2.

• If either x1_i or x2_i is NaN, the result is NaN.
• If x1_i is +infinity and x2_i is -infinity, the result is NaN.
• If x1_i is -infinity and x2_i is +infinity, the result is NaN.
• If x1_i is +infinity and x2_i is +infinity, the result is +infinity.
• If x1_i is -infinity and x2_i is -infinity, the result is -infinity.
• If x1_i is +infinity and x2_i is a finite number, the result is +infinity.
• If x1_i is -infinity and x2_i is a finite number, the result is -infinity.
• If x1_i is a finite number and x2_i is +infinity, the result is +infinity.
• If x1_i is a finite number and x2_i is -infinity, the result is -infinity.
• If x1_i is -0 and x2_i is -0, the result is -0.
• If x1_i is -0 and x2_i is +0, the result is +0.
• If x1_i is +0 and x2_i is -0, the result is +0.
• If x1_i is +0 and x2_i is +0, the result is +0.
• If x1_i is either +0 or -0 and x2_i is a nonzero finite number, the result is x2_i.
• If x1_i is a nonzero finite number and x2_i is either +0 or -0, the result is x1_i.
• If x1_i is a nonzero finite number and x2_i is -x1_i, the result is +0.
• In the remaining cases, when neither infinity, +0, -0, nor a NaN is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an infinity of appropriate mathematical sign.

Floating-point addition is a commutative operation, but not always associative.

Parameters

• self: <array>

  • array instance (augend array). Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • addend array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise sums. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`add(x1, x2)`](elementwise_functions.md#addx1-x2-).

(method-and)=

__and__(self, other, /)

Evaluates self_i & other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have an integer or boolean data type.

• other: Union[ int, bool, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have an integer or boolean data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x1, x2)`](elementwise_functions.md#logical_andx1-x2-).

(method-array_namespace)=

__array_namespace__(self, /, *, api_version=None)

Returns an object that has all the array API functions on it.

Parameters

• self: <array>

  • array instance.

• api_version: <Optional[str]>

  • string representing the version of the array API specification to be returned, in 'YYYY.MM' form, for example, '2020.10'. If it is None, it should return the namespace corresponding to latest version of the array API specification. If the given version is invalid or not implemented for the given module, an error should be raised. Default: None.

Returns

• out: <object>

  • an object representing the array API namespace. It should have every top-level function defined in the specification as an attribute. It may contain other public names as well, but it is recommended to only include those names that are part of the specification.

(method-bool)=

__bool__(self, /)

Converts a zero-dimensional boolean array to a Python bool object.

Parameters

• self: <array>

  • zero-dimensional array instance. Must have a boolean data type.

Returns

• out: <bool>

  • a Python bool object representing the single element of the array.

(method-dlpack)=

__dlpack__(self, /, *, stream=None)

Exports the array for consumption by {ref}function-from_dlpack as a DLPack capsule.

Parameters

• self: <array>

  • array instance.

• stream: Optional[ Union[ int, Any ]]

  • for CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. stream is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array (e.g., by inserting a dependency between streams via "wait for event"). The pointer must be a positive integer or -1. If stream is -1, the value may be used by the consumer to signal "producer must not perform any synchronization". The ownership of the stream stays with the consumer.

    On CPU and other device types without streams, only None is accepted.

    For other device types which do have a stream, queue or similar synchronization mechanism, the most appropriate type to use for stream is not yet determined. E.g., for SYCL one may want to use an object containing an in-order cl::sycl::queue. This is allowed when libraries agree on such a convention, and may be standardized in a future version of this API standard.

    Support for a `stream` value other than `None` is optional and implementation-dependent.
    

    Device-specific notes:

    :::{admonition} CUDA

    • None: producer must assume the legacy default stream (default).
    • 1: the legacy default stream.
    • 2: the per-thread default stream.
    • > 2: stream number represented as a Python integer.

    0 is disallowed due to its ambiguity: 0 could mean either None, 1, or 2. :::

    :::{admonition} ROCm

    • None: producer must assume the legacy default stream (default).
    • 0: the default stream.
    • > 2: stream number represented as a Python integer.

    Using 1 and 2 is not supported. :::

    It is recommended that implementers explicitly handle streams. If
    they use the legacy default stream, specifying `1` (CUDA) or `0`
    (ROCm) is preferred. `None` is a safe default for developers who do
    not want to think about stream handling at all, potentially at the
    cost of more synchronization than necessary.
    

Returns

• capsule: <PyCapsule>

  • a DLPack capsule for the array. See {ref}data-interchange for details.

(method-dlpack_device)=

__dlpack_device__(self, /)

Returns device type and device ID in DLPack format. Meant for use within {ref}function-from_dlpack.

Parameters

• self: <array>

  • array instance.

Returns

• device: Tuple[enum.IntEnum, int]

  • a tuple (device_type, device_id) in DLPack format. Valid device type enum members are:

    CPU = 1
    CUDA = 2
    CPU_PINNED = 3
    OPENCL = 4
    VULKAN = 7
    METAL = 8
    VPI = 9
    ROCM = 10
    

(method-eq)=

__eq__(self, 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.

Parameters

• self: <array>

  • array instance. May have any data type.

• other: Union[ int, float, bool, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). May have any data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool.

Element-wise results must equal the results returned by the equivalent element-wise function [`equal(x1, x2)`](elementwise_functions.md#equalx1-x2-).

(method-float)=

__float__(self, /)

Converts a zero-dimensional floating-point array to a Python float object.

Parameters

• self: <array>

  • zero-dimensional array instance. Must have a floating-point data type.

Returns

• out: <float>

  • a Python float object representing the single element of the array instance.

(method-floordiv)=

__floordiv__(self, other, /)

Evaluates self_i // other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x1, x2)`](elementwise_functions.md#floor_dividex1-x2-).

(method-ge)=

__ge__(self, 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.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool.

Element-wise results must equal the results returned by the equivalent element-wise function [`greater_equal(x1, x2)`](elementwise_functions.md#greater_equalx1-x2-).

(method-getitem)=

__getitem__(self, key, /)

Returns self[key].

Parameters

• self: <array>

  • array instance.

• key: Union[ int, slice, ellipsis, Tuple[ Union[ int, slice, ellipsis ], ... ], <array> ]

  • index key.

Returns

• out: <array>

  • an array containing the accessed value(s). The returned array must have the same data type as self.

(method-gt)=

__gt__(self, 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.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool.

Element-wise results must equal the results returned by the equivalent element-wise function [`greater(x1, x2)`](elementwise_functions.md#greaterx1-x2-).

(method-index)=

__index__(self, /)

Converts a zero-dimensional integer array to a Python int object.

This method is called to implement [`operator.index()`](https://docs.python.org/3/reference/datamodel.html#object.__index__). See also [PEP 357](https://www.python.org/dev/peps/pep-0357/).

Parameters

• self: <array>

  • zero-dimensional array instance. Must have an integer data type.

Returns

• out: <int>

  • a Python int object representing the single element of the array instance.

(method-int)=

__int__(self, /)

Converts a zero-dimensional integer array to a Python int object.

Parameters

• self: <array>

  • zero-dimensional array instance. Must have an integer data type.

Returns

• out: <int>

  • a Python int object representing the single element of the array instance.

(method-invert)=

__invert__(self, /)

Evaluates ~self_i for each element of an array instance.

Parameters

• self: <array>

  • array instance. Should have an integer or boolean data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have the same data type as self.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_invert(x)`](elementwise_functions.md#bitwise_invertx-).

(method-le)=

__le__(self, 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.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool.

Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#less_equalx1-x2-).

(method-lshift)=

__lshift__(self, other, /)

Evaluates self_i << other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have an integer data type.

• other: Union[ int, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have an integer data type. Each element must be greater than or equal to 0.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have the same data type as self.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_left_shift(x1, x2)`](elementwise_functions.md#bitwise_left_shiftx1-x2-).

(method-lt)=

__lt__(self, 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.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool.

Element-wise results must equal the results returned by the equivalent element-wise function [`less(x1, x2)`](elementwise_functions.md#lessx1-x2-).

(method-matmul)=

__matmul__(self, other, /)

Computes the matrix product.

The `matmul` function must implement the same semantics as the built-in `@` operator (see [PEP 465](https://www.python.org/dev/peps/pep-0465)).

Parameters

• self: <array>

  • array instance. Should have a numeric data type. Must have at least one dimension. If self is one-dimensional having shape (M) and other has more than one dimension, self must be promoted to a two-dimensional array by prepending 1 to its dimensions (i.e., must have shape (1, M)). After matrix multiplication, the prepended dimensions in the returned array must be removed. If self has more than one dimension (including after vector-to-matrix promotion), self must be compatible with other (see {ref}broadcasting). If self has shape (..., M, K), the innermost two dimensions form matrices on which to perform matrix multiplication.

• other: <array>

  • other array. Should have a numeric data type. Must have at least one dimension. If other is one-dimensional having shape (N) and self has more than one dimension, other must be promoted to a two-dimensional array by appending 1 to its dimensions (i.e., must have shape (N, 1)). After matrix multiplication, the appended dimensions in the returned array must be removed. If other has more than one dimension (including after vector-to-matrix promotion), other must be compatible with self (see {ref}broadcasting). If other has shape (..., K, N), the innermost two dimensions form matrices on which to perform matrix multiplication.

Returns

• out: <array>

  • if both self and other are one-dimensional arrays having shape (N), a zero-dimensional array containing the inner product as its only element.
  • if self is a two-dimensional array having shape (M, K) and other is a two-dimensional array having shape (K, N), a two-dimensional array containing the conventional matrix product and having shape (M, N).
  • if self is a one-dimensional array having shape (K) and other is an array having shape (..., K, N), an array having shape (..., N) (i.e., prepended dimensions during vector-to-matrix promotion must be removed) and containing the conventional matrix product.
  • if self is an array having shape (..., M, K) and other is a one-dimensional array having shape (K), an array having shape (..., M) (i.e., appended dimensions during vector-to-matrix promotion must be removed) and containing the conventional matrix product.
  • if self is a two-dimensional array having shape (M, K) and other is an array having shape (..., K, N), an array having shape (..., M, N) and containing the conventional matrix product for each stacked matrix.
  • if self is an array having shape (..., M, K) and other is a two-dimensional array having shape (K, N), an array having shape (..., M, N) and containing the conventional matrix product for each stacked matrix.
  • if either self or other has more than two dimensions, an array having a shape determined by {ref}broadcasting self against other and containing the conventional matrix product for each stacked matrix.

  The returned array must have a data type determined by {ref}type-promotion.

  Results must equal the results returned by the equivalent function [`matmul(x1, x2)`](linear_algebra_functions.md#matmulx1-x2-).
  

Raises

• if either self or other is a zero-dimensional array.
• if self is a one-dimensional array having shape (N), other is a one-dimensional array having shape (M), and N != M.
• if self is an array having shape (..., M, K), other is an array having shape (..., L, N), and K != L.

(method-mod)=

__mod__(self, other, /)

Evaluates self_i % other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. Each element-wise result must have the same sign as the respective element other_i. The returned array must have a floating-point data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x1, x2)`](elementwise_functions.md#remainderx1-x2-).

(method-mul)=

__mul__(self, other, /)

Calculates the product for each element of an array instance with the respective element of the array other.

Special Cases

For floating-point operands, let self equal x1 and other equal x2.

• If either x1_i or x2_i is NaN, the result is NaN.
• If x1_i is either +infinity or -infinity and x2_i is either +0 or -0, the result is NaN.
• If x1_i is either +0 or -0 and x2_i is either +infinity or -infinity, the result is NaN.
• If x1_i and x2_i have the same mathematical sign, the result has a positive mathematical sign, unless the result is NaN. If the result is NaN, the "sign" of NaN is implementation-defined.
• If x1_i and x2_i have different mathematical signs, the result has a negative mathematical sign, unless the result is NaN. If the result is NaN, the "sign" of NaN is implementation-defined.
• If x1_i is either +infinity or -infinity and x2_i is either +infinity or -infinity, the result is a signed infinity with the mathematical sign determined by the rule already stated above.
• If x1_i is either +infinity or -infinity and x2_i is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above.
• If x1_i is a nonzero finite number and x2_i is either +infinity or -infinity, the result is a signed infinity with the mathematical sign determined by the rule already stated above.
• In the remaining cases, where neither infinity nor NaN is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an infinity of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.

Floating-point multiplication is not always associative due to finite precision.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise products. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x1, x2)`](elementwise_functions.md#multiplyx1-x2-).

(method-ne)=

__ne__(self, 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.

Parameters

• self: <array>

  • array instance. May have any data type.

• other: Union[ int, float, bool, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). May have any data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type of bool (i.e., must be a boolean array).

Element-wise results must equal the results returned by the equivalent element-wise function [`not_equal(x1, x2)`](elementwise_functions.md#not_equalx1-x2-).

(method-neg)=

__neg__(self, /)

Evaluates -self_i for each element of an array instance.

For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

Returns

• out: <array>

  • an array containing the evaluated result for each element in self. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`negative(x)`](elementwise_functions.md#negativex-).

(method-or)=

__or__(self, other, /)

Evaluates self_i | other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have an integer or boolean data type.

• other: Union[ int, bool, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have an integer or boolean data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_or(x1, x2)`](elementwise_functions.md#bitwise_orx1-x2-).

(method-pos)=

__pos__(self, /)

Evaluates +self_i for each element of an array instance.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

Returns

• out: <array>

  • an array containing the evaluated result for each element. The returned array must have the same data type as self.

Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x)`](elementwise_functions.md#positivex-).

(method-pow)=

__pow__(self, 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.

Special Cases

For floating-point operands, let self equal x1 and other equal x2.

• If x1_i is not equal to 1 and x2_i is NaN, the result is NaN.
• If x2_i is +0, the result is 1, even if x1_i is NaN.
• If x2_i is -0, the result is 1, even if x1_i is NaN.
• If x1_i is NaN and x2_i is not equal to 0, the result is NaN.
• If abs(x1_i) is greater than 1 and x2_i is +infinity, the result is +infinity.
• If abs(x1_i) is greater than 1 and x2_i is -infinity, the result is +0.
• If abs(x1_i) is 1 and x2_i is +infinity, the result is 1.
• If abs(x1_i) is 1 and x2_i is -infinity, the result is 1.
• If x1_i is 1 and x2_i is not NaN, the result is 1.
• If abs(x1_i) is less than 1 and x2_i is +infinity, the result is +0.
• If abs(x1_i) is less than 1 and x2_i is -infinity, the result is +infinity.
• If x1_i is +infinity and x2_i is greater than 0, the result is +infinity.
• If x1_i is +infinity and x2_i is less than 0, the result is +0.
• If x1_i is -infinity and x2_i is greater than 0, the result is -infinity.
• If x1_i is -infinity, x2_i is greater than 0, and x2_i is not an odd integer value, the result is +infinity.
• If x1_i is -infinity, x2_i is less than 0, and x2_i is an odd integer value, the result is -0.
• If x1_i is -infinity, x2_i is less than 0, and x2_i is not an odd integer value, the result is +0.
• If x1_i is +0 and x2_i is greater than 0, the result is +0.
• If x1_i is +0 and x2_i is less than 0, the result is +infinity.
• If x1_i is -0, x2_i is greater than 0, and x2_i is an odd integer value, the result is -0.
• If x1_i is -0, x2_i is greater than 0, and x2_i is not an odd integer value, the result is +0.
• If x1_i is -0, x2_i is less than 0, and x2_i is an odd integer value, the result is -infinity.
• If x1_i is -0, x2_i is less than 0, and x2_i is not an odd integer value, the result is +infinity.
• If x1_i is less than 0, x1_i is a finite number, x2_i is a finite number, and x2_i is not an integer value, the result is NaN.

Parameters

• self: <array>

  • array instance whose elements correspond to the exponentiation base. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array whose elements correspond to the exponentiation exponent. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x1, x2)`](elementwise_functions.md#powx1-x2-).

(method-rshift)=

__rshift__(self, other, /)

Evaluates self_i >> other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have an integer data type.

• other: Union[ int, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have an integer data type. Each element must be greater than or equal to 0.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have the same data type as self.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x1, x2)`](elementwise_functions.md#bitwise_right_shiftx1-x2-).

(method-setitem)=

__setitem__(self, key, value, /)

Sets self[key] to value.

Parameters

• self: <array>

  • array instance.

• key: Union[ int, slice, ellipsis, Tuple[ Union[ int, slice, ellipsis ], ... ], <array> ]

  • index key.

• value: Union[ int, float, bool, <array> ]

  • value(s) to set. Must be compatible with self[key] (see {ref}broadcasting).

Setting array values must not affect the data type of `self`.

When `value` is a Python scalar (i.e., `int`, `float`, `bool`), behavior must follow specification guidance on mixing arrays with Python scalars (see {ref}`type-promotion`).

When `value` is an `array` of a different data type than `self`, how values are cast to the data type of `self` is implementation defined.

(method-sub)=

__sub__(self, other, /)

Calculates the difference for each element of an array instance with the respective element of the array other. The result of self_i - other_i must be the same as self_i + (-other_i) and must be governed by the same floating-point rules as addition (see __add__()).

Parameters

• self: <array>

  • array instance (minuend array). Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • subtrahend array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise differences. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x1, x2)`](elementwise_functions.md#subtractx1-x2-).

(method-truediv)=

__truediv__(self, other, /)

Evaluates self_i / other_i for each element of an array instance with the respective element of the array other.

Special Cases

For floating-point operands, let self equal x1 and other equal x2.

• If either x1_i or x2_i is NaN, the result is NaN.
• If x1_i is either +infinity or -infinity and x2_i is either +infinity or -infinity, the result is NaN.
• If x1_i is either +0 or -0 and x2_i is either +0 or -0, the result is NaN.
• If x1_i is +0 and x2_i is greater than 0, the result is +0.
• If x1_i is -0 and x2_i is greater than 0, the result -0.
• If x1_i is +0 and x2_i is less than 0, the result is -0.
• If x1_i is -0 and x2_i is less than 0, the result is +0.
• If x1_i is greater than 0 and x2_i is +0, the result is +infinity.
• If x1_i is greater than 0 and x2_i is -0, the result is -infinity.
• If x1_i is less than 0 and x2_i is +0, the result is -infinity.
• If x1_i is less than 0 and x2_i is -0, the result is +infinity.
• If x1_i is +infinity and x2_i is a positive (i.e., greater than 0) finite number, the result is +infinity.
• If x1_i is +infinity and x2_i is a negative (i.e., less than 0) finite number, the result is -infinity.
• If x1_i is -infinity and x2_i is a positive (i.e., greater than 0) finite number, the result is -infinity.
• If x1_i is -infinity and x2_i is a negative (i.e., less than 0) finite number, the result is +infinity.
• If x1_i is a positive (i.e., greater than 0) finite number and x2_i is +infinity, the result is +0.
• If x1_i is a positive (i.e., greater than 0) finite number and x2_i is -infinity, the result is -0.
• If x1_i is a negative (i.e., less than 0) finite number and x2_i is +infinity, the result is -0.
• If x1_i is a negative (i.e., less than 0) finite number and x2_i is -infinity, the result is +0.
• If x1_i and x2_i have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign.
• If x1_i and x2_i have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign.
• In the remaining cases, where neither -infinity, +0, -0, nor NaN is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an infinity of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign.

Parameters

• self: <array>

  • array instance. Should have a numeric data type.

• other: Union[ int, float, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have a numeric data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x1, x2)`](elementwise_functions.md#dividex1-x2-).

(method-xor)=

__xor__(self, other, /)

Evaluates self_i ^ other_i for each element of an array instance with the respective element of the array other.

Parameters

• self: <array>

  • array instance. Should have an integer or boolean data type.

• other: Union[ int, bool, <array> ]

  • other array. Must be compatible with self (see {ref}broadcasting). Should have an integer or boolean data type.

Returns

• out: <array>

  • an array containing the element-wise results. The returned array must have a data type determined by {ref}type-promotion.

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x1, x2)`](elementwise_functions.md#bitwise_xorx1-x2-).

(method-to_device)=

to_device(self, device, /, *, stream=None)

Copy the array from the device on which it currently resides to the specified device.

Parameters

• self: <array>

  • array instance.

• device: <device>

  • a device object (see {ref}device-support).

• stream: Optional[ Union[ int, Any ]]

  • stream object to use during copy. In addition to the types supported in {ref}method-__dlpack__, implementations may choose to support any library-specific stream object with the caveat that any code using such an object would not be portable.

Returns

• out: <array>

  • an array with the same data and data type as self and located on the specified device.

If `stream` is given, the copy operation should be enqueued on the provided `stream`; otherwise, the copy operation should be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this must be clearly explained in a conforming library's documentation.