8000 Update the specification for `remainder` to include special cases for… · data-apis/array-api@c16f5fa · GitHub
[go: up one dir, main page]
Skip to content

Commit c16f5fa

Browse files
kgrytehonno
kgryte
and
honno
authored
Update the specification for remainder to include special cases for floating-point operands (#401)
* Specify special cases for floating-point operands * Document dunder method * Update note * Fix indentation Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com> * Fix indentation Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com> * Fix spelling Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com> * Lowercase heading Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com> Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com>
1 parent 157c16b commit c16f5fa

File tree

2 files changed

+61
-1
lines changed

2 files changed

+61
-1
lines changed

‎spec/API_specification/signatures/array_object.py

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -634,6 +634,34 @@ def __mod__(self: array, other: Union[int, float, array], /) -> array:
634634
.. note::
635635
For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined.
636636
637+
**Special Cases**
638+
639+
.. note::
640+
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.
641+
642+
For floating-point operands, let ``self`` equal ``x1`` and ``other`` equal ``x2``.
643+
644+
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
645+
- If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``.
646+
- If ``x1_i`` is either ``+0`` or ``-0`` and ``x2_i`` is either ``+0`` or ``-0``, the result is ``NaN``.
647+
- If ``x1_i`` is ``+0`` and ``x2_i`` is greater than ``0``, the result is ``+0``.
648+
- If ``x1_i`` is ``-0`` and ``x2_i`` is greater than ``0``, the result is ``+0``.
649+
- If ``x1_i`` is ``+0`` and ``x2_i`` is less than ``0``, the result is ``-0``.
650+
- If ``x1_i`` is ``-0`` and ``x2_i`` is less than ``0``, the result is ``-0``.
651+
- If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``.
652+
- If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``.
653+
- If ``x1_i`` is less than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``.
654+
- If ``x1_i`` is less than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``.
655+
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``.
656+
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``.
657+
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``.
658+
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``.
659+
- 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.)
660+
- 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.)
661+
- 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.)
662+
- 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.)
663+
- In the remaining cases, the result must match that of the Python ``%`` operator.
664+
637665
Parameters
638666
----------
639667
self: array

‎spec/API_specification/signatures/elementwise_functions.py

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -638,7 +638,7 @@ def floor_divide(x1: array, x2: array, /) -> array:
638638
- If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``+0``.
639639
- If ``x1_i`` and ``x2_i`` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign.
640640
- If ``x1_i`` and ``x2_i`` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign.
641-
- 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.
641+
- 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.
642642
643643
Parameters
644644
----------
@@ -1112,9 +1112,40 @@ def remainder(x1: array, x2: array, /) -> array:
11121112
"""
11131113
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``.
11141114
1115+
.. note::
1116+
This function is equivalent to the Python modulus operator ``x1_i % x2_i``.
1117+
11151118
.. note::
11161119
For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined.
11171120
1121+
**Special cases**
1122+
1123+
.. note::
1124+
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.
1125+
1126+
For floating-point operands,
1127+
1128+
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
1129+
- If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``.
1130+
- If ``x1_i`` is either ``+0`` or ``-0`` and ``x2_i`` is either ``+0`` or ``-0``, the result is ``NaN``.
1131+
- If ``x1_i`` is ``+0`` and ``x2_i`` is greater than ``0``, the result is ``+0``.
1132+
- If ``x1_i`` is ``-0`` and ``x2_i`` is greater than ``0``, the result is ``+0``.
1133+
- If ``x1_i`` is ``+0`` and ``x2_i`` is less than ``0``, the result is ``-0``.
1134+
- If ``x1_i`` is ``-0`` and ``x2_i`` is less than ``0``, the result is ``-0``.
1135+
- If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``.
1136+
- If ``x1_i`` is greater than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``.
1137+
- If ``x1_i`` is less than ``0`` and ``x2_i`` is ``+0``, the result is ``NaN``.
1138+
- If ``x1_i`` is less than ``0`` and ``x2_i`` is ``-0``, the result is ``NaN``.
1139+
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``.
1140+
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``.
1141+
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``NaN``.
1142+
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is a negative (i.e., less than ``0``) finite number, the result is ``NaN``.
1143+
- 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.)
1144+
- 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.)
1145+
- 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.)
1146+
- 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.)
1147+
- In the remaining cases, the result must match that of the Python ``%`` operator.
1148+
11181149
Parameters
11191150
----------
11201151
x1: array
@@ -1206,6 +1237,7 @@ def sinh(x: array, /) -> array:
12061237
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``.
12071238
12081239
**Special cases**
1240+
12091241
For floating-point operands,
12101242
12111243
- If ``x_i`` is ``NaN``, the result is ``NaN``.

0 commit comments

Comments
 (0)
0