diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index f555eeb76..ee8b21833 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -1,3 +1,884 @@ .. 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](https://www.python.org/dev/peps/pep-0570/) 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](https://www.python.org/dev/peps/pep-3102/) 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 + +A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators: + +- `x1 < x2`: [`__lt__(x1, x2)`](#__lt__) + + - [`operator.lt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lt) + - [`operator.__lt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lt__) + +- `x1 <= x2`: [`__le__(x1, x2)`](#__le__) + + - [`operator.le(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.le) + - [`operator.__le__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__le__) + +- `x1 > x2`: [`__gt__(x1, x2)`](#__gt__) + + - [`operator.gt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.gt) + - [`operator.__gt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__gt__) + +- `x1 >= x2`: [`__ge__(x1, x2)`](#__ge__) + + - [`operator.ge(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ge) + - [`operator.__ge__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ge__) + +- `x1 == x2`: [`__eq__(x1, x2)`](#__eq__) + + - [`operator.eq(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.eq) + - [`operator.__eq__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__eq__) + +- `x1 != x2`: [`__ne__(x1, x2)`](#__ne__) + + - [`operator.ne(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ne) + - [`operator.__ne__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ne__) + +- `+x`: [`__pos__(x)`](#__pos__) + + - [`operator.pos(x)`](https://docs.python.org/3/library/operator.html#operator.pos) + - [`operator.__pos__(x)`](https://docs.python.org/3/library/operator.html#operator.__pos__) + +- `-x`: [`__neg__(x)`](#__neg__) + + - [`operator.neg(x)`](https://docs.python.org/3/library/operator.html#operator.neg) + - [`operator.__neg__(x)`](https://docs.python.org/3/library/operator.html#operator.__neg__) + +- `x1 + x2`: [`__add__(x1, x2)`](#__add__) + + - [`operator.add(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.add) + - [`operator.__add__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__add__) + +- `x1 - x2`: [`__sub__(x1, x2)`](#__sub__) + + - [`operator.sub(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.sub) + - [`operator.__sub__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__sub__) + +- `x1 * x2`: [`__mul__(x1, x2)`](#__mul__) + + - [`operator.mul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mul) + - [`operator.__mul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mul__) + +- `x1 / x2`: [`__truediv__(x1, x2)`](#__truediv__) + + - [`operator.truediv(x1,x2)`](https://docs.python.org/3/library/operator.html#operator.truediv) + - [`operator.__truediv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__truediv__) + +- `x1 // x2`: [`__floordiv__(x1, x2)`](#__floordiv__) + + - [`operator.floordiv(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.floordiv) + - [`operator.__floordiv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__floordiv__) + +- `x1 % x2`: [`__mod__(x1, x2)`](#__mod__) + + - [`operator.mod(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mod) + - [`operator.__mod__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mod__) + +- `x1 ** x2`: [`__pow__(x1, x2)`](#__pow__) + + - [`operator.pow(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.pow) + - [`operator.__pow__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__pow__) + +- `x1 @ x2`: [`__matmul__(x1, x2)`](#__matmul__) + + - [`operator.matmul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.matmul) + - [`operator.__matmul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__matmul__) + +- `~x`: [`__invert__(x)`](#__invert__) + + - [`operator.inv(x)`](https://docs.python.org/3/library/operator.html#operator.inv) + - [`operator.invert(x)`](https://docs.python.org/3/library/operator.html#operator.invert) + - [`operator.__inv__(x)`](https://docs.python.org/3/library/operator.html#operator.__inv__) + - [`operator.__invert__(x)`](https://docs.python.org/3/library/operator.html#operator.__invert__) + +- `x1 & x2`: [`__and__(x1, x2)`](#__and__) + + - [`operator.and(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.and) + - [`operator.__and__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__and__) + +- `x1 | x2`: [`__or__(x1, x2)`](#__or__) + + - [`operator.or(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.or) + - [`operator.__or__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__or__) + +- `x1 ^ x2`: [`__xor__(x1, x2)`](#__xor__) + + - [`operator.xor(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.xor) + - [`operator.__xor__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__xor__) + +- `x1 << x2`: [`__lshift__(x1, x2)`](#__lshift__) + + - [`operator.lshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lshift) + - [`operator.__lshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lshift__) + +- `x1 >> x2`: [`__rshift__(x1, x2)`](#__rshift__) + + - [`operator.rshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.rshift) + - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) + + +### In-place operators + +As discussed in :ref:`copyview-mutability`, in-place operators need to be +supported. The following operators must be supported: + +- `+=`. May be (but does not have to be) implemented via `__iadd__`. +- `-=`. May be (but does not have to be) implemented via `__isub__`. +- `*=`. May be (but does not have to be) implemented via `__imul__`. +- `/=`. May be (but does not have to be) implemented via `__idiv__`. +- `//=`. May be (but does not have to be) implemented via `__ifloordiv__`. +- `**=`. May be (but does not have to be) implemented via `__ipow__`. +- `@=`. May be (but does not have to be) implemented via `__imatmul__`. +- `%=`. May be (but does not have to be) implemented via `__imod__`. +- `&=`. May be (but does not have to be) implemented via `__iand__`. +- `|=`. May be (but does not have to be) implemented via `__ior__`. +- `^=`. May be (but does not have to be) implemented via `__ixor__`. +- `<<=`. May be (but does not have to be) implemented via `__ilshift__`. +- `>>=`. May be (but does not have to be) implemented via `__irshift__`. + + +### Right-hand side dunder methods + +All supported operators for which `array scalar` is implemented also need a right-hand +size dunder method. The following methods must be supported: + +- `__radd__` +- `__rsub__` +- `__rmul__` +- `__rdiv__` +- `__rfloordiv__` +- `__rtruediv__` +- `__rpow__` +- `__rmod__` +- `__rand__` +- `__ror__` +- `__rxor__` +- `__rlshift__` +- `__rrshift__` + +For the expected numerical behaviour, see their left-hand equivalents. + +* * * + +## Attributes + + + +### # dtype + +Data type of the array elements. + +#### Returns + +- **out**: _<dtype>_ + + - array data type. + +### # ndim + +Number of array dimensions (axes). + +#### Returns + +- **out**: _int_ + + - number of array dimensions (axes). + +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of dimensions may be dynamic._ + +### # shape + +Array dimensions. + +#### Returns + +- **out**: _Union\[ Tuple\[ int, ...], <shape> ]_ + + - array dimensions as either a tuple or a custom shape object. If a shape object, the object must be immutable and must support indexing for dimension retrieval. + +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ + +### # size + +Number of elements in an array. This should equal the product of the array's dimensions. + +#### Returns + +- **out**: _int_ + + - number of elements in an array. + +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of elements may be dynamic._ + +### # T + +Transpose of the array. + +#### Returns + +- **out**: _<array>_ + + - array whose 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 + + + +### # \_\_abs\_\_(x, /) + +Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). + +#### Special Cases + +- 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 + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise absolute value. The returned array must have the same data type as `x`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`abs(x)`](elementwise_functions.md#abs). + +### # \_\_add\_\_(x1, x2, /) + +Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +#### Special Cases + +- 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. + +.. note:: + + Floating-point addition is a commutative operation, but not always associative. + +#### Parameters + +- **x1**: _<array>_ + + - array instance (augend array). + +- **x2**: _<array>_ + + - addend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`add(x1, x2)`](elementwise_functions.md#add). + +### # \_\_and\_\_(x1, x2, /) + +Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. Must have an integer or boolean data type. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must 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`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x1, x2)`](elementwise_functions.md#and). + +### # \_\_eq\_\_(x1, x2, /) + +Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`equal(x1, x2)`](elementwise_functions.md#equal). + +### # \_\_floordiv\_\_(x1, x2, /) + +Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x1, x2)`](elementwise_functions.md#floor_divide). + +### # \_\_ge\_\_(x1, x2, /) + +Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`greater_equal(x1, x2)`](elementwise_functions.md#greater_equal). + +### # \_\_getitem\_\_(x, key, /) + +_TODO: dependent on the indexing specification._ + +### # \_\_gt\_\_(x1, x2, /) + +Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`greater(x1, x2)`](elementwise_functions.md#greater). + +### # \_\_invert\_\_(x, /) + +Evaluates `~x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. Must 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 `x`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_invert(x)`](elementwise_functions.md#bitwise_invert). + +### # \_\_le\_\_(x1, x2, /) + +Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#less_equal). + +### # \_\_len\_\_(x, /) + +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ + +### # \_\_lshift\_\_(x1, x2, /) + +Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. Must have an integer data type. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must 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 `x1`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#bitwise_left_shift). + +### # \_\_lt\_\_(x1, x2, /) + +Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`less(x1, x2)`](elementwise_functions.md#less). + +### # \_\_matmul\_\_(x1, x2, /) + +_TODO: awaiting `matmul` functional equivalent._ + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - _TODO_ + +### # \_\_mod\_\_(x1, x2, /) + +Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x1, x2)`](elementwise_functions.md#remainder). + +### # \_\_mul\_\_(x1, x2, /) + +Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +#### Special Cases + +- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. +- 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` 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. + +.. note:: + + Floating-point multiplication is not always associative due to finite precision. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x1, x2)`](elementwise_functions.md#multiply). + +### # \_\_ne\_\_(x1, x2, /) + +Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### 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). + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`not_equal(x1, x2)`](elementwise_functions.md#not_equal). + +### # \_\_neg\_\_(x, /) + +Evaluates `-x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`negative(x)`](elementwise_functions.md#negative). + +### # \_\_or\_\_(x1, x2, /) + +Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. Must have an integer or boolean data type. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must 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`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x1, x2)`](elementwise_functions.md#bitwise_or). + +### # \_\_pos\_\_(x, /) + +Evaluates `+x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the evaluated result for each element in `x`. The returned array must have the same data type as `x`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x)`](elementwise_functions.md#positive). + +### # \_\_pow\_\_(x1, x2, /) + +Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. + +#### Special Cases + +- 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 + +- **x1**: _<array>_ + + - array instance whose elements correspond to the exponentiation base. + +- **x2**: _<array>_ + + - other array whose elements correspond to the exponentiation exponent. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x1, x2)`](elementwise_functions.md#pow). + +### # \_\_rshift\_\_(x1, x2, /) + +Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. Must have an integer data type. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must 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 `x1`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x1, x2)`](elementwise_functions.md#bitwise_right_shift). + +### # \_\_setitem\_\_(x, key, value, /) + +_TODO: dependent on the indexing specification._ + +### # \_\_sub\_\_(x1, x2, /) + +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__()`](#__add__)). + +#### Parameters + +- **x1**: _<array>_ + + - array instance (minuend array). + +- **x2**: _<array>_ + + - subtrahend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x1, x2)`](elementwise_functions.md#subtract). + +### # \_\_truediv\_\_(x1, x2, /) + +Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +#### Special Cases + +- 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 + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x1, x2)`](elementwise_functions.md#divide). + +### # \_\_xor\_\_(x1, x2, /) + +Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. Must have an integer or boolean data type. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must 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`. + +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x1, x2)`](elementwise_functions.md#bitwise_xor). \ No newline at end of file diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index cd27d0b0f..348f974b4 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -1,3 +1,5 @@ +.. _element-wise-functions: + # Element-wise Functions > Array API specification for element-wise functions. @@ -18,7 +20,7 @@ A conforming implementation of the array API standard must provide and support t Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. @@ -40,7 +42,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1, +1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. @@ -57,13 +59,13 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # acosh(x, /) Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `1`, the result is `NaN`. @@ -80,23 +82,23 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c - **out**: _<array>_ - - an array containing the inverse hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # add(x1, x2, /) Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - 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 finite, the result is `+infinity`. -- If `x1_i` is `-infinity` and `x2_i` is finite, the result is `-infinity`. -- If `x1_i` is finite and `x2_i` is `+infinity`, the result is `+infinity`. -- If `x1_i` is finite 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`. @@ -104,7 +106,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - 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 an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same 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 sign. +- 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. .. note:: @@ -124,13 +126,13 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - **out**: _<array>_ - - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. ### # asin(x, /) Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. @@ -148,13 +150,13 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # asinh(x, /) Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -172,19 +174,19 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s - **out**: _<array>_ - - an array containing the inverse hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atan(x, /) Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. -- If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded). -- If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded). +- If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2`. +- If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2`. #### Parameters @@ -196,13 +198,13 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atan2(x1, x2, /) Calculates an implementation-dependent approximation of the inverse tangent of the quotient `x1/x2`, having domain `[-infinity, +infinity] x [-infinity, +infinity]` (where the `x` notation denotes the set of ordered pairs of elements `(x1_i, x2_i)`) and codomain `[-π, +π]`, for each pair of elements `(x1_i, x2_i)` of the input arrays `x1` and `x2`, respectively. Each element-wise result is expressed in radians. -The signs of `x1_i` and `x2_i` determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise result is the signed angle in radians between the ray ending at the origin and passing through the point `(1,0)` and the ray ending at the origin and passing through the point `(x2_i, x1_i)`. +The mathematical signs of `x1_i` and `x2_i` determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise result is the signed angle in radians between the ray ending at the origin and passing through the point `(1,0)` and the ray ending at the origin and passing through the point `(x2_i, x1_i)`. .. note:: @@ -210,7 +212,7 @@ The signs of `x1_i` and `x2_i` determine the quadrant of each element-wise resul By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined for `x2_i` equal to positive or negative zero and for either or both of `x1_i` and `x2_i` equal to positive or negative `infinity`. -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is greater than `0` and `x2_i` is `+0`, the result is an implementation-dependent approximation to `+π/2`. @@ -225,10 +227,10 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f - If `x1_i` is `-0` and `x2_i` is less than `0`, the result is an implementation-dependent approximation to `-π`. - If `x1_i` is less than `0` and `x2_i` is `+0`, the result is an implementation-dependent approximation to `-π/2`. - If `x1_i` is less than `0` and `x2_i` is `-0`, the result is an implementation-dependent approximation to `-π/2`. -- If `x1_i` is greater than `0`, `x1_i` is finite, and `x2_i` is `+infinity`, the result is `+0`. -- If `x1_i` is greater than `0`, `x1_i` is finite, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `+π`. -- If `x1_i` is less than `0`, `x1_i` is finite, and `x2_i` is `+infinity`, the result is `-0`. -- If `x1_i` is less than `0`, `x1_i` is finite, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `-π`. +- If `x1_i` is greater than `0`, `x1_i` is a finite number, and `x2_i` is `+infinity`, the result is `+0`. +- If `x1_i` is greater than `0`, `x1_i` is a finite number, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `+π`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, and `x2_i` is `+infinity`, the result is `-0`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `-π`. - If `x1_i` is `+infinity` and `x2_i` is finite, the result is an implementation-dependent approximation to `+π/2`. - If `x1_i` is `-infinity` and `x2_i` is finite, the result is an implementation-dependent approximation to `-π/2`. - If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/4`. @@ -250,13 +252,13 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f - **out**: _<array>_ - - an array containing the inverse tangent of the quotient `x1/x2`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse tangent of the quotient `x1/x2`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atanh(x, /) Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -276,7 +278,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t - **out**: _<array>_ - - an array containing the inverse hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # bitwise_and(x1, x2, /) @@ -296,7 +298,7 @@ Computes the bitwise AND of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # bitwise_left_shift(x1, x2, /) @@ -352,7 +354,7 @@ Computes the bitwise OR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # bitwise_right_shift(x1, x2, /) @@ -392,13 +394,13 @@ Computes the bitwise XOR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # ceil(x, /) Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. @@ -418,7 +420,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. @@ -436,7 +438,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai - **out**: _<array>_ - - an array containing the cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # cosh(x, /) @@ -458,25 +460,36 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h - **out**: _<array>_ - - an array containing the hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # divide(x1, x2, /) Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. - 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 `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the 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 sign determined by the rule already stated above. -- If `x1_i` is finite and `x2_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `-infinity`, `+0`, `-0`, or `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 sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate sign. +- 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 @@ -492,7 +505,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # equal(x1, x2, /) @@ -518,7 +531,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. @@ -536,7 +549,7 @@ Calculates an implementation-dependent approximation to the exponential function - **out**: _<array>_ - - an array containing the evaluated exponential function result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated exponential function result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # expm1(x, /) @@ -544,9 +557,9 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai .. note:: - The purpose of this API is to calculate `exp(x)-1.0` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this API as simply `exp(x)-1.0`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate `exp(x)-1.0` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `exp(x)-1.0`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -564,13 +577,13 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # floor(x, /) Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. @@ -604,7 +617,7 @@ Rounds the result of dividing each element `x1_i` of the input array `x1` by the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # greater(x1, x2, /) @@ -738,7 +751,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -756,7 +769,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - **out**: _<array>_ - - an array containing the evaluated natural logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated natural logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log1p(x, /) @@ -764,9 +777,9 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` .. note:: - The purpose of this API is to calculate `log(1+x)` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this API as simply `log(1+x)`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate `log(1+x)` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `log(1+x)`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -785,13 +798,13 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log2(x, /) Calculates an implementation-dependent approximation to the base `2` logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -809,13 +822,13 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `2` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated base `2` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log10(x, /) Calculates an implementation-dependent approximation to the base `10` logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -833,7 +846,7 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `10` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated base `10` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # logical_and(x1, x2, /) @@ -915,21 +928,21 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - 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` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the 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 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 sign determined by the rule already stated above. -- In the remaining cases, where neither an `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 sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. +- 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. .. note:: - Floating-point multiplication not always associative due to finite precision. + Floating-point multiplication is not always associative due to finite precision. #### Parameters @@ -945,7 +958,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. ### # negative(x, /) @@ -961,7 +974,7 @@ Computes the numerical negative of each element `x_i` (i.e., `y_i = -x_i`) of th - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. ### # not_equal(x1, x2, /) @@ -1003,12 +1016,12 @@ Computes the numerical positive of each element `x_i` (i.e., `y_i = +x_i`) of th Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of the input array `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the input array `x2`. -#### Special Values +#### Special Cases - 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 nonzero, the result 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`. @@ -1028,7 +1041,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - 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 finite, `x2_i` is finite, and `x2_i` is not an integer value, the result is `NaN`. +- 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 @@ -1044,7 +1057,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # remainder(x1, x2, /) @@ -1064,13 +1077,13 @@ Returns the remainder of division for each element `x1_i` of the input array `x1 - **out**: _<array>_ - - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # round(x, /) Rounds each element `x_i` of the input array `x` to the nearest integer-valued number. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. - If two integers are equally close to `x_i`, the result is whichever integer is farthest from `0`. @@ -1091,7 +1104,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n Returns an indication of the sign of a number for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is less than `0`, the result is `-1`. - If `x_i` is either `-0` or `+0`, the result is `0`. @@ -1113,7 +1126,7 @@ Returns an indication of the sign of a number for each element `x_i` of the inpu Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1130,13 +1143,13 @@ Calculates an implementation-dependent approximation to the sine, having domain - **out**: _<array>_ - - an array containing the sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # sinh(x, /) Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1154,7 +1167,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - **out**: _<array>_ - - an array containing the hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # square(x, /) @@ -1170,13 +1183,13 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. ### # sqrt(x, /) Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -1194,11 +1207,11 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in - **out**: _<array>_ - - an array containing the square root of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the square root of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # subtract(x1, x2, /) -Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must **always** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add`][#add]). +Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add()`](#add)). #### Parameters @@ -1214,13 +1227,13 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t - **out**: _<array>_ - - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. ### # tan(x, /) Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1237,13 +1250,13 @@ Calculates an implementation-dependent approximation to the tangent, having doma - **out**: _<array>_ - - an array containing the tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # tanh(x, /) Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1261,13 +1274,13 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, - **out**: _<array>_ - - an array containing the hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # trunc(x, /) Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`.