From be4d6f10173322072831793da313bba3cad7bf15 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 02:49:36 -0700 Subject: [PATCH 01/27] Add TODO --- spec/API_specification/array_object.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 07e4f0850..22fde1e5a 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -1 +1,3 @@ # Array object + +> TODO \ No newline at end of file From a3a3d3ea3671c2cbe7b0911c0054213c8365f3dd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Oct 2020 01:44:06 -0700 Subject: [PATCH 02/27] Add attributes --- spec/API_specification/array_object.md | 69 +++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 22fde1e5a..5895c062b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -1,3 +1,70 @@ # Array object -> TODO \ No newline at end of file +> Array API specification for array object attributes and methods. + +A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods adhering to the following conventions. + +- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a method accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, methods must support the data types defined in :ref:`data-types`. +- Unless stated otherwise, methods must adhere to the type promotion rules defined in :ref:`type-promotion`. +- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. + +## Attributes + + + +### # dtype + +Data type of the array elements. + +#### Returns + +- **out**: _<dtype>_ + + - array data type. + +### # ndim + +Number of array dimensions (axes). + +#### Returns + +- **out**: _int_ + + - number of array dimensions (axes). + +### # shape + +Array dimensions. + +#### Returns + +- **out**: _Union\[ Tuple\[ int, ...], <shape> ]_ + + - array dimensions as either a tuple or a custom shape object. If a shape object, the object must be immutable and must support indexing for dimension retrieval. + +### # size + +Number of elements in an array. This should equal the product of the array's dimensions. + +#### Returns + +- **out**: _int_ + + - number of elements in an array. + +### # T + +Transpose of the array. + +#### Returns + +- **out**: _<array>_ + + - array whose dimensions (axes) are permuted in reverse order relative to original array. Must have the same data type as the original array. + +## Methods + + From f765c380dfe4d278c5d2709bb0ee78799ecfb1c2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Oct 2020 02:03:36 -0700 Subject: [PATCH 03/27] Add method --- spec/API_specification/array_object.md | 24 +++++++++++++++++++ .../elementwise_functions.md | 2 +- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 5895c062b..995589d15 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -68,3 +68,27 @@ Transpose of the array. ## Methods + +### # \_\_abs\_\_(self, /) + +Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). + +- If `x_i` is `NaN`, the result is `NaN`. +- If `x_i` is `-0`, the result is `+0`. +- If `x_i` is `-infinity`, the result is `+infinity`. + +#### Parameters + +- **self**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise absolute value. Must have the same data type as `self`. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 861ff87fe..fada53e7d 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -31,7 +31,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e - **out**: _<array>_ - - an array containing the absolute value of each element in `x`. + - an array containing the element-wise absolute value. Must have the same data type as `x`. ### # acos(x, /) From 45ab2a2dfeae51245a0db2b03d20ab111c8e08d8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Oct 2020 02:09:39 -0700 Subject: [PATCH 04/27] Add horizontal rules --- spec/API_specification/array_object.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 995589d15..09649105a 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -11,6 +11,8 @@ A conforming implementation of the array API standard must provide and support a - Unless stated otherwise, methods must adhere to the type promotion rules defined in :ref:`type-promotion`. - Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +* * * + ## Attributes @@ -65,6 +67,8 @@ Transpose of the array. - array whose dimensions (axes) are permuted in reverse order relative to original array. Must have the same data type as the original array. +* * * + ## Methods From 19d3604c030a4751d8fee6d8f5e72bca9b68d367 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Oct 2020 09:37:00 -0700 Subject: [PATCH 05/27] Add methods --- spec/API_specification/array_object.md | 455 +++++++++++++++++- .../elementwise_functions.md | 2 +- 2 files changed, 452 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 09649105a..759e44dc2 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -73,7 +73,7 @@ Transpose of the array. -### # \_\_abs\_\_(self, /) +### # \_\_abs\_\_(x, /) Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). @@ -83,7 +83,7 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i #### Parameters -- **self**: _<array>_ +- **x**: _<array>_ - array instance. @@ -91,8 +91,455 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i - **out**: _<array>_ - - an array containing the element-wise absolute value. Must have the same data type as `self`. + - an array containing the element-wise absolute value. Must have the same data type as `x`. .. note:: - Element-wise results should equal those of the equivalent element-wise function. + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `abs`. + +### # \_\_add\_\_(x1, x2, /) + +Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 + +- **x1**: _<array>_ + + - array instance (augend array). + +- **x2**: _<array;gt;_ + + - addend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise sums. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `add`. + +### # \_\_and\_\_(x1, x2, /) + +Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +### # \_\_eq\_\_(x1, x2, /) + +Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `equal`. + +### # \_\_floordiv\_\_(x1, x2, /) + +Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_ge\_\_(x1, x2, /) + +Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `greater_equal`. + +### # \_\_getitem\_\_(x, key, /) + +TODO + +### # \_\_gt\_\_(x1, x2, /) + +Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `greater`. + +### # \_\_invert\_\_(x, /) + +Evaluates `~x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart (bitwise_not) + +### # \_\_le\_\_(x1, x2, /) + +Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `less_equal`. + +### # \_\_len\_\_(x, /) + +TODO + +### # \_\_lshift\_\_(x1, x2, /) + +Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? + +### # \_\_lt\_\_(x1, x2, /) + +Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `less`. + +### # \_\_mod\_\_(x1, x2, /) + +Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_mul\_\_(x1, x2, /) + +Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 is not always associative due to finite precision. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise products. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `multiply`. + +### # \_\_ne\_\_(x1, x2, /) + +Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `not_equal`. + +### # \_\_neg\_\_(x, /) + +Evaluates `-x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (numpy.negative) + +### # \_\_or\_\_(x1, x2, /) + +Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (bitwise_or) + +### # \_\_pos\_\_(x, /) + +Evaluates `+x_i` for each element `x_i` of an array instance `x`. + +#### Parameters + +- **x**: _<array>_ + + - array instance. + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (numpy.positive) + +### # \_\_pow\_\_(x1, x2, /) + +Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. + +- 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>_ + + - array instance whose elements correspond to the exponentiation base. + +- **x2**: _<array;gt;_ + + - other array whose elements correspond to the exponentiation exponent. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. \ No newline at end of file diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index fada53e7d..779c50ab2 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -756,7 +756,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the .. note:: - Floating-point multiplication not always associative due to finite precision. + Floating-point multiplication is not always associative due to finite precision. #### Parameters From 89282b981acbc1bd93f7c133b8cc26114240efce Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 18 Oct 2020 21:09:08 -0700 Subject: [PATCH 06/27] Add specifications --- spec/API_specification/array_object.md | 437 ++++++++++++++++++++++++- 1 file changed, 436 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 759e44dc2..4268025a1 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -37,6 +37,8 @@ Number of array dimensions (axes). - number of array dimensions (axes). +TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of dimensions may be dynamic. + ### # shape Array dimensions. @@ -47,6 +49,8 @@ Array dimensions. - array dimensions as either a tuple or a custom shape object. If a shape object, the object must be immutable and must support indexing for dimension retrieval. +TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic. + ### # size Number of elements in an array. This should equal the product of the array's dimensions. @@ -57,6 +61,8 @@ Number of elements in an array. This should equal the product of the array's dim - number of elements in an array. +TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of elements may be dynamic. + ### # T Transpose of the array. @@ -542,4 +548,433 @@ Calculates an implementation-dependent approximation of exponentiation by raisin .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. \ No newline at end of file + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. + +### # \_\_radd\_\_(x1, x2, /) + +Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 + +- **x1**: _<array>_ + + - array instance (addend array). + +- **x2**: _<array;gt;_ + + - augend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise sums. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `add`. + +### # \_\_rand\_\_(x1, x2, /) + +Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +### # \_\_rfloordiv\_\_(x1, x2, /) + +Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_rlshift\_\_(x1, x2, /) + +Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? + +### # \_\_rmod\_\_(x1, x2, /) + +Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_rmul\_\_(x1, x2, /) + +Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 is not always associative due to finite precision. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise products. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `multiply`. + +### # \_\_ror\_\_(x1, x2, /) + +Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (bitwise_or) + +### # \_\_rpow\_\_(x1, x2, /) + +Calculates an implementation-dependent approximation of exponentiation by raising each element `x2_i` (the base) of an array `x2` to the power of `x1_i` (the exponent), where `x1_i` is the corresponding element of the array instance `x1`. + +- If `x2_i` is not equal to `1` and `x1_i` is `NaN`, the result is `NaN`. +- If `x1_i` is `+0`, the result is `1`, even if `x2_i` is `NaN`. +- If `x1_i` is `-0`, the result is `1`, even if `x2_i` is `NaN`. +- If `x2_i` is `NaN` and `x1_i` is nonzero, the result is `NaN`. +- If `abs(x2_i)` is greater than `1` and `x1_i` is `+infinity`, the result is `+infinity`. +- If `abs(x2_i)` is greater than `1` and `x1_i` is `-infinity`, the result is `+0`. +- If `abs(x2_i)` is `1` and `x1_i` is `+infinity`, the result is `1`. +- If `abs(x2_i)` is `1` and `x1_i` is `-infinity`, the result is `1`. +- If `x2_i` is `1` and `x1_i` is not `NaN`, the result is `1`. +- If `abs(x2_i)` is less than `1` and `x1_i` is `+infinity`, the result is `+0`. +- If `abs(x2_i)` is less than `1` and `x1_i` is `-infinity`, the result is `+infinity`. +- If `x2_i` is `+infinity` and `x1_i` is greater than `0`, the result is `+infinity`. +- If `x2_i` is `+infinity` and `x1_i` is less than `0`, the result is `+0`. +- If `x2_i` is `-infinity` and `x1_i` is greater than `0`, the result is `-infinity`. +- If `x2_i` is `-infinity`, `x1_i` is greater than `0`, and `x1_i` is not an odd integer value, the result is `+infinity`. +- If `x2_i` is `-infinity`, `x1_i` is less than `0`, and `x1_i` is an odd integer value, the result is `-0`. +- If `x2_i` is `-infinity`, `x1_i` is less than `0`, and `x1_i` is not an odd integer value, the result is `+0`. +- If `x2_i` is `+0` and `x1_i` is greater than `0`, the result is `+0`. +- If `x2_i` is `+0` and `x1_i` is less than `0`, the result is `+infinity`. +- If `x2_i` is `-0`, `x1_i` is greater than `0`, and `x1_i` is an odd integer value, the result is `-0`. +- If `x2_i` is `-0`, `x1_i` is greater than `0`, and `x1_i` is not an odd integer value, the result is `+0`. +- If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is an odd integer value, the result is `-infinity`. +- If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is not an odd integer value, the result is `+infinity`. +- If `x2_i` is less than `0`, `x2_i` is finite, `x1_i` is finite, and `x1_i` is not an integer value, the result is `NaN`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance whose elements correspond to the exponentiation exponent. + +- **x2**: _<array;gt;_ + + - other array whose elements correspond to the exponentiation base. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. + +### # \_\_rrshift\_\_(x1, x2, /) + +Evaluates `x2_i >> x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? + +### # \_\_rshift\_\_(x1, x2, /) + +Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? + +### # \_\_rsub\_\_(x1, x2, /) + +Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` **must** be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`][#__radd__]). + +#### Parameters + +- **x1**: _<array>_ + + - array instance (subtrahend array). + +- **x2**: _<array;gt;_ + + - minuend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise differences. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `subtract`. + +### # \_\_rtruediv\_\_(x1, x2, /) + +Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_rxor\_\_(x1, x2, /) + +Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (bitwise_or) + +### # \_\_setitem\_\_(x, key, value, /) + +TODO + +### # \_\_sizeof\_\_(x, /) + +TODO + +### # \_\_sub\_\_(x1, x2, /) + +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` **must** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`][#__add__]). + +#### Parameters + +- **x1**: _<array>_ + + - array instance (minuend array). + +- **x2**: _<array;gt;_ + + - subtrahend array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise differences. + +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `subtract`. + +### # \_\_truediv\_\_(x1, x2, /) + +Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: an element-wise counterpart API + +### # \_\_xor\_\_(x1, x2, /) + +Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array;gt;_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - an array containing the element-wise results. + +TODO: functional counterpart? (bitwise_xor) \ No newline at end of file From 2dd559ed22aa8339bc43c310e8a7c5b7a0ef74c0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 18 Oct 2020 21:09:58 -0700 Subject: [PATCH 07/27] Fix markup --- spec/API_specification/array_object.md | 52 +++++++++++++------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 4268025a1..bcb3527f8 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -135,7 +135,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - array instance (augend array). -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - addend array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -159,7 +159,7 @@ Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -179,7 +179,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array i - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -203,7 +203,7 @@ Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -323,7 +323,7 @@ Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -369,7 +369,7 @@ Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -405,7 +405,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -429,7 +429,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array i - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -471,7 +471,7 @@ Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -536,7 +536,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - array instance whose elements correspond to the exponentiation base. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array whose elements correspond to the exponentiation exponent. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -582,7 +582,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - array instance (addend array). -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - augend array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -606,7 +606,7 @@ Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -626,7 +626,7 @@ Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -648,7 +648,7 @@ Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -670,7 +670,7 @@ Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -706,7 +706,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -730,7 +730,7 @@ Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -777,7 +777,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - array instance whose elements correspond to the exponentiation exponent. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array whose elements correspond to the exponentiation base. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -801,7 +801,7 @@ Evaluates `x2_i >> x1_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -823,7 +823,7 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -845,7 +845,7 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp - array instance (subtrahend array). -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - minuend array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -869,7 +869,7 @@ Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -891,7 +891,7 @@ Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -921,7 +921,7 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with - array instance (minuend array). -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - subtrahend array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -945,7 +945,7 @@ Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). @@ -967,7 +967,7 @@ Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with t - array instance. -- **x2**: _<array;gt;_ +- **x2**: _<array>_ - other array. Must be compatible with `x1` (see :ref:`broadcasting`). From 8420a6dc22f8ba024b246ace9d6ea67826244e0d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 18 Oct 2020 21:36:12 -0700 Subject: [PATCH 08/27] Update specs --- spec/API_specification/array_object.md | 42 ++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index bcb3527f8..23fac6112 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -616,6 +616,8 @@ Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. +TODO: link to functional equivalent + ### # \_\_rfloordiv\_\_(x1, x2, /) Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. @@ -861,17 +863,29 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp ### # \_\_rtruediv\_\_(x1, x2, /) -Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 `x2_i` is either `+infinity` or `-infinity` and `x1_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is a finite nonzero value, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x2_i` is a finite value and `x1_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 `x2_i` is either `+0` or `-0` and `x1_i` is a finite nonzero value, the result is a signed zero with the sign determined by the rule already stated above. +- If `x2_i` is a nonzero finite value and `x1_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 - **x1**: _<array>_ - - array instance. + - array instance (divisor). - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - dividend array. Must be compatible with `x1` (see :ref:`broadcasting`). #### Returns @@ -879,7 +893,9 @@ Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `divide`. ### # \_\_rxor\_\_(x1, x2, /) @@ -937,7 +953,19 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with ### # \_\_truediv\_\_(x1, x2, /) -Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, + +- 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 @@ -955,7 +983,9 @@ Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `divide`. ### # \_\_xor\_\_(x1, x2, /) From 4a73f3e9e81613f91b35ed56b92d54841020bb6f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 19 Oct 2020 00:04:01 -0700 Subject: [PATCH 09/27] Add TODO --- spec/API_specification/array_object.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 23fac6112..669b24de8 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -169,6 +169,8 @@ Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. +TODO: functional counterpart + ### # \_\_eq\_\_(x1, x2, /) Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. From 710ac01d10bb470dddb9c2e0b913b35e0b3a1ff4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Fri, 6 Nov 2020 00:36:41 -0600 Subject: [PATCH 10/27] Update markup --- spec/API_specification/array_object.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 669b24de8..97ce67ac3 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -37,7 +37,7 @@ Number of array dimensions (axes). - number of array dimensions (axes). -TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of dimensions may be dynamic. +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of dimensions may be dynamic._ ### # shape @@ -49,7 +49,7 @@ Array dimensions. - array dimensions as either a tuple or a custom shape object. If a shape object, the object must be immutable and must support indexing for dimension retrieval. -TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic. +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ ### # size @@ -61,7 +61,7 @@ Number of elements in an array. This should equal the product of the array's dim - number of elements in an array. -TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of elements may be dynamic. +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where the number of elements may be dynamic._ ### # T From 7f1c2fde33726d717adffbd95050f69a67f68061 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Fri, 6 Nov 2020 23:37:36 -0600 Subject: [PATCH 11/27] Update notes --- spec/API_specification/array_object.md | 66 ++++++++++++------- .../elementwise_functions.md | 2 + 2 files changed, 46 insertions(+), 22 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index ca9a7d6ba..7f5d95695 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -103,7 +103,7 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `abs`. + Element-wise results must equal those of the equivalent element-wise function [`abs()`](elementwise_functions.md#abs). ### # \_\_add\_\_(x1, x2, /) @@ -149,7 +149,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `add`. + Element-wise results must equal those of the equivalent element-wise function [`add()`](elementwise_functions.md#add). ### # \_\_and\_\_(x1, x2, /) @@ -171,7 +171,9 @@ Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: functional counterpart +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`bitwise_and()`](elementwise_functions.md#and). ### # \_\_eq\_\_(x1, x2, /) @@ -195,7 +197,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `equal`. + Element-wise results must equal those of the equivalent element-wise function [`equal`](elementwise_functions.md#equal). ### # \_\_floordiv\_\_(x1, x2, /) @@ -217,7 +219,9 @@ Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`floor_divide()`](elementwise_functions.md#floor_divide). ### # \_\_ge\_\_(x1, x2, /) @@ -241,7 +245,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `greater_equal`. + Element-wise results must equal those of the equivalent element-wise function [`greater_equal()`](elementwise_functions.md#greater_equal). ### # \_\_getitem\_\_(x, key, /) @@ -269,7 +273,7 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array in .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `greater`. + Element-wise results must equal those of the equivalent element-wise function [`greater()`](elementwise_functions.md#greater). ### # \_\_invert\_\_(x, /) @@ -287,7 +291,9 @@ Evaluates `~x_i` for each element `x_i` of an array instance `x`. - an array containing the element-wise results. -TODO: functional counterpart (bitwise_not) +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`bitwise_invert()`](elementwise_functions.md#bitwise_invert). ### # \_\_le\_\_(x1, x2, /) @@ -311,7 +317,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `less_equal`. + Element-wise results must equal those of the equivalent element-wise function [`less_equal()`](elementwise_functions.md#less_equal). ### # \_\_len\_\_(x, /) @@ -337,7 +343,9 @@ Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: functional counterpart? +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`less_equal()`](elementwise_functions.md#bitwise_left_shift). ### # \_\_lt\_\_(x1, x2, /) @@ -361,7 +369,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array in .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `less`. + Element-wise results must equal those of the equivalent element-wise function [`less()`](elementwise_functions.md#less). ### # \_\_mod\_\_(x1, x2, /) @@ -383,7 +391,9 @@ Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`remainder()`](elementwise_functions.md#remainder). ### # \_\_mul\_\_(x1, x2, /) @@ -421,7 +431,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `multiply`. + Element-wise results must equal those of the equivalent element-wise function [`multiply()`](elementwise_functions.md#multiply). ### # \_\_ne\_\_(x1, x2, /) @@ -445,7 +455,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `not_equal`. + Element-wise results must equal those of the equivalent element-wise function [`not_equal()`](elementwise_functions.md#not_equal). ### # \_\_neg\_\_(x, /) @@ -463,7 +473,9 @@ Evaluates `-x_i` for each element `x_i` of an array instance `x`. - an array containing the element-wise results. -TODO: functional counterpart? (numpy.negative) +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`negative()`](elementwise_functions.md#negative). ### # \_\_or\_\_(x1, x2, /) @@ -485,7 +497,9 @@ Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: functional counterpart? (bitwise_or) +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`positive()`](elementwise_functions.md#bitwise_or). ### # \_\_pos\_\_(x, /) @@ -503,7 +517,9 @@ Evaluates `+x_i` for each element `x_i` of an array instance `x`. - an array containing the element-wise results. -TODO: functional counterpart? (numpy.positive) +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`positive()`](elementwise_functions.md#positive). ### # \_\_pow\_\_(x1, x2, /) @@ -552,7 +568,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. + Element-wise results must equal those of the equivalent element-wise function [`pow()`](elementwise_functions.md#pow). ### # \_\_radd\_\_(x1, x2, /) @@ -598,7 +614,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `add`. + Element-wise results must equal those of the equivalent element-wise function [`add()`](elementwise_functions.md#add). ### # \_\_rand\_\_(x1, x2, /) @@ -620,7 +636,9 @@ Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: link to functional equivalent +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`bitwise_and()`](elementwise_functions.md#bitwise_and). ### # \_\_rfloordiv\_\_(x1, x2, /) @@ -642,7 +660,9 @@ Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`floor_divide()`](elementwise_functions.md#floor_divide). ### # \_\_rlshift\_\_(x1, x2, /) @@ -664,7 +684,9 @@ Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: functional counterpart? +.. note:: + + Element-wise results must equal those of the equivalent element-wise function [`bitwise_left_shift()`](elementwise_functions.md#bitwise_left_shift). ### # \_\_rmod\_\_(x1, x2, /) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index ee71ba8bb..7093ee1d7 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -1,3 +1,5 @@ +.. _element-wise-functions: + # Element-wise Functions > Array API specification for element-wise functions. From 50535e99b62389775a6cfdebd0ced902ab70ce29 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Fri, 6 Nov 2020 23:52:13 -0600 Subject: [PATCH 12/27] Update notes --- spec/API_specification/array_object.md | 84 +++++++++++-------- .../elementwise_functions.md | 2 +- 2 files changed, 49 insertions(+), 37 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 7f5d95695..030bf7755 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -103,7 +103,7 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i .. note:: - Element-wise results must equal those of the equivalent element-wise function [`abs()`](elementwise_functions.md#abs). + Element-wise results must equal the results returned by the equivalent element-wise function [`abs(x)`](elementwise_functions.md#abs). ### # \_\_add\_\_(x1, x2, /) @@ -149,7 +149,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re .. note:: - Element-wise results must equal those of the equivalent element-wise function [`add()`](elementwise_functions.md#add). + Element-wise results must equal the results returned by the equivalent element-wise function [`add(x1, x2)`](elementwise_functions.md#add). ### # \_\_and\_\_(x1, x2, /) @@ -173,7 +173,7 @@ Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results must equal those of the equivalent element-wise function [`bitwise_and()`](elementwise_functions.md#and). + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x1, x2)`](elementwise_functions.md#and). ### # \_\_eq\_\_(x1, x2, /) @@ -197,7 +197,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results must equal those of the equivalent element-wise function [`equal`](elementwise_functions.md#equal). + Element-wise results must equal the results returned by the equivalent element-wise function [`equal(x1, x2)`](elementwise_functions.md#equal). ### # \_\_floordiv\_\_(x1, x2, /) @@ -221,7 +221,7 @@ Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with .. note:: - Element-wise results must equal those of the equivalent element-wise function [`floor_divide()`](elementwise_functions.md#floor_divide). + Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x1, x2)`](elementwise_functions.md#floor_divide). ### # \_\_ge\_\_(x1, x2, /) @@ -245,7 +245,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results must equal those of the equivalent element-wise function [`greater_equal()`](elementwise_functions.md#greater_equal). + Element-wise results must equal the results returned by the equivalent element-wise function [`greater_equal(x1, x2)`](elementwise_functions.md#greater_equal). ### # \_\_getitem\_\_(x, key, /) @@ -273,7 +273,7 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array in .. note:: - Element-wise results must equal those of the equivalent element-wise function [`greater()`](elementwise_functions.md#greater). + Element-wise results must equal the results returned by the equivalent element-wise function [`greater(x1, x2)`](elementwise_functions.md#greater). ### # \_\_invert\_\_(x, /) @@ -293,7 +293,7 @@ Evaluates `~x_i` for each element `x_i` of an array instance `x`. .. note:: - Element-wise results must equal those of the equivalent element-wise function [`bitwise_invert()`](elementwise_functions.md#bitwise_invert). + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_invert(x)`](elementwise_functions.md#bitwise_invert). ### # \_\_le\_\_(x1, x2, /) @@ -317,7 +317,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results must equal those of the equivalent element-wise function [`less_equal()`](elementwise_functions.md#less_equal). + Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#less_equal). ### # \_\_len\_\_(x, /) @@ -345,7 +345,7 @@ Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with .. note:: - Element-wise results must equal those of the equivalent element-wise function [`less_equal()`](elementwise_functions.md#bitwise_left_shift). + Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#bitwise_left_shift). ### # \_\_lt\_\_(x1, x2, /) @@ -369,7 +369,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array in .. note:: - Element-wise results must equal those of the equivalent element-wise function [`less()`](elementwise_functions.md#less). + Element-wise results must equal the results returned by the equivalent element-wise function [`less(x1, x2)`](elementwise_functions.md#less). ### # \_\_mod\_\_(x1, x2, /) @@ -393,7 +393,7 @@ Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results must equal those of the equivalent element-wise function [`remainder()`](elementwise_functions.md#remainder). + Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x1, x2)`](elementwise_functions.md#remainder). ### # \_\_mul\_\_(x1, x2, /) @@ -431,7 +431,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th .. note:: - Element-wise results must equal those of the equivalent element-wise function [`multiply()`](elementwise_functions.md#multiply). + Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x1, x2)`](elementwise_functions.md#multiply). ### # \_\_ne\_\_(x1, x2, /) @@ -455,7 +455,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array i .. note:: - Element-wise results must equal those of the equivalent element-wise function [`not_equal()`](elementwise_functions.md#not_equal). + Element-wise results must equal the results returned by the equivalent element-wise function [`not_equal(x1, x2)`](elementwise_functions.md#not_equal). ### # \_\_neg\_\_(x, /) @@ -475,7 +475,7 @@ Evaluates `-x_i` for each element `x_i` of an array instance `x`. .. note:: - Element-wise results must equal those of the equivalent element-wise function [`negative()`](elementwise_functions.md#negative). + Element-wise results must equal the results returned by the equivalent element-wise function [`negative(x)`](elementwise_functions.md#negative). ### # \_\_or\_\_(x1, x2, /) @@ -499,7 +499,7 @@ Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results must equal those of the equivalent element-wise function [`positive()`](elementwise_functions.md#bitwise_or). + Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x1, x2)`](elementwise_functions.md#bitwise_or). ### # \_\_pos\_\_(x, /) @@ -519,7 +519,7 @@ Evaluates `+x_i` for each element `x_i` of an array instance `x`. .. note:: - Element-wise results must equal those of the equivalent element-wise function [`positive()`](elementwise_functions.md#positive). + Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x)`](elementwise_functions.md#positive). ### # \_\_pow\_\_(x1, x2, /) @@ -568,7 +568,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin .. note:: - Element-wise results must equal those of the equivalent element-wise function [`pow()`](elementwise_functions.md#pow). + Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x1, x2)`](elementwise_functions.md#pow). ### # \_\_radd\_\_(x1, x2, /) @@ -614,7 +614,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re .. note:: - Element-wise results must equal those of the equivalent element-wise function [`add()`](elementwise_functions.md#add). + Element-wise results must equal the results returned by the equivalent element-wise function [`add(x2, x1)`](elementwise_functions.md#add). ### # \_\_rand\_\_(x1, x2, /) @@ -638,7 +638,7 @@ Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results must equal those of the equivalent element-wise function [`bitwise_and()`](elementwise_functions.md#bitwise_and). + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x2, x1)`](elementwise_functions.md#bitwise_and). ### # \_\_rfloordiv\_\_(x1, x2, /) @@ -662,7 +662,7 @@ Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with .. note:: - Element-wise results must equal those of the equivalent element-wise function [`floor_divide()`](elementwise_functions.md#floor_divide). + Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x2, x1)`](elementwise_functions.md#floor_divide). ### # \_\_rlshift\_\_(x1, x2, /) @@ -686,7 +686,7 @@ Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with .. note:: - Element-wise results must equal those of the equivalent element-wise function [`bitwise_left_shift()`](elementwise_functions.md#bitwise_left_shift). + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_left_shift(x2, x1)`](elementwise_functions.md#bitwise_left_shift). ### # \_\_rmod\_\_(x1, x2, /) @@ -708,7 +708,9 @@ Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: an element-wise counterpart API +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x2, x1)`](elementwise_functions.md#remainder). ### # \_\_rmul\_\_(x1, x2, /) @@ -746,7 +748,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `multiply`. + Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x2, x1)`](elementwise_functions.md#multiply). ### # \_\_ror\_\_(x1, x2, /) @@ -768,7 +770,9 @@ Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: functional counterpart? (bitwise_or) +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_or(x2, x1)`](elementwise_functions.md#bitwise_or). ### # \_\_rpow\_\_(x1, x2, /) @@ -817,7 +821,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `pow`. + Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x2, x1)`](elementwise_functions#pow). ### # \_\_rrshift\_\_(x1, x2, /) @@ -839,7 +843,9 @@ Evaluates `x2_i >> x1_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: functional counterpart? +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x2, x1)`](elementwise_functions.md#bitwise_right_shift). ### # \_\_rshift\_\_(x1, x2, /) @@ -861,11 +867,13 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with - an array containing the element-wise results. -TODO: functional counterpart? +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x1, x2)`](elementwise_functions.md#bitwise_right_shift). ### # \_\_rsub\_\_(x1, x2, /) -Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` **must** be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`][#__radd__]). +Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` **must** be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`](#__radd__)). #### Parameters @@ -885,7 +893,7 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `subtract`. + Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x2, x1)`](elementwise_functions.md#subtract). ### # \_\_rtruediv\_\_(x1, x2, /) @@ -921,7 +929,7 @@ Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `divide`. + Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x2, x1)`](elementwise_functions.md#divide). ### # \_\_rxor\_\_(x1, x2, /) @@ -943,7 +951,9 @@ Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: functional counterpart? (bitwise_or) +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x2, x1)`](elementwise_functions.md#bitwise_xor). ### # \_\_setitem\_\_(x, key, value, /) @@ -955,7 +965,7 @@ TODO ### # \_\_sub\_\_(x1, x2, /) -Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` **must** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`][#__add__]). +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` **must** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`](#__add__)). #### Parameters @@ -975,7 +985,7 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `subtract`. + Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x1, x2)`](elementwise_functions.md#subtract). ### # \_\_truediv\_\_(x1, x2, /) @@ -1011,7 +1021,7 @@ Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with t .. note:: - Element-wise results should equal those of the equivalent element-wise function. TODO: link to function specification: `divide`. + Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x1, x2)`](elementwise_functions.md#divide). ### # \_\_xor\_\_(x1, x2, /) @@ -1033,4 +1043,6 @@ Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with t - an array containing the element-wise results. -TODO: functional counterpart? (bitwise_xor) \ No newline at end of file +.. note:: + + Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x1, x2)`](elementwise_functions.md#bitwise_xor). \ No newline at end of file diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index c58a16c12..5edb3226a 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -1200,7 +1200,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`. The result of `x1_i - x2_i` must **always** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add`][#add]). +Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must **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 18b1634fe02aa9d2892f8df6ba127466ab8584ea Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 7 Nov 2020 00:37:23 -0600 Subject: [PATCH 13/27] Specify output data types --- spec/API_specification/array_object.md | 168 +++++++++--------- .../elementwise_functions.md | 72 ++++---- 2 files changed, 120 insertions(+), 120 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 030bf7755..fde41009b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -73,7 +73,7 @@ Transpose of the array. - **out**: _<array>_ - - array whose dimensions (axes) are permuted in reverse order relative to original array. Must have the same data type as the original array. + - array whose dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array. * * * @@ -99,7 +99,7 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i - **out**: _<array>_ - - an array containing the element-wise absolute value. Must have the same data type as `x`. + - an array containing the element-wise absolute value. The returned array must have the same data type as `x`. .. note:: @@ -116,14 +116,14 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - 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 a finite number and `x2_i` is `+infinity`, the result is `+infinity`. +- If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. - If `x1_i` is `-0` and `x2_i` is `+0`, the result is `+0`. - If `x1_i` is `+0` and `x2_i` is `-0`, the result is `+0`. - If `x1_i` is `+0` and `x2_i` is `+0`, the result is `+0`. -- If `x1_i` is `+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 either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. - If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. - In the remaining cases, when neither an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate sign. @@ -145,7 +145,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - **out**: _<array>_ - - an array containing the element-wise sums. + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -159,17 +159,17 @@ Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -193,7 +193,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -217,7 +217,7 @@ Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. .. note:: @@ -241,7 +241,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -269,7 +269,7 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array in - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -283,13 +283,13 @@ Evaluates `~x_i` for each element `x_i` of an array instance `x`. - **x**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x`. .. note:: @@ -313,7 +313,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -331,17 +331,17 @@ Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x1`. .. note:: @@ -365,7 +365,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array in - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -389,7 +389,7 @@ Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with t - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. .. note:: @@ -404,9 +404,9 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - 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. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. - In the remaining cases, where neither an `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. .. note:: @@ -427,7 +427,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - **out**: _<array>_ - - an array containing the element-wise products. + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -451,7 +451,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). .. note:: @@ -471,7 +471,7 @@ Evaluates `-x_i` for each element `x_i` of an array instance `x`. - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -485,17 +485,17 @@ Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -515,7 +515,7 @@ Evaluates `+x_i` for each element `x_i` of an array instance `x`. - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the evaluated result for each element in `x`. The returned array must have the same data type as `x`. .. note:: @@ -564,7 +564,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -581,14 +581,14 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - 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 a finite number and `x2_i` is `+infinity`, the result is `+infinity`. +- If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. - If `x1_i` is `-0` and `x2_i` is `+0`, the result is `+0`. - If `x1_i` is `+0` and `x2_i` is `-0`, the result is `+0`. - If `x1_i` is `+0` and `x2_i` is `+0`, the result is `+0`. -- If `x1_i` is `+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 either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. - If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. - In the remaining cases, when neither an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate sign. @@ -610,7 +610,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - **out**: _<array>_ - - an array containing the element-wise sums. + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -624,17 +624,17 @@ Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -658,7 +658,7 @@ Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. .. note:: @@ -672,17 +672,17 @@ Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer data type. Each element must be greater than or equal to `0`. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x2`. .. note:: @@ -706,7 +706,7 @@ Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with t - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x1_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. .. note:: @@ -721,9 +721,9 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - 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. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. - In the remaining cases, where neither an `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. .. note:: @@ -744,7 +744,7 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th - **out**: _<array>_ - - an array containing the element-wise products. + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -758,17 +758,17 @@ Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -817,7 +817,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -831,17 +831,17 @@ Evaluates `x2_i >> x1_i` for each element `x1_i` of an array instance `x1` with - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer data type. Each element must be greater than or equal to `0`. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x2`. .. note:: @@ -855,17 +855,17 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x1`. .. note:: @@ -873,7 +873,7 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with ### # \_\_rsub\_\_(x1, x2, /) -Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` **must** be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`](#__radd__)). +Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` must be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`](#__radd__)). #### Parameters @@ -889,7 +889,7 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp - **out**: _<array>_ - - an array containing the element-wise differences. + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -900,15 +900,15 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, - 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 both `x1_i` and `x2_i` have the same sign, the result is positive. +- If `x1_i` and `x2_i` have different signs, the result is negative. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. - If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is a finite nonzero value, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x2_i` is a finite value and `x1_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. +- If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x2_i` is a finite number and `x1_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 `x2_i` is either `+0` or `-0` and `x1_i` is a finite nonzero value, the result is a signed zero with the sign determined by the rule already stated above. -- If `x2_i` is a nonzero finite value and `x1_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x2_i` is either `+0` or `-0` and `x1_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. +- If `x2_i` is a nonzero finite number and `x1_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 @@ -925,7 +925,7 @@ Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with t - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -939,17 +939,17 @@ Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -965,7 +965,7 @@ TODO ### # \_\_sub\_\_(x1, x2, /) -Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` **must** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`](#__add__)). +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`](#__add__)). #### Parameters @@ -981,7 +981,7 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with - **out**: _<array>_ - - an array containing the element-wise differences. + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -992,15 +992,15 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, - 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 both `x1_i` and `x2_i` have the same sign, the result is positive. +- If `x1_i` and `x2_i` have different signs, the result is negative. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a 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 `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. +- If `x1_i` is a finite number 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. +- If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. - In the remaining cases, where neither an `-infinity`, `+0`, `-0`, or `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate sign. #### Parameters @@ -1017,7 +1017,7 @@ Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with t - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: @@ -1031,17 +1031,17 @@ Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with t - **x1**: _<array>_ - - array instance. + - array instance. Must have an integer or boolean data type. - **x2**: _<array>_ - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 5edb3226a..430de8ecc 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -59,7 +59,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # acosh(x, /) @@ -82,7 +82,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c - **out**: _<array>_ - - an array containing the inverse hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # add(x1, x2, /) @@ -97,8 +97,8 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - 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 a finite number and `x2_i` is `+infinity`, the result is `+infinity`. +- If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. - If `x1_i` is `-0` and `x2_i` is `+0`, the result is `+0`. - If `x1_i` is `+0` and `x2_i` is `-0`, the result is `+0`. @@ -126,7 +126,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - **out**: _<array>_ - - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. ### # asin(x, /) @@ -150,7 +150,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # asinh(x, /) @@ -174,7 +174,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s - **out**: _<array>_ - - an array containing the inverse hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atan(x, /) @@ -198,7 +198,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atan2(x1, x2, /) @@ -252,7 +252,7 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f - **out**: _<array>_ - - an array containing the inverse tangent of the quotient `x1/x2`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse tangent of the quotient `x1/x2`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # atanh(x, /) @@ -278,7 +278,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t - **out**: _<array>_ - - an array containing the inverse hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the inverse hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # bitwise_and(x1, x2, /) @@ -298,7 +298,7 @@ Computes the bitwise AND of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # bitwise_left_shift(x1, x2, /) @@ -354,7 +354,7 @@ Computes the bitwise OR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # bitwise_right_shift(x1, x2, /) @@ -394,7 +394,7 @@ Computes the bitwise XOR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # ceil(x, /) @@ -438,7 +438,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai - **out**: _<array>_ - - an array containing the cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # cosh(x, /) @@ -460,7 +460,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h - **out**: _<array>_ - - an array containing the hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # divide(x1, x2, /) @@ -474,7 +474,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is finite and `x2_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. +- If `x1_i` is a finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. - If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. @@ -494,7 +494,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # equal(x1, x2, /) @@ -538,7 +538,7 @@ Calculates an implementation-dependent approximation to the exponential function - **out**: _<array>_ - - an array containing the evaluated exponential function result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated exponential function result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # expm1(x, /) @@ -566,7 +566,7 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # floor(x, /) @@ -606,7 +606,7 @@ Rounds the result of dividing each element `x1_i` of the input array `x1` by the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # greater(x1, x2, /) @@ -758,7 +758,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - **out**: _<array>_ - - an array containing the evaluated natural logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated natural logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log1p(x, /) @@ -787,7 +787,7 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log2(x, /) @@ -811,7 +811,7 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `2` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated base `2` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # log10(x, /) @@ -835,7 +835,7 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `10` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated base `10` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # logical_and(x1, x2, /) @@ -947,7 +947,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. ### # negative(x, /) @@ -963,7 +963,7 @@ Computes the numerical negative of each element `x_i` (i.e., `y_i = -x_i`) of th - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. ### # not_equal(x1, x2, /) @@ -1046,7 +1046,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. ### # remainder(x1, x2, /) @@ -1066,7 +1066,7 @@ Returns the remainder of division for each element `x1_i` of the input array `x1 - **out**: _<array>_ - - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # round(x, /) @@ -1132,7 +1132,7 @@ Calculates an implementation-dependent approximation to the sine, having domain - **out**: _<array>_ - - an array containing the sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # sinh(x, /) @@ -1156,7 +1156,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - **out**: _<array>_ - - an array containing the hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # square(x, /) @@ -1172,7 +1172,7 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion`. ### # sqrt(x, /) @@ -1196,11 +1196,11 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in - **out**: _<array>_ - - an array containing the square root of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the square root of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # subtract(x1, x2, /) -Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must **always** be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add`](#add)). +Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add`](#add)). #### Parameters @@ -1216,7 +1216,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t - **out**: _<array>_ - - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion` rules. + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. ### # tan(x, /) @@ -1239,7 +1239,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma - **out**: _<array>_ - - an array containing the tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # tanh(x, /) @@ -1263,7 +1263,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, - **out**: _<array>_ - - an array containing the hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. + - an array containing the hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. ### # trunc(x, /) From 39e8088eb24aa5331e495775a3034f9384481ebd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 7 Nov 2020 23:42:38 -0600 Subject: [PATCH 14/27] Update wording and special cases --- spec/API_specification/array_object.md | 120 +++++++++++------ .../elementwise_functions.md | 127 ++++++++++-------- 2 files changed, 149 insertions(+), 98 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index fde41009b..8d6a2b749 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -85,6 +85,8 @@ Transpose of the array. Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). +#### Special Cases + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. - If `x_i` is `-infinity`, the result is `+infinity`. @@ -109,13 +111,15 @@ Calculates the absolute value for each element `x_i` of an array instance `x` (i Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. - If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is `-infinity` and `x2_i` is `-infinity`, the result is `-infinity`. -- If `x1_i` is `+infinity` and `x2_i` is finite, 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 a finite number, the result is `+infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a finite number, the result is `-infinity`. - If `x1_i` is a finite number and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. @@ -125,7 +129,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. - If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. - If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. -- In the remaining cases, when neither an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate sign. +- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. .. note:: @@ -399,15 +403,17 @@ Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with t Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. .. note:: @@ -525,10 +531,12 @@ Evaluates `+x_i` for each element `x_i` of an array instance `x`. Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. +#### Special Cases + - If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`. - If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`. - If `x2_i` is `-0`, the result is `1`, even if `x1_i` is `NaN`. -- If `x1_i` is `NaN` and `x2_i` is nonzero, the result is `NaN`. +- If `x1_i` is `NaN` and `x2_i` is not equal to `0`, the result is `NaN`. - If `abs(x1_i)` is greater than `1` and `x2_i` is `+infinity`, the result is `+infinity`. - If `abs(x1_i)` is greater than `1` and `x2_i` is `-infinity`, the result is `+0`. - If `abs(x1_i)` is `1` and `x2_i` is `+infinity`, the result is `1`. @@ -548,7 +556,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - If `x1_i` is `-0`, `x2_i` is greater than `0`, and `x2_i` is not an odd integer value, the result is `+0`. - If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is an odd integer value, the result is `-infinity`. - If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is not an odd integer value, the result is `+infinity`. -- If `x1_i` is less than `0`, `x1_i` is finite, `x2_i` is finite, and `x2_i` is not an integer value, the result is `NaN`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, `x2_i` is a finite number, and `x2_i` is not an integer value, the result is `NaN`. #### Parameters @@ -574,13 +582,15 @@ Calculates an implementation-dependent approximation of exponentiation by raisin Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. - If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is `-infinity` and `x2_i` is `-infinity`, the result is `-infinity`. -- If `x1_i` is `+infinity` and `x2_i` is finite, 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 a finite number, the result is `+infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a finite number, the result is `-infinity`. - If `x1_i` is a finite number and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. @@ -590,7 +600,7 @@ Calculates the sum for each element `x1_i` of an array instance `x1` with the re - If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. - If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. - If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. -- In the remaining cases, when neither an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate sign. +- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. .. note:: @@ -716,15 +726,17 @@ Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with t Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. .. note:: @@ -778,10 +790,12 @@ Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with t Calculates an implementation-dependent approximation of exponentiation by raising each element `x2_i` (the base) of an array `x2` to the power of `x1_i` (the exponent), where `x1_i` is the corresponding element of the array instance `x1`. +#### Special Cases + - If `x2_i` is not equal to `1` and `x1_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+0`, the result is `1`, even if `x2_i` is `NaN`. - If `x1_i` is `-0`, the result is `1`, even if `x2_i` is `NaN`. -- If `x2_i` is `NaN` and `x1_i` is nonzero, the result is `NaN`. +- If `x2_i` is `NaN` and `x1_i` is not equal to `0`, the result is `NaN`. - If `abs(x2_i)` is greater than `1` and `x1_i` is `+infinity`, the result is `+infinity`. - If `abs(x2_i)` is greater than `1` and `x1_i` is `-infinity`, the result is `+0`. - If `abs(x2_i)` is `1` and `x1_i` is `+infinity`, the result is `1`. @@ -801,7 +815,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - If `x2_i` is `-0`, `x1_i` is greater than `0`, and `x1_i` is not an odd integer value, the result is `+0`. - If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is an odd integer value, the result is `-infinity`. - If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is not an odd integer value, the result is `+infinity`. -- If `x2_i` is less than `0`, `x2_i` is finite, `x1_i` is finite, and `x1_i` is not an integer value, the result is `NaN`. +- If `x2_i` is less than `0`, `x2_i` is a finite number, `x1_i` is a finite number, and `x1_i` is not an integer value, the result is `NaN`. #### Parameters @@ -873,7 +887,7 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with ### # \_\_rsub\_\_(x1, x2, /) -Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` must be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__`](#__radd__)). +Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` must be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__()`](#__radd__)). #### Parameters @@ -899,17 +913,30 @@ Calculates the difference for each element `x2_i` of an array `x2` with the resp Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x2_i` is either `+infinity` or `-infinity` and `x1_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x2_i` is a finite number and `x1_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 `x2_i` is either `+0` or `-0` and `x1_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. -- If `x2_i` is a nonzero finite number and `x1_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `-infinity`, `+0`, `-0`, or `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate sign. +- If `x2_i` is `+0` and `x1_i` is greater than `0`, the result is `+0`. +- If `x2_i` is `-0` and `x1_i` is greater than `0`, the result `-0`. +- If `x2_i` is `+0` and `x1_i` is less than `0`, the result is `-0`. +- If `x2_i` is `-0` and `x1_i` is less than `0`, the result is `+0`. +- If `x2_i` is greater than `0` and `x1_i` is `+0`, the result is `+infinity`. +- If `x2_i` is greater than `0` and `x1_i` is `-0`, the result is `-infinity`. +- If `x2_i` is less than `0` and `x1_i` is `+0`, the result is `-infinity`. +- If `x2_i` is less than `0` and `x1_i` is `-0`, the result is `+infinity`. +- If `x2_i` is `+infinity` and `x1_i` is a positive (i.e., greater than `0`) finite number, the result is `+infinity`. +- If `x2_i` is `+infinity` and `x1_i` is a negative (i.e., less than `0`) finite number, the result is `-infinity`. +- If `x2_i` is `-infinity` and `x1_i` is a positive (i.e., greater than `0`) finite number, the result is `-infinity`. +- If `x2_i` is `-infinity` and `x1_i` is a negative (i.e., less than `0`) finite number, the result is `+infinity`. +- If `x2_i` is a positive (i.e., greater than `0`) finite number and `x1_i` is `+infinity`, the result is `+0`. +- If `x2_i` is a positive (i.e., greater than `0`) finite number and `x1_i` is `-infinity`, the result is `-0`. +- If `x2_i` is a negative (i.e., less than `0`) finite number and `x1_i` is `+infinity`, the result is `-0`. +- If `x2_i` is a negative (i.e., less than `0`) finite number and `x1_i` is `-infinity`, the result is `+0`. +- If `x1_i` and `x2_i` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. +- In the remaining cases, where neither `-infinity`, `+0`, `-0`, nor `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. #### Parameters @@ -965,7 +992,7 @@ TODO ### # \_\_sub\_\_(x1, x2, /) -Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__`](#__add__)). +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__()`](#__add__)). #### Parameters @@ -991,17 +1018,30 @@ Calculates the difference for each element `x1_i` of an array instance `x1` with Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +#### Special Cases + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is a finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `-infinity`, `+0`, `-0`, or `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate sign. +- If `x1_i` is `+0` and `x2_i` is greater than `0`, the result is `+0`. +- If `x1_i` is `-0` and `x2_i` is greater than `0`, the result `-0`. +- If `x1_i` is `+0` and `x2_i` is less than `0`, the result is `-0`. +- If `x1_i` is `-0` and `x2_i` is less than `0`, the result is `+0`. +- If `x1_i` is greater than `0` and `x2_i` is `+0`, the result is `+infinity`. +- If `x1_i` is greater than `0` and `x2_i` is `-0`, the result is `-infinity`. +- If `x1_i` is less than `0` and `x2_i` is `+0`, the result is `-infinity`. +- If `x1_i` is less than `0` and `x2_i` is `-0`, the result is `+infinity`. +- If `x1_i` is `+infinity` and `x2_i` is a positive (i.e., greater than `0`) finite number, the result is `+infinity`. +- If `x1_i` is `+infinity` and `x2_i` is a negative (i.e., less than `0`) finite number, the result is `-infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a positive (i.e., greater than `0`) finite number, the result is `-infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a negative (i.e., less than `0`) finite number, the result is `+infinity`. +- If `x1_i` is a positive (i.e., greater than `0`) finite number and `x2_i` is `+infinity`, the result is `+0`. +- If `x1_i` is a positive (i.e., greater than `0`) finite number and `x2_i` is `-infinity`, the result is `-0`. +- If `x1_i` is a negative (i.e., less than `0`) finite number and `x2_i` is `+infinity`, the result is `-0`. +- If `x1_i` is a negative (i.e., less than `0`) finite number and `x2_i` is `-infinity`, the result is `+0`. +- If `x1_i` and `x2_i` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. +- In the remaining cases, where neither `-infinity`, `+0`, `-0`, nor `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. #### Parameters diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 430de8ecc..348f974b4 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -20,7 +20,7 @@ A conforming implementation of the array API standard must provide and support t Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. @@ -42,7 +42,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1, +1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. @@ -65,7 +65,7 @@ Calculates an implementation-dependent approximation of the principal value of t Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `1`, the result is `NaN`. @@ -88,15 +88,15 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. - If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is `-infinity` and `x2_i` is `-infinity`, the result is `-infinity`. -- If `x1_i` is `+infinity` and `x2_i` is finite, the result is `+infinity`. -- If `x1_i` is `-infinity` and `x2_i` is finite, the result is `-infinity`. +- If `x1_i` is `+infinity` and `x2_i` is a finite number, the result is `+infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a finite number, the result is `-infinity`. - If `x1_i` is a finite number and `x2_i` is `+infinity`, the result is `+infinity`. - If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. - If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. @@ -106,7 +106,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. - If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. - If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. -- In the remaining cases, when neither an `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate sign. +- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. .. note:: @@ -132,7 +132,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. @@ -156,7 +156,7 @@ Calculates an implementation-dependent approximation of the principal value of t Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -180,13 +180,13 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. -- If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded). -- If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded). +- If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2`. +- If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2`. #### Parameters @@ -204,7 +204,7 @@ Calculates an implementation-dependent approximation of the principal value of t Calculates an implementation-dependent approximation of the inverse tangent of the quotient `x1/x2`, having domain `[-infinity, +infinity] x [-infinity, +infinity]` (where the `x` notation denotes the set of ordered pairs of elements `(x1_i, x2_i)`) and codomain `[-π, +π]`, for each pair of elements `(x1_i, x2_i)` of the input arrays `x1` and `x2`, respectively. Each element-wise result is expressed in radians. -The signs of `x1_i` and `x2_i` determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise result is the signed angle in radians between the ray ending at the origin and passing through the point `(1,0)` and the ray ending at the origin and passing through the point `(x2_i, x1_i)`. +The mathematical signs of `x1_i` and `x2_i` determine the quadrant of each element-wise result. The quadrant (i.e., branch) is chosen such that each element-wise result is the signed angle in radians between the ray ending at the origin and passing through the point `(1,0)` and the ray ending at the origin and passing through the point `(x2_i, x1_i)`. .. note:: @@ -212,7 +212,7 @@ The signs of `x1_i` and `x2_i` determine the quadrant of each element-wise resul By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined for `x2_i` equal to positive or negative zero and for either or both of `x1_i` and `x2_i` equal to positive or negative `infinity`. -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is greater than `0` and `x2_i` is `+0`, the result is an implementation-dependent approximation to `+π/2`. @@ -227,10 +227,10 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f - If `x1_i` is `-0` and `x2_i` is less than `0`, the result is an implementation-dependent approximation to `-π`. - If `x1_i` is less than `0` and `x2_i` is `+0`, the result is an implementation-dependent approximation to `-π/2`. - If `x1_i` is less than `0` and `x2_i` is `-0`, the result is an implementation-dependent approximation to `-π/2`. -- If `x1_i` is greater than `0`, `x1_i` is finite, and `x2_i` is `+infinity`, the result is `+0`. -- If `x1_i` is greater than `0`, `x1_i` is finite, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `+π`. -- If `x1_i` is less than `0`, `x1_i` is finite, and `x2_i` is `+infinity`, the result is `-0`. -- If `x1_i` is less than `0`, `x1_i` is finite, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `-π`. +- If `x1_i` is greater than `0`, `x1_i` is a finite number, and `x2_i` is `+infinity`, the result is `+0`. +- If `x1_i` is greater than `0`, `x1_i` is a finite number, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `+π`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, and `x2_i` is `+infinity`, the result is `-0`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, and `x2_i` is `-infinity`, the result is an implementation-dependent approximation to `-π`. - If `x1_i` is `+infinity` and `x2_i` is finite, the result is an implementation-dependent approximation to `+π/2`. - If `x1_i` is `-infinity` and `x2_i` is finite, the result is an implementation-dependent approximation to `-π/2`. - If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/4`. @@ -258,7 +258,7 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -400,7 +400,7 @@ Computes the bitwise XOR of the underlying binary representation of each element Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. @@ -420,7 +420,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. @@ -466,19 +466,30 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is a finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed zero with the sign determined by the rule already stated above. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is a signed zero with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `-infinity`, `+0`, `-0`, or `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate sign. +- If `x1_i` is `+0` and `x2_i` is greater than `0`, the result is `+0`. +- If `x1_i` is `-0` and `x2_i` is greater than `0`, the result `-0`. +- If `x1_i` is `+0` and `x2_i` is less than `0`, the result is `-0`. +- If `x1_i` is `-0` and `x2_i` is less than `0`, the result is `+0`. +- If `x1_i` is greater than `0` and `x2_i` is `+0`, the result is `+infinity`. +- If `x1_i` is greater than `0` and `x2_i` is `-0`, the result is `-infinity`. +- If `x1_i` is less than `0` and `x2_i` is `+0`, the result is `-infinity`. +- If `x1_i` is less than `0` and `x2_i` is `-0`, the result is `+infinity`. +- If `x1_i` is `+infinity` and `x2_i` is a positive (i.e., greater than `0`) finite number, the result is `+infinity`. +- If `x1_i` is `+infinity` and `x2_i` is a negative (i.e., less than `0`) finite number, the result is `-infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a positive (i.e., greater than `0`) finite number, the result is `-infinity`. +- If `x1_i` is `-infinity` and `x2_i` is a negative (i.e., less than `0`) finite number, the result is `+infinity`. +- If `x1_i` is a positive (i.e., greater than `0`) finite number and `x2_i` is `+infinity`, the result is `+0`. +- If `x1_i` is a positive (i.e., greater than `0`) finite number and `x2_i` is `-infinity`, the result is `-0`. +- If `x1_i` is a negative (i.e., less than `0`) finite number and `x2_i` is `+infinity`, the result is `-0`. +- If `x1_i` is a negative (i.e., less than `0`) finite number and `x2_i` is `-infinity`, the result is `+0`. +- If `x1_i` and `x2_i` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. +- In the remaining cases, where neither `-infinity`, `+0`, `-0`, nor `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. #### Parameters @@ -520,7 +531,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. @@ -546,9 +557,9 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai .. note:: - The purpose of this API is to calculate `exp(x)-1.0` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this API as simply `exp(x)-1.0`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate `exp(x)-1.0` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `exp(x)-1.0`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -572,7 +583,7 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. @@ -740,7 +751,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -766,9 +777,9 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` .. note:: - The purpose of this API is to calculate `log(1+x)` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this API as simply `log(1+x)`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate `log(1+x)` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply `log(1+x)`. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -793,7 +804,7 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` Calculates an implementation-dependent approximation to the base `2` logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -817,7 +828,7 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, Calculates an implementation-dependent approximation to the base `10` logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -917,17 +928,17 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, -#### Special Values +#### Special Cases - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If both `x1_i` and `x2_i` have the same sign, the result is positive. -- If `x1_i` and `x2_i` have different signs, the result is negative. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the sign determined by the rule already stated above. -- In the remaining cases, where neither an `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate sign. If the magnitude is too small to represent, the result is a zero of appropriate sign. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. +- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. .. note:: @@ -1005,12 +1016,12 @@ Computes the numerical positive of each element `x_i` (i.e., `y_i = +x_i`) of th Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of the input array `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the input array `x2`. -#### Special Values +#### Special Cases - If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`. - If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`. - If `x2_i` is `-0`, the result is `1`, even if `x1_i` is `NaN`. -- If `x1_i` is `NaN` and `x2_i` is nonzero, the result is `NaN`. +- If `x1_i` is `NaN` and `x2_i` is not equal to `0`, the result is `NaN`. - If `abs(x1_i)` is greater than `1` and `x2_i` is `+infinity`, the result is `+infinity`. - If `abs(x1_i)` is greater than `1` and `x2_i` is `-infinity`, the result is `+0`. - If `abs(x1_i)` is `1` and `x2_i` is `+infinity`, the result is `1`. @@ -1030,7 +1041,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - If `x1_i` is `-0`, `x2_i` is greater than `0`, and `x2_i` is not an odd integer value, the result is `+0`. - If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is an odd integer value, the result is `-infinity`. - If `x1_i` is `-0`, `x2_i` is less than `0`, and `x2_i` is not an odd integer value, the result is `+infinity`. -- If `x1_i` is less than `0`, `x1_i` is finite, `x2_i` is finite, and `x2_i` is not an integer value, the result is `NaN`. +- If `x1_i` is less than `0`, `x1_i` is a finite number, `x2_i` is a finite number, and `x2_i` is not an integer value, the result is `NaN`. #### Parameters @@ -1072,7 +1083,7 @@ Returns the remainder of division for each element `x1_i` of the input array `x1 Rounds each element `x_i` of the input array `x` to the nearest integer-valued number. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. - If two integers are equally close to `x_i`, the result is whichever integer is farthest from `0`. @@ -1093,7 +1104,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n Returns an indication of the sign of a number for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is less than `0`, the result is `-1`. - If `x_i` is either `-0` or `+0`, the result is `0`. @@ -1115,7 +1126,7 @@ Returns an indication of the sign of a number for each element `x_i` of the inpu Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1138,7 +1149,7 @@ Calculates an implementation-dependent approximation to the sine, having domain Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1178,7 +1189,7 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754). -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. @@ -1200,7 +1211,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`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add`](#add)). +Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add()`](#add)). #### Parameters @@ -1222,7 +1233,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1245,7 +1256,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. -#### Special Values +#### Special Cases - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1269,7 +1280,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`. -#### Special Values +#### Special Cases - If `x_i` is already integer-valued, the result is `x_i`. From 07b6f7a987cf1e8336e9ebe25a7577206211c58c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 7 Nov 2020 23:52:35 -0600 Subject: [PATCH 15/27] Add TODOs --- spec/API_specification/array_object.md | 40 ++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 8d6a2b749..b44841603 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -375,6 +375,26 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array in Element-wise results must equal the results returned by the equivalent element-wise function [`less(x1, x2)`](elementwise_functions.md#less). +### # \_\_matmul\_\_(x1, x2, /) + +_TODO: awaiting `matmul` functional equivalent._ + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - _TODO_ + ### # \_\_mod\_\_(x1, x2, /) Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. @@ -698,6 +718,26 @@ Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_left_shift(x2, x1)`](elementwise_functions.md#bitwise_left_shift). +### # \_\_rmatmul\_\_(x1, x2, /) + +_TODO: awaiting `matmul` functional equivalent._ + +#### Parameters + +- **x1**: _<array>_ + + - array instance. + +- **x2**: _<array>_ + + - other array. Must be compatible with `x1` (see :ref:`broadcasting`). + +#### Returns + +- **out**: _<array>_ + + - _TODO_ + ### # \_\_rmod\_\_(x1, x2, /) Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. From 12ae38310ee139c2157349f40bf7bfb9c10c76c7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 00:32:31 -0600 Subject: [PATCH 16/27] Add operator mapping --- spec/API_specification/array_object.md | 128 +++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b44841603..0958b15ca 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -15,6 +15,134 @@ A conforming implementation of the array API standard must provide and support a * * * +## Operators + +A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators: + +- `x1 < x2`: [`__lt__(x1, x2)`](#__lt__) + + - [`operator.lt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lt) + - [`operator.__lt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lt__) + +- `x1 <= x2`: [`__le__(x1, x2)`](#__le__) + + - [`operator.le(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.le) + - [`operator.__le__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__le__) + +- `x1 > x2`: [`__gt__(x1, x2)`](#__gt__) + + - [`operator.gt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.gt) + - `operator.__gt__(x1, x2)` + +- `x1 >= x2`: [`__ge__(x1, x2)`](#__ge__) + + - `operator.ge(x1, x2)` + - `operator.__ge__(x1, x2)` + +- `x1 == x2`: [`__eq__(x1, x2)`](#__eq__) + + - [`operator.eq(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.eq) + - [`operator.__eq__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__eq__) + +- `x1 != x2`: [`__ne__(x1, x2)`](#__ne__) + + - [`operator.ne(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ne) + - [`operator.__ne__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ne__) + +- `+x`: [`__pos__(x)`](#__pos__) + + - [`operator.pos(x)`](https://docs.python.org/3/library/operator.html#operator.pos) + - [`operator.__pos__(x)`](https://docs.python.org/3/library/operator.html#operator.__pos__) + +- `-x`: [`__neg__(x)`](#__neg__) + + - [`operator.neg(x)`](https://docs.python.org/3/library/operator.html#operator.neg) + - [`operator.__neg__(x)`](https://docs.python.org/3/library/operator.html#operator.__neg__) + +- `x1 + x2`: [`__add__(x1, x2)`](#__add__) + + - [`operator.add(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.add) + - [`operator.__add__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__add__) + +- `x1 - x2`: [`__sub__(x1, x2)`](#__sub__) + + - [`operator.sub(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.sub) + - [`operator.__sub__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__sub__) + +- `x1 * x2`: [`__mul__(x1, x2)`](#__mul__) + + - [`operator.mul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mul) + - [`operator.__mul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mul__) + +- `x1 / x2`: [`__truediv__(x1, x2)`](#__truediv__) + + - [`operator.truediv(x1,x2)`](https://docs.python.org/3/library/operator.html#operator.truediv) + - [`operator.__truediv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__truediv__) + +- `x1 // x2`: [`__floordiv__(x1, x2)`](#__floordiv__) + + - [`operator.floordiv(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.floordiv) + - [`operator.__floordiv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__floordiv__) + +- `x1 % x2`: [`__mod__(x1, x2)`](#__mod__) + + - [`operator.mod(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mod) + - [`operator.__mod__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mod__) + +- `x1 ** x2`: [`__pow__(x1, x2)`](#__pow__) + + - [`operator.pow(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.pow) + - [`operator.__pow__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__pow__) + +- `x1 @ x2`: [`__matmul__(x1, x2)`](#__matmul__) + + - [`operator.matmul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.matmul) + - [`operator.__matmul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__matmul__) + +- `~x`: [`__invert(x)`](#__invert__) + + - [`operator.inv(x)`](https://docs.python.org/3/library/operator.html#operator.inv) + - [`operator.invert(x)`](https://docs.python.org/3/library/operator.html#operator.invert) + - [`operator.__inv__(x)`](https://docs.python.org/3/library/operator.html#operator.__inv__) + - [`operator.__invert__(x)`](https://docs.python.org/3/library/operator.html#operator.__invert__) + +- `x1 & x2`: [`__and__(x1, x2)`](#__and__) + + - [`operator.and(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.and) + - [`operator.__and__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__and__) + +- `x1 | x2`: [`__or__(x1, x2)`](#__or__) + + - [`operator.or(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.or) + - [`operator.__or__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__or__) + +- `x1 ^ x2`: [`__xor__(x1, x2)`](#__xor__) + + - [`operator.xor(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.xor) + - [`operator.__xor__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__xor__) + +- `x1 << x2`: [`__lshift__(x1, x2)`](#__lshift__) + + - [`operator.lshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lshift) + - [`operator.__lshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lshift__) + +- `x1 >> x2`: [`__rshift__(x1, x2)`](#__rshift__) + + - [`operator.rshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.rshift) + - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) + +- `abs`: [`__abs__(x)`](#__abs__) + + - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) + - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) + +- `x[key]`: [`__getitem__(x, key)`](#__getitem__) + + - [`operator.getitem(x, key)`](https://docs.python.org/3/library/operator.html#operator.getitem) + - [`operator.__getitem__(x, key)`](https://docs.python.org/3/library/operator.html#operator.__getitem__) + +* * * + ## Attributes From d2ab96151b5a073ca7c8443478c6e3651a657ad0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 00:34:17 -0600 Subject: [PATCH 17/27] Fix links and typos --- spec/API_specification/array_object.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 0958b15ca..9efd123d8 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -32,12 +32,12 @@ A conforming implementation of the array API standard must provide and support a - `x1 > x2`: [`__gt__(x1, x2)`](#__gt__) - [`operator.gt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.gt) - - `operator.__gt__(x1, x2)` + - [`operator.__gt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__gt__) - `x1 >= x2`: [`__ge__(x1, x2)`](#__ge__) - - `operator.ge(x1, x2)` - - `operator.__ge__(x1, x2)` + - [`operator.ge(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ge) + - [`operator.__ge__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ge__) - `x1 == x2`: [`__eq__(x1, x2)`](#__eq__) @@ -99,7 +99,7 @@ A conforming implementation of the array API standard must provide and support a - [`operator.matmul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.matmul) - [`operator.__matmul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__matmul__) -- `~x`: [`__invert(x)`](#__invert__) +- `~x`: [`__invert__(x)`](#__invert__) - [`operator.inv(x)`](https://docs.python.org/3/library/operator.html#operator.inv) - [`operator.invert(x)`](https://docs.python.org/3/library/operator.html#operator.invert) From 756dc5017dff605f5713ba92ec48fe9d55fcbc48 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 02:23:09 -0600 Subject: [PATCH 18/27] Remove dunder method --- spec/API_specification/array_object.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 9efd123d8..b8cafc56c 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -381,7 +381,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array i ### # \_\_getitem\_\_(x, key, /) -TODO +_TODO: dependent on the indexing specification._ ### # \_\_gt\_\_(x1, x2, /) @@ -1152,11 +1152,7 @@ Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with t ### # \_\_setitem\_\_(x, key, value, /) -TODO - -### # \_\_sizeof\_\_(x, /) - -TODO +_TODO: dependent on the indexing specification._ ### # \_\_sub\_\_(x1, x2, /) From e4d241ad2eccc07c33e03f1e68ca8581d657f7ba Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 02:25:07 -0600 Subject: [PATCH 19/27] Update TODO --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b8cafc56c..a38c98dc0 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -453,7 +453,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array i ### # \_\_len\_\_(x, /) -TODO +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ ### # \_\_lshift\_\_(x1, x2, /) From 886bd4ce6a8aab6c82e216e8e6e0303fbdc78b8b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 02:31:40 -0600 Subject: [PATCH 20/27] Update item --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index a38c98dc0..121b3547b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -131,7 +131,7 @@ A conforming implementation of the array API standard must provide and support a - [`operator.rshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.rshift) - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) -- `abs`: [`__abs__(x)`](#__abs__) +- `abs(x)`: [`__abs__(x)`](#__abs__) - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) From a2245e1b933e8c1703fc98f13cd7feceedcc4870 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 12:42:22 +0000 Subject: [PATCH 21/27] Delete getitem from the list of operators Rationale: it's arguably not an operator, and the asymmetry with the missing getitem is potentially confusing. --- spec/API_specification/array_object.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 121b3547b..b3d4532e6 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -136,11 +136,6 @@ A conforming implementation of the array API standard must provide and support a - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) -- `x[key]`: [`__getitem__(x, key)`](#__getitem__) - - - [`operator.getitem(x, key)`](https://docs.python.org/3/library/operator.html#operator.getitem) - - [`operator.__getitem__(x, key)`](https://docs.python.org/3/library/operator.html#operator.__getitem__) - * * * ## Attributes From 6efce0d8c2c73f4d5198e0a2aed1cf6a81c1015a Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 12:43:30 +0000 Subject: [PATCH 22/27] Fix a small issue with return type of floordiv --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b3d4532e6..4b2a60d38 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -344,7 +344,7 @@ Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. .. note:: From 1660480e09bc14fb2a188e68b361b08a8416f96b Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 13:09:22 +0000 Subject: [PATCH 23/27] Add section for in-place operators --- spec/API_specification/array_object.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 4b2a60d38..0058768bb 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -136,6 +136,17 @@ A conforming implementation of the array API standard must provide and support a - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) +### In-place operators + +As discussed in :ref:`copyview-mutability`, in-place operators need to be +supported. The following operators must be supported: + +- `+=`, implemented via `__iadd__`. +- `-=`, implemented via `__isub__`. +- `*=`, implemented via `__imul__`. +- `/=`, implemented via `__idiv__`. + + * * * ## Attributes From a99ddb20741d929e5864d5d23b5282a3a3b4b47f Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 13:34:01 +0000 Subject: [PATCH 24/27] Add section on right-hand dunder methods Remove section with details on it. --- spec/API_specification/array_object.md | 422 ++----------------------- 1 file changed, 22 insertions(+), 400 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 0058768bb..b473c90e3 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -136,6 +136,7 @@ A conforming implementation of the array API standard must provide and support a - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) + ### In-place operators As discussed in :ref:`copyview-mutability`, in-place operators need to be @@ -147,6 +148,27 @@ supported. The following operators must be supported: - `/=`, implemented via `__idiv__`. +### Right-hand side dunder methods + +All supported operators for which `array scalar` is implemented also need a right-hand +size dunder method. The following methods must be supported: + +- `__radd__` +- `__rsub__` +- `__rmul__` +- `__rdiv__` +- `__rfloordiv__` +- `__rtruediv__` +- `__rpow__` +- `__rmod__` +- `__rand__` +- `__ror__` +- `__rxor__` +- `__rlshift__` +- `__rrshift__` + +For the expected numerical behaviour, see their left-hand equivalents. + * * * ## Attributes @@ -732,309 +754,6 @@ Calculates an implementation-dependent approximation of exponentiation by raisin Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x1, x2)`](elementwise_functions.md#pow). -### # \_\_radd\_\_(x1, x2, /) - -Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, - -#### Special Cases - -- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. -- If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. -- If `x1_i` is `+infinity` and `x2_i` is `+infinity`, the result is `+infinity`. -- If `x1_i` is `-infinity` and `x2_i` is `-infinity`, the result is `-infinity`. -- If `x1_i` is `+infinity` and `x2_i` is a finite number, the result is `+infinity`. -- If `x1_i` is `-infinity` and `x2_i` is a finite number, the result is `-infinity`. -- If `x1_i` is a finite number and `x2_i` is `+infinity`, the result is `+infinity`. -- If `x1_i` is a finite number and `x2_i` is `-infinity`, the result is `-infinity`. -- If `x1_i` is `-0` and `x2_i` is `-0`, the result is `-0`. -- If `x1_i` is `-0` and `x2_i` is `+0`, the result is `+0`. -- If `x1_i` is `+0` and `x2_i` is `-0`, the result is `+0`. -- If `x1_i` is `+0` and `x2_i` is `+0`, the result is `+0`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is a nonzero finite number, the result is `x2_i`. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+0` or `-0`, the result is `x1_i`. -- If `x1_i` is a nonzero finite number and `x2_i` is `-x1_i`, the result is `+0`. -- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. - -.. note:: - - Floating-point addition is a commutative operation, but not always associative. - -#### Parameters - -- **x1**: _<array>_ - - - array instance (addend array). - -- **x2**: _<array>_ - - - augend array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`add(x2, x1)`](elementwise_functions.md#add). - -### # \_\_rand\_\_(x1, x2, /) - -Evaluates `x2_i & x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. Must have an integer or boolean data type. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x2, x1)`](elementwise_functions.md#bitwise_and). - -### # \_\_rfloordiv\_\_(x1, x2, /) - -Evaluates `x2_i // x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x2, x1)`](elementwise_functions.md#floor_divide). - -### # \_\_rlshift\_\_(x1, x2, /) - -Evaluates `x2_i << x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. Must have an integer data type. Each element must be greater than or equal to `0`. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have the same data type as `x2`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_left_shift(x2, x1)`](elementwise_functions.md#bitwise_left_shift). - -### # \_\_rmatmul\_\_(x1, x2, /) - -_TODO: awaiting `matmul` functional equivalent._ - -#### Parameters - -- **x1**: _<array>_ - - - array instance. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - _TODO_ - -### # \_\_rmod\_\_(x1, x2, /) - -Evaluates `x2_i % x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x1_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x2, x1)`](elementwise_functions.md#remainder). - -### # \_\_rmul\_\_(x1, x2, /) - -Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, - -#### Special Cases - -- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. -- If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. -- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. - -.. note:: - - Floating-point multiplication is not always associative due to finite precision. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x2, x1)`](elementwise_functions.md#multiply). - -### # \_\_ror\_\_(x1, x2, /) - -Evaluates `x2_i | x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. Must have an integer or boolean data type. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_or(x2, x1)`](elementwise_functions.md#bitwise_or). - -### # \_\_rpow\_\_(x1, x2, /) - -Calculates an implementation-dependent approximation of exponentiation by raising each element `x2_i` (the base) of an array `x2` to the power of `x1_i` (the exponent), where `x1_i` is the corresponding element of the array instance `x1`. - -#### Special Cases - -- If `x2_i` is not equal to `1` and `x1_i` is `NaN`, the result is `NaN`. -- If `x1_i` is `+0`, the result is `1`, even if `x2_i` is `NaN`. -- If `x1_i` is `-0`, the result is `1`, even if `x2_i` is `NaN`. -- If `x2_i` is `NaN` and `x1_i` is not equal to `0`, the result is `NaN`. -- If `abs(x2_i)` is greater than `1` and `x1_i` is `+infinity`, the result is `+infinity`. -- If `abs(x2_i)` is greater than `1` and `x1_i` is `-infinity`, the result is `+0`. -- If `abs(x2_i)` is `1` and `x1_i` is `+infinity`, the result is `1`. -- If `abs(x2_i)` is `1` and `x1_i` is `-infinity`, the result is `1`. -- If `x2_i` is `1` and `x1_i` is not `NaN`, the result is `1`. -- If `abs(x2_i)` is less than `1` and `x1_i` is `+infinity`, the result is `+0`. -- If `abs(x2_i)` is less than `1` and `x1_i` is `-infinity`, the result is `+infinity`. -- If `x2_i` is `+infinity` and `x1_i` is greater than `0`, the result is `+infinity`. -- If `x2_i` is `+infinity` and `x1_i` is less than `0`, the result is `+0`. -- If `x2_i` is `-infinity` and `x1_i` is greater than `0`, the result is `-infinity`. -- If `x2_i` is `-infinity`, `x1_i` is greater than `0`, and `x1_i` is not an odd integer value, the result is `+infinity`. -- If `x2_i` is `-infinity`, `x1_i` is less than `0`, and `x1_i` is an odd integer value, the result is `-0`. -- If `x2_i` is `-infinity`, `x1_i` is less than `0`, and `x1_i` is not an odd integer value, the result is `+0`. -- If `x2_i` is `+0` and `x1_i` is greater than `0`, the result is `+0`. -- If `x2_i` is `+0` and `x1_i` is less than `0`, the result is `+infinity`. -- If `x2_i` is `-0`, `x1_i` is greater than `0`, and `x1_i` is an odd integer value, the result is `-0`. -- If `x2_i` is `-0`, `x1_i` is greater than `0`, and `x1_i` is not an odd integer value, the result is `+0`. -- If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is an odd integer value, the result is `-infinity`. -- If `x2_i` is `-0`, `x1_i` is less than `0`, and `x1_i` is not an odd integer value, the result is `+infinity`. -- If `x2_i` is less than `0`, `x2_i` is a finite number, `x1_i` is a finite number, and `x1_i` is not an integer value, the result is `NaN`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance whose elements correspond to the exponentiation exponent. - -- **x2**: _<array>_ - - - other array whose elements correspond to the exponentiation base. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x2, x1)`](elementwise_functions#pow). - -### # \_\_rrshift\_\_(x1, x2, /) - -Evaluates `x2_i >> x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. Must have an integer data type. Each element must be greater than or equal to `0`. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have the same data type as `x2`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x2, x1)`](elementwise_functions.md#bitwise_right_shift). - ### # \_\_rshift\_\_(x1, x2, /) Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. @@ -1059,103 +778,6 @@ Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x1, x2)`](elementwise_functions.md#bitwise_right_shift). -### # \_\_rsub\_\_(x1, x2, /) - -Calculates the difference for each element `x2_i` of an array `x2` with the respective element `x1_i` of the array instance `x1`. The result of `x2_i - x1_i` must be the same as `x2_i + (-x1_i)` and is thus governed by the same floating-point rules as addition (see [`__radd__()`](#__radd__)). - -#### Parameters - -- **x1**: _<array>_ - - - array instance (subtrahend array). - -- **x2**: _<array>_ - - - minuend array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x2, x1)`](elementwise_functions.md#subtract). - -### # \_\_rtruediv\_\_(x1, x2, /) - -Evaluates `x2_i / x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, - -#### Special Cases - -- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. -- If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. -- If `x2_i` is `+0` and `x1_i` is greater than `0`, the result is `+0`. -- If `x2_i` is `-0` and `x1_i` is greater than `0`, the result `-0`. -- If `x2_i` is `+0` and `x1_i` is less than `0`, the result is `-0`. -- If `x2_i` is `-0` and `x1_i` is less than `0`, the result is `+0`. -- If `x2_i` is greater than `0` and `x1_i` is `+0`, the result is `+infinity`. -- If `x2_i` is greater than `0` and `x1_i` is `-0`, the result is `-infinity`. -- If `x2_i` is less than `0` and `x1_i` is `+0`, the result is `-infinity`. -- If `x2_i` is less than `0` and `x1_i` is `-0`, the result is `+infinity`. -- If `x2_i` is `+infinity` and `x1_i` is a positive (i.e., greater than `0`) finite number, the result is `+infinity`. -- If `x2_i` is `+infinity` and `x1_i` is a negative (i.e., less than `0`) finite number, the result is `-infinity`. -- If `x2_i` is `-infinity` and `x1_i` is a positive (i.e., greater than `0`) finite number, the result is `-infinity`. -- If `x2_i` is `-infinity` and `x1_i` is a negative (i.e., less than `0`) finite number, the result is `+infinity`. -- If `x2_i` is a positive (i.e., greater than `0`) finite number and `x1_i` is `+infinity`, the result is `+0`. -- If `x2_i` is a positive (i.e., greater than `0`) finite number and `x1_i` is `-infinity`, the result is `-0`. -- If `x2_i` is a negative (i.e., less than `0`) finite number and `x1_i` is `+infinity`, the result is `-0`. -- If `x2_i` is a negative (i.e., less than `0`) finite number and `x1_i` is `-infinity`, the result is `+0`. -- If `x1_i` and `x2_i` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. -- In the remaining cases, where neither `-infinity`, `+0`, `-0`, nor `NaN` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too larger to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. - -#### Parameters - -- **x1**: _<array>_ - - - array instance (divisor). - -- **x2**: _<array>_ - - - dividend array. Must be compatible with `x1` (see :ref:`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x2, x1)`](elementwise_functions.md#divide). - -### # \_\_rxor\_\_(x1, x2, /) - -Evaluates `x2_i ^ x1_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. - -#### Parameters - -- **x1**: _<array>_ - - - array instance. Must have an integer or boolean data type. - -- **x2**: _<array>_ - - - other array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. - -#### Returns - -- **out**: _<array>_ - - - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. - -.. note:: - - Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x2, x1)`](elementwise_functions.md#bitwise_xor). - ### # \_\_setitem\_\_(x, key, value, /) _TODO: dependent on the indexing specification._ From 989ff306f79c5c4b88b1e7b8828a4d43605b3ed7 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 13:48:47 +0000 Subject: [PATCH 25/27] Add other inplace operators, for consistency Most do exist in all/most libs, and this makes sense and should be easy to add if missing (e.g. numpy misses `__imatmul__`). --- spec/API_specification/array_object.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b473c90e3..a2bab1339 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -146,6 +146,15 @@ supported. The following operators must be supported: - `-=`, implemented via `__isub__`. - `*=`, implemented via `__imul__`. - `/=`, implemented via `__idiv__`. +- `//=`, implemented via `__ifloordiv__`. +- `**=`, implemented via `__ipow__`. +- `@=`, implemented via `__imatmul__`. +- `%=`, implemented via `__imod__`. +- `&=`, implemented via `__iand__`. +- `|=`, implemented via `__ior__`. +- `^=`, implemented via `__ixor__`. +- `<<=`, implemented via `__ilshift__`. +- `>>=`, implemented via `__irshift__`. ### Right-hand side dunder methods From 315faef88f5f5f0f2a4a03dbbb3cdae87a4b80d7 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 21:18:32 +0000 Subject: [PATCH 26/27] Remove `abs` from table near top of array object specification `abs` isn't an operator, and it was the only non-operator left in the top-level table in this file. Related: `len(array)` is bad form, and it's not clear what is desired here. Raising an exception may make sense, but that's not what some current libraries do. `abs(array)` also isn't all that great, but seems implemented all around and is well-defined. --- spec/API_specification/array_object.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index a2bab1339..3a3532297 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -131,11 +131,6 @@ A conforming implementation of the array API standard must provide and support a - [`operator.rshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.rshift) - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) -- `abs(x)`: [`__abs__(x)`](#__abs__) - - - [`operator.abs(x)`](https://docs.python.org/3/library/operator.html#operator.abs) - - [`operator.__abs__(x)`](https://docs.python.org/3/library/operator.html#operator.__abs__) - ### In-place operators From 31e73ea6aaf34dc1870aae627fcea1d2efe6bb54 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 9 Nov 2020 21:30:54 +0000 Subject: [PATCH 27/27] Update inplace operator section --- spec/API_specification/array_object.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 3a3532297..ee8b21833 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -137,19 +137,19 @@ A conforming implementation of the array API standard must provide and support a As discussed in :ref:`copyview-mutability`, in-place operators need to be supported. The following operators must be supported: -- `+=`, implemented via `__iadd__`. -- `-=`, implemented via `__isub__`. -- `*=`, implemented via `__imul__`. -- `/=`, implemented via `__idiv__`. -- `//=`, implemented via `__ifloordiv__`. -- `**=`, implemented via `__ipow__`. -- `@=`, implemented via `__imatmul__`. -- `%=`, implemented via `__imod__`. -- `&=`, implemented via `__iand__`. -- `|=`, implemented via `__ior__`. -- `^=`, implemented via `__ixor__`. -- `<<=`, implemented via `__ilshift__`. -- `>>=`, implemented via `__irshift__`. +- `+=`. May be (but does not have to be) implemented via `__iadd__`. +- `-=`. May be (but does not have to be) implemented via `__isub__`. +- `*=`. May be (but does not have to be) implemented via `__imul__`. +- `/=`. May be (but does not have to be) implemented via `__idiv__`. +- `//=`. May be (but does not have to be) implemented via `__ifloordiv__`. +- `**=`. May be (but does not have to be) implemented via `__ipow__`. +- `@=`. May be (but does not have to be) implemented via `__imatmul__`. +- `%=`. May be (but does not have to be) implemented via `__imod__`. +- `&=`. May be (but does not have to be) implemented via `__iand__`. +- `|=`. May be (but does not have to be) implemented via `__ior__`. +- `^=`. May be (but does not have to be) implemented via `__ixor__`. +- `<<=`. May be (but does not have to be) implemented via `__ilshift__`. +- `>>=`. May be (but does not have to be) implemented via `__irshift__`. ### Right-hand side dunder methods