diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index f925e46c8..23eb56379 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -6,7 +6,6 @@ A conforming implementation of the array API standard must provide and support t - 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 function 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. -- The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`. - Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. - Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. - Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. @@ -14,7 +13,7 @@ A conforming implementation of the array API standard must provide and support t -### # abs(x, /, *, out=None) +### # abs(x, /) 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). @@ -28,17 +27,13 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the absolute value of each element in `x`. -### # acos(x, /, *, out=None) +### # acos(x, /) 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. @@ -53,17 +48,13 @@ Calculates an implementation-dependent approximation of the principal value of t - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse cosine of each element in `x`. -### # acosh(x, /, *, out=None) +### # 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`. @@ -78,21 +69,37 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c - input array whose elements each represent the area of a hyperbolic sector. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse hyperbolic cosine of each element in `x`. -### # add(x1, x2, /, *, out=None) +### # 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`. +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, - 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 `-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 `+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 `+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. + +.. note:: + + Floating-point addition is a commutative operation, but not always associative. #### Parameters @@ -102,11 +109,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -114,7 +117,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - an array containing the element-wise sums. -### # asin(x, /, *, out=None) +### # 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. @@ -130,17 +133,13 @@ Calculates an implementation-dependent approximation of the principal value of t - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse sine of each element in `x`. -### # asinh(x, /, *, out=None) +### # 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`. @@ -156,17 +155,13 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s - input array whose elements each represent the area of a hyperbolic sector. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse hyperbolic sine of each element in `x`. -### # atan(x, /, *, out=None) +### # 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. @@ -182,17 +177,13 @@ Calculates an implementation-dependent approximation of the principal value of t - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse tangent of each element in `x`. -### # atanh(x, /, *, out=None) +### # 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`. @@ -210,17 +201,13 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t - input array whose elements each represent the area of a hyperbolic sector. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the inverse hyperbolic tangent of each element in `x`. -### # ceil(x, /, *, out=None) +### # 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`. @@ -232,17 +219,13 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the rounded result for each element in `x`. -### # cos(x, /, *, out=None) +### # cos(x, /) 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. @@ -258,17 +241,13 @@ Calculates an implementation-dependent approximation to the cosine, having domai - input array whose elements are each expressed in radians. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the cosine of each element in `x`. -### # cosh(x, /, *, out=None) +### # cosh(x, /) Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`. @@ -284,21 +263,27 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h - input array whose elements each represent a hyperbolic angle. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the hyperbolic cosine of each element in `x`. -### # divide(x1, x2, /, *, out=None) +### # 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`. +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, - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. +- If both `x1_i` and `x2_i` has the same sign, the result is positive. +- If `x1_i` and `x2_i` has 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 finite nonzero value, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is a finite value 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 finite nonzero value, the result is a signed zero with the sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite value 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. #### Parameters @@ -320,7 +305,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the - an array containing the element-wise results. -### # equal(x1, x2, /, *, out=None) +### # equal(x1, x2, /) Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -332,11 +317,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -344,7 +325,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input - an array containing the element-wise results. -### # exp(x, /, *, out=None) +### # exp(x, /) 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). @@ -360,17 +341,39 @@ Calculates an implementation-dependent approximation to the exponential function - input array. -- **out**: _Optional\[ <array> ]_ +#### Returns + +- **out**: _<array>_ + + - an array containing the evaluated exponential function result for each element in `x`. + +### # expm1(x, /) - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. +Calculates an implementation-dependent approximation to `exp(x)-1`, having domain `[-infinity, +infinity]` and codomain `[-1, +infinity]`, for each element `x_i` of the input array `x`. + +.. 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. + +- 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 `+infinity`. +- If `x_i` is `-infinity`, the result is `-1`. + +#### Parameters + +- **x**: _<array>_ + + - input array. #### Returns - **out**: _<array>_ - - an array containing the evaluated exponential function result for each element in `x`. + - an array containing the evaluated result for each element in `x`. -### # floor(x, /, *, out=None) +### # 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`. @@ -382,17 +385,13 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the rounded result for each element in `x`. -### # greater(x1, x2, /, *, out=None) +### # greater(x1, x2, /) Computes the truth value of `x1_i > x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -406,17 +405,13 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of the input a - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the element-wise results. -### # greater_equal(x1, x2, /, *, out=None) +### # greater_equal(x1, x2, /) Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -428,11 +423,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of the input - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -440,7 +431,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of the input - an array containing the element-wise results. -### # less(x1, x2, /, *, out=None) +### # less(x1, x2, /) Computes the truth value of `x1_i < x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -452,11 +443,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of the input a - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -464,7 +451,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of the input a - an array containing the element-wise results. -### # less_equal(x1, x2, /, *, out=None) +### # less_equal(x1, x2, /) Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -476,11 +463,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -488,7 +471,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input - an array containing the element-wise results. -### # log(x, /, *, out=None) +### # log(x, /) 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`. @@ -504,17 +487,84 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - input array. -- **out**: _Optional\[ <array> ]_ +#### Returns - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. +- **out**: _<array>_ + + - an array containing the evaluated natural logarithm for each element in `x`. + +### # log1p(x, /) + +Calculates an implementation-dependent approximation to `log(1+x)`, where `log` refers to the natural (base `e`) logarithm, having domain `[-1, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. + +.. 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. + +- If `x_i` is `NaN`, the result is `NaN`. +- If `x_i` is less than `-1`, the result is `NaN`. +- If `x_i` is `-1`, the result is `-infinity`. +- 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 `+infinity`. + +#### Parameters + +- **x**: _<array>_ + + - input array. #### Returns - **out**: _<array>_ - - an array containing the evaluated natural logarithm for each element in `x`. + - an array containing the evaluated result for each element in `x`. + +### # 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`. + +- If `x_i` is `NaN`, the result is `NaN`. +- If `x_i` is less than `0`, the result is `NaN`. +- If `x_i` is `+0` or `-0`, the result is `-infinity`. +- If `x_i` is `1`, the result is `+0`. +- If `x_i` is `+infinity`, the result is `+infinity`. -### # logical_and(x1, x2, /, *, out=None) +#### Parameters + +- **x**: _<array>_ + + - input array. + +#### Returns + +- **out**: _<array>_ + + - an array containing the evaluated base `2` logarithm for each element in `x`. + +### # 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`. + +- If `x_i` is `NaN`, the result is `NaN`. +- If `x_i` is less than `0`, the result is `NaN`. +- If `x_i` is `+0` or `-0`, the result is `-infinity`. +- If `x_i` is `1`, the result is `+0`. +- If `x_i` is `+infinity`, the result is `+infinity`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +#### Returns + +- **out**: _<array>_ + + - an array containing the evaluated base `10` logarithm for each element in `x`. + +### # logical_and(x1, x2, /) Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. @@ -526,11 +576,7 @@ Computes the logical AND for each element `x1_i` of the input array `x1` with th - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -538,7 +584,7 @@ Computes the logical AND for each element `x1_i` of the input array `x1` with th - an array containing the element-wise results. -### # logical_not(x, /, *, out=None) +### # logical_not(x, /) Computes the logical NOT for each element `x_i` of the input array `x`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. @@ -546,11 +592,7 @@ Computes the logical NOT for each element `x_i` of the input array `x`. Zeros sh - **x**: _<array>_ - - input array. - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array `x` (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - input array. #### Returns @@ -558,7 +600,7 @@ Computes the logical NOT for each element `x_i` of the input array `x`. Zeros sh - an array containing the element-wise results. -### # logical_or(x1, x2, /, *, out=None) +### # logical_or(x1, x2, /) Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. @@ -570,11 +612,7 @@ Computes the logical OR for each element `x1_i` of the input array `x1` with the - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -582,9 +620,9 @@ Computes the logical OR for each element `x1_i` of the input array `x1` with the - an array containing the element-wise results. -### # logical_xor(x1, x2, /, *, out=None) +### # logical_xor(x1, x2, /) -Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros must should be considered the equivalent of `False`, while non-zeros must should be considered the equivalent of `True`. +Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. #### Parameters @@ -594,11 +632,7 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). - -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -606,11 +640,23 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th - an array containing the element-wise results. -### # multiply(x1, x2, /, *, out=None) +### # multiply(x1, x2, /) -Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. +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, - 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 `+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 either `+infinity` and `-infinity` with the sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a finite nonzero value, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is a finite nonzero value 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. + +.. note:: + + Floating-point multiplication not always associative due to finite precision. #### Parameters @@ -622,17 +668,13 @@ Calculates the product for each element `x1_i` of the input array `x1` with the - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the element-wise products. -### # not_equal(x1, x2, /, *, out=None) +### # not_equal(x1, x2, /) Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -644,11 +686,52 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). -- **out**: _Optional\[ <array> ]_ +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +### # pow(x1, x2, /) + +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`. + +- 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 `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 finite, `x2_i` is finite, and `x2_i` is not an integer value, the result is `NaN`. + +#### Parameters - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array, whose underlying data type is `bool`, must be created and then filled with the result of each element-wise computation. Default: `None`. +- **x1**: _<array>_ + + - first input array whose elements correspond to the exponentiation base. + +- **x2**: _<array>_ + + - second input array whose elements correspond to the exponentiation exponent. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -656,7 +739,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input - an array containing the element-wise results. -### # round(x, /, *, out=None) +### # round(x, /) Rounds each element `x_i` of the input array `x` to the nearest integer-valued number. @@ -669,17 +752,33 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n - input array. -- **out**: _Optional\[ <array> ]_ +#### Returns + +- **out**: _<array>_ + + - an array containing the rounded result for each element in `x`. - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. +### # sign(x, /) + +Returns an indication of the sign of a number for each element `x_i` of the input array `x`. + +- If `x_i` is less than `0`, the result is `-1`. +- If `x_i` is `-0` or `+0`, the result is `0`. +- If `x_i` is greater than `0`, the result is `+1`. + +#### Parameters + +- **x**: _<array>_ + + - input array. #### Returns - **out**: _<array>_ - - an array containing the rounded result for each element in `x`. + - an array containing the evaluated result for each element in `x`. If `out` is `None`, the returned array must have the same data type as `x`. -### # sin(x, /, *, out=None) +### # sin(x, /) 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. @@ -694,17 +793,13 @@ Calculates an implementation-dependent approximation to the sine, having domain - input array whose elements are each expressed in radians. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the sine of each element in `x`. -### # sinh(x, /, *, out=None) +### # 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`. @@ -720,17 +815,29 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - input array whose elements each represent a hyperbolic angle. -- **out**: _Optional\[ <array> ]_ +#### Returns - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. +- **out**: _<array>_ + + - an array containing the hyperbolic sine of each element in `x`. + +### # square(x, /) + +Squares (`x_i * x_i`) each element `x_i` of the input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. #### Returns - **out**: _<array>_ - - an array containing the hyperbolic sine of each element in `x`. + - an array containing the evaluated result for each element in `x`. -### # sqrt(x, /, *, out=None) +### # 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). @@ -746,21 +853,15 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the square root of each element in `x`. -### # subtract(x1, x2, /, *, out=None) +### # 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`. - -- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. +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]). #### Parameters @@ -772,17 +873,13 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the element-wise differences. -### # tan(x, /, *, out=None) +### # 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. @@ -797,17 +894,13 @@ Calculates an implementation-dependent approximation to the tangent, having doma - input array whose elements are each expressed in radians. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the tangent of each element in `x`. -### # tanh(x, /, *, out=None) +### # 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`. @@ -823,17 +916,13 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, - input array whose elements each represent a hyperbolic angle. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_ - an array containing the hyperbolic tangent of each element in `x`. -### # trunc(x, /, *, out=None) +### # 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`. @@ -845,10 +934,6 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th - input array. -- **out**: _Optional\[ <array> ]_ - - - output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`. - #### Returns - **out**: _<array>_