From f37e7a5747bc61dcebd4899928fc75b67b005b3b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 10 Sep 2020 02:11:47 -0700 Subject: [PATCH 01/14] Add elementwise signatures --- .../elementwise_functions.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index f925e46c8..66d123c4b 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -370,6 +370,32 @@ Calculates an implementation-dependent approximation to the exponential function - an array containing the evaluated exponential function result for each element in `x`. +### # expm1(x, /, *, out=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` (`e` raised to the power of `x_i` minus `1`, where `e` is the base of the natural logarithm). + +- 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. + +- **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 evaluated result for each element in `x`. + ### # floor(x, /, *, out=None) 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`. @@ -514,6 +540,85 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - an array containing the evaluated natural logarithm for each element in `x`. +### # log1p(x, /, *, out=None) + +Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[-1, +infinity]` and codomain `[-infinity, +infinity]`, of `1+x_i` 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 `-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. + +- **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 evaluated result for each element in `x`. + +### # log2(x, /, *, out=None) + +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`. + +#### Parameters + +- **x**: _<array>_ + + - 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 evaluated base `2` logarithm for each element in `x`. + +### # log10(x, /, *, out=None) + +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. + +- **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 evaluated base `10` logarithm for each element in `x`. + ### # logical_and(x1, x2, /, *, out=None) 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`. @@ -679,6 +784,30 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n - an array containing the rounded result for each element in `x`. +### # sign(x, /, *, out=None) + +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. + +- **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 evaluated result for each element in `x`. + ### # sin(x, /, *, out=None) 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. @@ -730,6 +859,26 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - an array containing the hyperbolic sine of each element in `x`. +### # square(x, /, *, out=None) + +Squares (`x_i * x_i`) each element `x_i` of the input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - 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 evaluated result for each element in `x`. + ### # sqrt(x, /, *, out=None) 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). From 0323a858f5c6ae4276f524482ef37e7c235f8ed5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 10 Sep 2020 09:36:32 -0700 Subject: [PATCH 02/14] Update description --- spec/API_specification/elementwise_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 66d123c4b..6b0810860 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -372,7 +372,7 @@ Calculates an implementation-dependent approximation to the exponential function ### # expm1(x, /, *, out=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` (`e` raised to the power of `x_i` minus `1`, where `e` is the base of the natural logarithm). +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`. - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. From 0901c44555a011d146b9018413f9c166c8367233 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 10 Sep 2020 09:39:35 -0700 Subject: [PATCH 03/14] Add note returning return array data type --- spec/API_specification/elementwise_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 6b0810860..12c84f937 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -806,7 +806,7 @@ Returns an indication of the sign of a number for each element `x_i` of the inpu - **out**: _<array>_ - - an array containing the evaluated 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) From e14adced2b4ffda4b5282ff40b105149f26120af Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:34:58 -0700 Subject: [PATCH 04/14] Update phrasing --- spec/API_specification/elementwise_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 12c84f937..469d5066d 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -542,7 +542,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l ### # log1p(x, /, *, out=None) -Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[-1, +infinity]` and codomain `[-infinity, +infinity]`, of `1+x_i` for each element `x_i` of the input array `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`. - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. From 5c6ddd8576ab505bfa71664747aa8964dd726ef7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:44:22 -0700 Subject: [PATCH 05/14] Remove `out` keyword argument --- .../elementwise_functions.md | 259 ++++-------------- 1 file changed, 51 insertions(+), 208 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 469d5066d..0547208f4 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,17 +69,13 @@ 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`. @@ -102,11 +89,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 +97,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 +113,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 +135,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 +157,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 +181,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 +199,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 +221,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,17 +243,13 @@ 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`. @@ -320,7 +275,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 +287,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 +295,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 +311,13 @@ Calculates an implementation-dependent approximation to the exponential function - 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 evaluated exponential function result for each element in `x`. -### # expm1(x, /, *, out=None) +### # expm1(x, /) 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`. @@ -386,17 +333,13 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai - 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 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`. @@ -408,17 +351,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`. @@ -432,17 +371,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`. @@ -454,11 +389,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 @@ -466,7 +397,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`. @@ -478,11 +409,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 @@ -490,7 +417,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`. @@ -502,11 +429,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 @@ -514,7 +437,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`. @@ -530,17 +453,13 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - 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 evaluated natural logarithm for each element in `x`. -### # log1p(x, /, *, out=None) +### # 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`. @@ -557,17 +476,13 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` - 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 evaluated result for each element in `x`. -### # log2(x, /, *, out=None) +### # 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`. @@ -583,17 +498,13 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, - 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 evaluated base `2` logarithm for each element in `x`. -### # log10(x, /, *, out=None) +### # 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`. @@ -609,17 +520,13 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, - 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 evaluated base `10` logarithm for each element in `x`. -### # logical_and(x1, x2, /, *, out=None) +### # 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`. @@ -631,11 +538,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 @@ -643,7 +546,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`. @@ -651,11 +554,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 @@ -663,7 +562,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`. @@ -675,11 +574,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 @@ -687,9 +582,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 @@ -699,11 +594,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 @@ -711,7 +602,7 @@ 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`. @@ -727,17 +618,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`. @@ -749,11 +636,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 @@ -761,7 +644,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. @@ -774,17 +657,13 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n - 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`. -### # sign(x, /, *, out=None) +### # sign(x, /) Returns an indication of the sign of a number for each element `x_i` of the input array `x`. @@ -798,17 +677,13 @@ Returns an indication of the sign of a number for each element `x_i` of the inpu - 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 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. @@ -823,17 +698,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`. @@ -849,17 +720,13 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - 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 sine of each element in `x`. -### # square(x, /, *, out=None) +### # square(x, /) Squares (`x_i * x_i`) each element `x_i` of the input array `x`. @@ -869,17 +736,13 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. - 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 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). @@ -895,17 +758,13 @@ 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`. @@ -921,17 +780,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. @@ -946,17 +801,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`. @@ -972,17 +823,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`. @@ -994,10 +841,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>_ From cdb3976ef0d2e5a85e4631c47368ac2df92cbfc8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:55:38 -0700 Subject: [PATCH 06/14] Add note --- spec/API_specification/elementwise_functions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 0547208f4..9f17772c6 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -321,6 +321,8 @@ Calculates an implementation-dependent approximation to the exponential function 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, which is particularly useful in financial applications, 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`. From 6ce4fe4bb6542687d04fb8ee6509928aeac6d437 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:57:06 -0700 Subject: [PATCH 07/14] Add note --- spec/API_specification/elementwise_functions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 9f17772c6..6afb8e6e7 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -465,6 +465,8 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l 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, which is particularly useful in financial applications, 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`. From 4e2540fcf56a3a808dfc5e4a4d7296fc3eb462bb Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:59:43 -0700 Subject: [PATCH 08/14] Reformat notes --- spec/API_specification/elementwise_functions.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 6afb8e6e7..c68039541 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -321,7 +321,9 @@ Calculates an implementation-dependent approximation to the exponential function 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, which is particularly useful in financial applications, 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._ +.. note:: + + The purpose of this API, which is particularly useful in financial applications, 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`. @@ -465,7 +467,9 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l 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, which is particularly useful in financial applications, 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._ +.. note:: + + The purpose of this API, which is particularly useful in financial applications, 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`. From 258a0482c70b85753361eaf4875266a3a460bace Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 22:05:25 -0700 Subject: [PATCH 09/14] Add pow signature --- .../elementwise_functions.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index c68039541..646287d2c 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -648,6 +648,51 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input #### 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 + +- **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 + - **out**: _<array>_ - an array containing the element-wise results. From 2a3b65bc96ec5a3662694c02057ea447626ef65d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 00:09:24 -0700 Subject: [PATCH 10/14] Add floating-point arithmetic behavior --- .../elementwise_functions.md | 72 +++++++++++-------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 646287d2c..e4da5f99d 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -77,9 +77,25 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c ### # 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 is 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 the appropriate sign. #### Parameters @@ -656,30 +672,30 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input 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`. +- 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 @@ -720,9 +736,9 @@ 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`. -- 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`. +- 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 From a34aa98c2cf64785639c2fc146be834d8a3f907a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 00:19:50 -0700 Subject: [PATCH 11/14] Update subtract notes --- spec/API_specification/elementwise_functions.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index e4da5f99d..0de5acba8 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -97,6 +97,10 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - 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 is 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 the appropriate sign. +.. note:: + + Floating-point addition is a commutative operation, but not always associative. + #### Parameters - **x1**: _<array>_ @@ -835,9 +839,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in ### # 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 From a9e2ab3d82e6cbaae1d497d432a62a62f01e2d75 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 01:03:46 -0700 Subject: [PATCH 12/14] Add divide notes --- .../elementwise_functions.md | 28 +++++++++++++++++-- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 0de5acba8..a461556df 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -95,7 +95,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - 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 is 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 the appropriate sign. +- 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:: @@ -271,9 +271,19 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h ### # 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 operands, - 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 @@ -632,9 +642,21 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th ### # 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 operands, - 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 From 2f12635d30e04b1197bf45921bcec8b1c5b6899c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 01:05:30 -0700 Subject: [PATCH 13/14] Update copy --- spec/API_specification/elementwise_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index a461556df..64c6dbf5b 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -271,7 +271,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h ### # 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 operands, +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. @@ -642,7 +642,7 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th ### # 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`. For floating-point operands, +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. From a021c230c2d6ef97ae79a5a5a71b2451289f89a7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Tue, 15 Sep 2020 16:55:37 -0700 Subject: [PATCH 14/14] Update copy --- spec/API_specification/elementwise_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 64c6dbf5b..23eb56379 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -353,7 +353,7 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai .. note:: - The purpose of this API, which is particularly useful in financial applications, 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 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`. @@ -499,7 +499,7 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` .. note:: - The purpose of this API, which is particularly useful in financial applications, 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 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`.