Skip to content

Commit 857e6ad

Browse files
authored
Add design document on complex number ordering (#527)
1 parent 247f082 commit 857e6ad

File tree

7 files changed

+70
-4
lines changed

7 files changed

+70
-4
lines changed

spec/API_specification/array_api/array_object.py

+12
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
427427
"""
428428
Computes the truth value of ``self_i >= other_i`` for each element of an array instance with the respective element of the array ``other``.
429429
430+
.. note::
431+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
432+
430433
Parameters
431434
----------
432435
self: array
@@ -465,6 +468,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array:
465468
"""
466469
Computes the truth value of ``self_i > other_i`` for each element of an array instance with the respective element of the array ``other``.
467470
471+
.. note::
472+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
473+
468474
Parameters
469475
----------
470476
self: array
@@ -538,6 +544,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array:
538544
"""
539545
Computes the truth value of ``self_i <= other_i`` for each element of an array instance with the respective element of the array ``other``.
540546
547+
.. note::
548+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
549+
541550
Parameters
542551
----------
543552
self: array
@@ -580,6 +589,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array:
580589
"""
581590
Computes the truth value of ``self_i < other_i`` for each element of an array instance with the respective element of the array ``other``.
582591
592+
.. note::
593+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
594+
583595
Parameters
584596
----------
585597
self: array

spec/API_specification/array_api/elementwise_functions.py

+12
Original file line numberDiff line numberDiff line change
@@ -973,6 +973,9 @@ def greater(x1: array, x2: array, /) -> array:
973973
"""
974974
Computes the truth value of ``x1_i > x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``.
975975
976+
.. note::
977+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
978+
976979
Parameters
977980
----------
978981
x1: array
@@ -990,6 +993,9 @@ def greater_equal(x1: array, x2: array, /) -> array:
990993
"""
991994
Computes the truth value of ``x1_i >= x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``.
992995
996+
.. note::
997+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
998+
993999
Parameters
9941000
----------
9951001
x1: array
@@ -1067,6 +1073,9 @@ def less(x1: array, x2: array, /) -> array:
10671073
"""
10681074
Computes the truth value of ``x1_i < x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``.
10691075
1076+
.. note::
1077+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
1078+
10701079
Parameters
10711080
----------
10721081
x1: array
@@ -1084,6 +1093,9 @@ def less_equal(x1: array, x2: array, /) -> array:
10841093
"""
10851094
Computes the truth value of ``x1_i <= x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``.
10861095
1096+
.. note::
1097+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
1098+
10871099
Parameters
10881100
----------
10891101
x1: array

spec/API_specification/array_api/searching_functions.py

+12-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,12 @@
22

33
def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array:
44
"""
5-
Returns the indices of the maximum values along a specified axis. When the maximum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
5+
Returns the indices of the maximum values along a specified axis.
6+
7+
When the maximum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
8+
9+
.. note::
10+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
611
712
Parameters
813
----------
@@ -21,7 +26,12 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -
2126

2227
def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array:
2328
"""
24-
Returns the indices of the minimum values along a specified axis. When the minimum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
29+
Returns the indices of the minimum values along a specified axis.
30+
31+
When the minimum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
32+
33+
.. note::
34+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
2535
2636
Parameters
2737
----------

spec/API_specification/array_api/sorting_functions.py

+8-2
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,13 @@ def argsort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bo
44
"""
55
Returns the indices that sort an array ``x`` along a specified axis.
66
7+
.. note::
8+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
9+
710
Parameters
811
----------
912
x : array
10-
input array.
13+
input array. Should have a real-valued data type.
1114
axis: int
1215
axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
1316
descending: bool
@@ -25,10 +28,13 @@ def sort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool
2528
"""
2629
Returns a sorted copy of an input array ``x``.
2730
31+
.. note::
32+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
33+
2834
Parameters
2935
----------
3036
x: array
31-
input array.
37+
input array. Should have a real-valued data type.
3238
axis: int
3339
axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
3440
descending: bool

spec/API_specification/array_api/statistical_functions.py

+6
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ def max(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep
77
.. note::
88
When the number of elements over which to compute the maximum value is zero, the maximum value is implementation-defined. Specification-compliant libraries may choose to raise an error, return a sentinel value (e.g., if ``x`` is a floating-point input array, return ``NaN``), or return the minimum possible value for the input array ``x`` data type (e.g., if ``x`` is a floating-point array, return ``-infinity``).
99
10+
.. note::
11+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
12+
1013
**Special Cases**
1114
1215
For floating-point operands,
@@ -64,6 +67,9 @@ def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep
6467
.. note::
6568
When the number of elements over which to compute the minimum value is zero, the minimum value is implementation-defined. Specification-compliant libraries may choose to raise an error, return a sentinel value (e.g., if ``x`` is a floating-point input array, return ``NaN``), or return the maximum possible value for the input array ``x`` data type (e.g., if ``x`` is a floating-point array, return ``+infinity``).
6669
70+
.. note::
71+
For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
72+
6773
**Special Cases**
6874
6975
For floating-point operands,
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. _complex-number-ordering:
2+
3+
Complex Number Ordering
4+
=======================
5+
6+
Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties:
7+
8+
1. **Reflexive**: for any :math:`a` in the set, :math:`a \leq a`.
9+
2. **Transitive**: for any :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b` and :math:`b \leq c`, then :math:`a \leq c`.
10+
3. **Antisymmetric**: for any :math:`a` and :math:`b` in the set, if :math:`a \leq b` and :math:`b \leq a`, then :math:`a = b`.
11+
4. **Total Order**: in addition to the *partial order* established by 1-3, for any :math:`a` and :math:`b` in the set, either :math:`a \leq b` or :math:`b \leq a` (or both).
12+
5. **Compatible with Addition**: for all :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b`, then :math:`a + c \leq b + c`.
13+
6. **Compatible with Multiplication**: for all :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b` and :math:`0 \leq c`, then :math:`ac \leq bc`.
14+
15+
Defining an order relation for complex numbers which satisfies all six properties defined above is not possible. Accordingly, this specification does not require that a conforming implementation of the array API standard adopt any specific complex number order relation.
16+
17+
In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an ordering for complex numbers (e.g., lexicographic); however, consumers of the array API standard should **not** assume that complex number ordering is consistent between implementations or even supported.
18+
19+
If a conforming implementation chooses to define an ordering for complex numbers, the ordering must be clearly documented.

spec/design_topics/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@ Design topics & constraints
1212
static_typing
1313
accuracy
1414
branch_cuts
15+
complex_number_ordering
1516
C_API
1617
parallelism

0 commit comments

Comments
 (0)