From 2eaf8d0e022a458c9ed20ef2ef1888cffa8499be Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 04:07:44 -0800 Subject: [PATCH 1/9] Add design document on complex number ordering --- .../API_specification/array_api/array_object.py | 12 ++++++++++++ .../array_api/elementwise_functions.py | 12 ++++++++++++ spec/design_topics/complex_number_ordering.rst | 17 +++++++++++++++++ spec/design_topics/index.rst | 1 + 4 files changed, 42 insertions(+) create mode 100644 spec/design_topics/complex_number_ordering.rst diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index cc24a3bbe..2bc89ff4d 100644 --- a/spec/API_specification/array_api/array_object.py +++ b/spec/API_specification/array_api/array_object.py @@ -427,6 +427,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array: """ Computes the truth value of ``self_i >= other_i`` for each element of an array instance with the respective element of the array ``other``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- self: array @@ -465,6 +468,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array: """ Computes the truth value of ``self_i > other_i`` for each element of an array instance with the respective element of the array ``other``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- self: array @@ -538,6 +544,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array: """ Computes the truth value of ``self_i <= other_i`` for each element of an array instance with the respective element of the array ``other``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- self: array @@ -580,6 +589,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array: """ Computes the truth value of ``self_i < other_i`` for each element of an array instance with the respective element of the array ``other``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- self: array diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index e76be8d65..145446d03 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -779,6 +779,9 @@ def greater(x1: array, x2: array, /) -> array: """ 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``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- x1: array @@ -796,6 +799,9 @@ def greater_equal(x1: array, x2: array, /) -> array: """ 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``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- x1: array @@ -873,6 +879,9 @@ def less(x1: array, x2: array, /) -> array: """ 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``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- x1: array @@ -890,6 +899,9 @@ def less_equal(x1: array, x2: array, /) -> array: """ 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``. + .. note:: + Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + Parameters ---------- x1: array diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst new file mode 100644 index 000000000..3de200c9e --- /dev/null +++ b/spec/design_topics/complex_number_ordering.rst @@ -0,0 +1,17 @@ +.. _complex-number-ordering: + +Complex Number Ordering +======================= + +Given a set :math:`{a_1, \ldots, a_n}`, an order relation must satisfy the following properties: + +1. For any :math:`a` in the set, :math:`a \leq a` (i.e., *reflexive*). +2. 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` (i.e., *transitive*). +3. For any :math:`a` and :math:`b` in the set, if :math:`a \leq b` and :math:`b \leq a`, then :math:`a = b` (i.e., *antisymmetric*). +4. For any :math:`a` and :math:`b` in the set, either :math:`a \leq b` or :math:`b \leq a` (or both) (i.e., in addition to a *partial order* established by 1-3, satisfies a *total order*). +5. For all :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b`, then :math:`a + c \leq b + c` (i.e., compatible with addition). +6. 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` (i.e., compatible with multiplication). + +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. + +In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an order relation 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. \ No newline at end of file diff --git a/spec/design_topics/index.rst b/spec/design_topics/index.rst index c8c55b3be..55b9d74b4 100644 --- a/spec/design_topics/index.rst +++ b/spec/design_topics/index.rst @@ -12,5 +12,6 @@ Design topics & constraints static_typing accuracy branch_cuts + complex_number_ordering C_API parallelism From 704e9affee53cf74725c280d3b75393f035a891c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 04:13:32 -0800 Subject: [PATCH 2/9] Add brackets --- spec/design_topics/complex_number_ordering.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst index 3de200c9e..85b89970e 100644 --- a/spec/design_topics/complex_number_ordering.rst +++ b/spec/design_topics/complex_number_ordering.rst @@ -3,7 +3,7 @@ Complex Number Ordering ======================= -Given a set :math:`{a_1, \ldots, a_n}`, an order relation must satisfy the following properties: +Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties: 1. For any :math:`a` in the set, :math:`a \leq a` (i.e., *reflexive*). 2. 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` (i.e., *transitive*). From 686b0c7109515dab906661f123d66a8d2c4104a5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 04:15:52 -0800 Subject: [PATCH 3/9] Reformat --- spec/design_topics/complex_number_ordering.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst index 85b89970e..4b578a521 100644 --- a/spec/design_topics/complex_number_ordering.rst +++ b/spec/design_topics/complex_number_ordering.rst @@ -5,12 +5,12 @@ Complex Number Ordering Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties: -1. For any :math:`a` in the set, :math:`a \leq a` (i.e., *reflexive*). -2. 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` (i.e., *transitive*). -3. For any :math:`a` and :math:`b` in the set, if :math:`a \leq b` and :math:`b \leq a`, then :math:`a = b` (i.e., *antisymmetric*). -4. For any :math:`a` and :math:`b` in the set, either :math:`a \leq b` or :math:`b \leq a` (or both) (i.e., in addition to a *partial order* established by 1-3, satisfies a *total order*). -5. For all :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b`, then :math:`a + c \leq b + c` (i.e., compatible with addition). -6. 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` (i.e., compatible with multiplication). +1. **Reflexive**: for any :math:`a` in the set, :math:`a \leq a`. +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`. +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`. +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). +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`. +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`. 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. From 3bea51c3009b78d43539e6846f93d497083c1960 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 04:19:54 -0800 Subject: [PATCH 4/9] Update copy --- spec/design_topics/complex_number_ordering.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst index 4b578a521..8c5404b91 100644 --- a/spec/design_topics/complex_number_ordering.rst +++ b/spec/design_topics/complex_number_ordering.rst @@ -14,4 +14,4 @@ Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the fol 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. -In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an order relation 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. \ No newline at end of file +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. \ No newline at end of file From 3a1a68c8f1faee7f7eb387954b7d8bb8c7b14a3f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 13:20:29 -0800 Subject: [PATCH 5/9] Update notes --- spec/API_specification/array_api/array_object.py | 8 ++++---- spec/API_specification/array_api/elementwise_functions.py | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index 2bc89ff4d..600851569 100644 --- a/spec/API_specification/array_api/array_object.py +++ b/spec/API_specification/array_api/array_object.py @@ -428,7 +428,7 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array: Computes the truth value of ``self_i >= other_i`` for each element of an array instance with the respective element of the array ``other``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -469,7 +469,7 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array: Computes the truth value of ``self_i > other_i`` for each element of an array instance with the respective element of the array ``other``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -545,7 +545,7 @@ def __le__(self: array, other: Union[int, float, array], /) -> array: Computes the truth value of ``self_i <= other_i`` for each element of an array instance with the respective element of the array ``other``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -590,7 +590,7 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array: Computes the truth value of ``self_i < other_i`` for each element of an array instance with the respective element of the array ``other``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index 145446d03..1b115189c 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -780,7 +780,7 @@ def greater(x1: array, x2: array, /) -> array: 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``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -800,7 +800,7 @@ def greater_equal(x1: array, x2: array, /) -> array: 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``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -880,7 +880,7 @@ def less(x1: array, x2: array, /) -> array: 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``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- @@ -900,7 +900,7 @@ def less_equal(x1: array, x2: array, /) -> array: 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``. .. note:: - Inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + 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`). Parameters ---------- From 7d053120e48b19ad3b72421ec30793778a3a7f30 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 13:35:54 -0800 Subject: [PATCH 6/9] Add notes to searching functions concerning complex number support --- .../array_api/searching_functions.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/searching_functions.py b/spec/API_specification/array_api/searching_functions.py index a76b03f63..1db08f287 100644 --- a/spec/API_specification/array_api/searching_functions.py +++ b/spec/API_specification/array_api/searching_functions.py @@ -2,7 +2,12 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: """ - 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. + 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. + + .. note:: + 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`). Parameters ---------- @@ -21,7 +26,12 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: """ - 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. + 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. + + .. note:: + 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`). Parameters ---------- From 4057a884a979fff6c45edd7a83c381da0bfb20b1 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 13:41:00 -0800 Subject: [PATCH 7/9] Add notes concerning complex number support to sorting functions --- spec/API_specification/array_api/sorting_functions.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/sorting_functions.py b/spec/API_specification/array_api/sorting_functions.py index 715a3e817..53732d535 100644 --- a/spec/API_specification/array_api/sorting_functions.py +++ b/spec/API_specification/array_api/sorting_functions.py @@ -4,10 +4,13 @@ def argsort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bo """ Returns the indices that sort an array ``x`` along a specified axis. + .. note:: + 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`). + Parameters ---------- x : array - input array. + input array. Should have a real-valued data type. axis: int axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. descending: bool @@ -25,10 +28,13 @@ def sort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool """ Returns a sorted copy of an input array ``x``. + .. note:: + 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`). + Parameters ---------- x: array - input array. + input array. Should have a real-valued data type. axis: int axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. descending: bool From 6ccf3d8f4fe0baf555c1b7995c4194ba2a3eba30 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 13:48:17 -0800 Subject: [PATCH 8/9] Add notes concerning complex number support to `min` and `max` --- spec/API_specification/array_api/statistical_functions.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/API_specification/array_api/statistical_functions.py b/spec/API_specification/array_api/statistical_functions.py index 6cdbbb338..9ef10060d 100644 --- a/spec/API_specification/array_api/statistical_functions.py +++ b/spec/API_specification/array_api/statistical_functions.py @@ -7,6 +7,9 @@ def max(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep .. note:: 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``). + .. note:: + 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`). + **Special Cases** For floating-point operands, @@ -64,6 +67,9 @@ def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep .. note:: 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``). + .. note:: + 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`). + **Special Cases** For floating-point operands, From ec99dc5d9f7f4a9980d79f74a6d2c58a7bcba15a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 14:14:50 -0800 Subject: [PATCH 9/9] Update copy --- spec/design_topics/complex_number_ordering.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst index 8c5404b91..25ad215cd 100644 --- a/spec/design_topics/complex_number_ordering.rst +++ b/spec/design_topics/complex_number_ordering.rst @@ -14,4 +14,6 @@ Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the fol 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. -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. \ No newline at end of file +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. + +If a conforming implementation chooses to define an ordering for complex numbers, the ordering must be clearly documented. \ No newline at end of file