From 7e7aea6c999ee924eb4c25dbf828ba0a7074515c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 9 Mar 2022 17:21:26 -0800 Subject: [PATCH 1/7] Specify special cases for floating-point operands --- .../signatures/elementwise_functions.py | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index 0abb852d1..8fa2f1699 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -638,7 +638,7 @@ def floor_divide(x1: array, x2: array, /) -> array: - 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 greatest (i.e., closest to `+infinity`) representable integer-value number that is not greater than the division result. If the magnitude is too large 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. + - In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient must be computed and rounded to the greatest (i.e., closest to `+infinity`) representable integer-value number that is not greater than the division result. If the magnitude is too large 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 ---------- @@ -1112,9 +1112,40 @@ def remainder(x1: array, x2: array, /) -> array: """ Returns the remainder of division for each element ``x1_i`` of the input array ``x1`` and the respective element ``x2_i`` of the input array ``x2``. + .. note:: + This function is equivalent to the Python modulus operator ``x1_i % x2_i`` and is complementary to the :func:`~signatures.elementwise_functions.floor_divide`. + .. note:: For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined. + **Special Cases** + + .. note:: + In general, similar to Python's ``%`` operator, this function is **not** recommended for floating-point operands as semantics do not follow IEEE 754. That this function is specified to accept floating-point operands is primarily for reasons of backward compatibility. + + For floating-points operands, + + - If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``. + - If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``. + - If ``x1_i`` is either ``+0`` or ``-0`` and ``x2_i`` is either ``+0`` or ``-0``, the result is ``NaN``. + - If ``x1_i`` is ``+0`` and ``x2_i`` is greater than ``0``, the result is ``+0``. + - If ``x1_i`` is ``-0`` and ``x2_i`` is greater than ``0``, the result is ``+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 ``NaN``. + - If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``. + - If ``x1_i`` is less than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``. + - If ``x1_i`` is less than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``. + - If ``x1_i`` is ``+infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``+infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``-infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``-infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) + - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x2_i``. (**note**: this result matches Python behavior.) + - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.) + - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) + - In the remaining cases, the result must match that of the Python ``%`` operator. + Parameters ---------- x1: array @@ -1206,6 +1237,7 @@ def sinh(x: array, /) -> array: 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 cases** + For floating-point operands, - If ``x_i`` is ``NaN``, the result is ``NaN``. From 7948a5ccfaf580d8bdabd2c56a8cfcfc16410c37 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 9 Mar 2022 17:25:12 -0800 Subject: [PATCH 2/7] Document dunder method --- .../signatures/array_object.py | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/spec/API_specification/signatures/array_object.py b/spec/API_specification/signatures/array_object.py index 31a8493de..375719d29 100644 --- a/spec/API_specification/signatures/array_object.py +++ b/spec/API_specification/signatures/array_object.py @@ -634,6 +634,34 @@ def __mod__(self: array, other: Union[int, float, array], /) -> array: .. note:: For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined. + **Special Cases** + + .. note:: + In general, this method is **not** recommended for floating-point operands as semantics do not follow IEEE 754. That this method is specified to accept floating-point operands is primarily for reasons of backward compatibility. + + For floating-point operands, let ``self`` equal ``x1`` and ``other`` equal ``x2``. + + - If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``. + - If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``. + - If ``x1_i`` is either ``+0`` or ``-0`` and ``x2_i`` is either ``+0`` or ``-0``, the result is ``NaN``. + - If ``x1_i`` is ``+0`` and ``x2_i`` is greater than ``0``, the result is ``+0``. + - If ``x1_i`` is ``-0`` and ``x2_i`` is greater than ``0``, the result is ``+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 ``NaN``. + - If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``. + - If ``x1_i`` is less than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``. + - If ``x1_i`` is less than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``. + - If ``x1_i`` is ``+infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``+infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``-infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is ``-infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``. + - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) + - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x2_i``. (**note**: this result matches Python behavior.) + - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.) + - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) + - In the remaining cases, the result must match that of the Python ``%`` operator. + Parameters ---------- self: array From 4b2f9aa17c3846201644086282f988226632186d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 9 Mar 2022 17:36:25 -0800 Subject: [PATCH 3/7] Update note --- spec/API_specification/signatures/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index 8fa2f1699..e4af5c880 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -1113,7 +1113,7 @@ def remainder(x1: array, x2: array, /) -> array: Returns the remainder of division for each element ``x1_i`` of the input array ``x1`` and the respective element ``x2_i`` of the input array ``x2``. .. note:: - This function is equivalent to the Python modulus operator ``x1_i % x2_i`` and is complementary to the :func:`~signatures.elementwise_functions.floor_divide`. + This function is equivalent to the Python modulus operator ``x1_i % x2_i``. .. note:: For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined. From 85dc561e8bc7dfd8a6fa0f063ce63e0d503213a4 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 10 Mar 2022 01:39:08 -0800 Subject: [PATCH 4/7] Fix indentation Co-authored-by: Matthew Barber --- spec/API_specification/signatures/array_object.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/array_object.py b/spec/API_specification/signatures/array_object.py index 375719d29..970f641a1 100644 --- a/spec/API_specification/signatures/array_object.py +++ b/spec/API_specification/signatures/array_object.py @@ -660,7 +660,7 @@ def __mod__(self: array, other: Union[int, float, array], /) -> array: - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x2_i``. (**note**: this result matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) - - In the remaining cases, the result must match that of the Python ``%`` operator. + - In the remaining cases, the result must match that of the Python ``%`` operator. Parameters ---------- From 7fbd3d81799da53638ccb72b2e130371f01229a5 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 10 Mar 2022 01:39:22 -0800 Subject: [PATCH 5/7] Fix indentation Co-authored-by: Matthew Barber --- spec/API_specification/signatures/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index e4af5c880..0795c78e4 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -1144,7 +1144,7 @@ def remainder(x1: array, x2: array, /) -> array: - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x2_i``. (**note**: this result matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) - - In the remaining cases, the result must match that of the Python ``%`` operator. + - In the remaining cases, the result must match that of the Python ``%`` operator. Parameters ---------- From 5d094183024ca9043e08bd7a65cad8fbac781dab Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 10 Mar 2022 01:39:45 -0800 Subject: [PATCH 6/7] Fix spelling Co-authored-by: Matthew Barber --- spec/API_specification/signatures/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index 0795c78e4..cc5c05f63 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -1123,7 +1123,7 @@ def remainder(x1: array, x2: array, /) -> array: .. note:: In general, similar to Python's ``%`` operator, this function is **not** recommended for floating-point operands as semantics do not follow IEEE 754. That this function is specified to accept floating-point operands is primarily for reasons of backward compatibility. - For floating-points operands, + For floating-point operands, - 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``. From b3504b9096d8a497b675a0eb8fc82c5826a2e3c2 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 10 Mar 2022 01:41:04 -0800 Subject: [PATCH 7/7] Lowercase heading Co-authored-by: Matthew Barber --- spec/API_specification/signatures/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index cc5c05f63..e14b213c8 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -1118,7 +1118,7 @@ def remainder(x1: array, x2: array, /) -> array: .. note:: For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined. - **Special Cases** + **Special cases** .. note:: In general, similar to Python's ``%`` operator, this function is **not** recommended for floating-point operands as semantics do not follow IEEE 754. That this function is specified to accept floating-point operands is primarily for reasons of backward compatibility.