diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index cc24a3bbe..600851569 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:: + 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 ---------- 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:: + 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 ---------- 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:: + 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 ---------- 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:: + 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 ---------- self: array diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index e76be8d65..1b115189c 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:: + 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 ---------- 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:: + 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 ---------- 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:: + 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 ---------- 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:: + 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 ---------- x1: array 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 ---------- 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 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, diff --git a/spec/design_topics/complex_number_ordering.rst b/spec/design_topics/complex_number_ordering.rst new file mode 100644 index 000000000..25ad215cd --- /dev/null +++ b/spec/design_topics/complex_number_ordering.rst @@ -0,0 +1,19 @@ +.. _complex-number-ordering: + +Complex Number Ordering +======================= + +Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties: + +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. + +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 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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy