From 87855e270c7e5107884d3e9ab14abbb52a2277b5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 18 Apr 2022 11:55:40 -0700 Subject: [PATCH 1/5] Add complex floating-point data types --- spec/API_specification/data_types.rst | 32 ++++++++++++++++----------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst index f40006c4e..198a3aade 100644 --- a/spec/API_specification/data_types.rst +++ b/spec/API_specification/data_types.rst @@ -62,19 +62,20 @@ float64 IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). -.. note:: - IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks. +complex64 +--------- - Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. +Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). -.. admonition:: Future extension - :class: admonition tip +complex128 +---------- - ``complex64`` and ``complex128`` data types are expected to be included in the next version of this standard and to have the following casting rules (will be added to :ref:`type-promotion`): +Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). - .. image:: /_static/images/dtype_promotion_complex.png +.. note:: + IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks. - See `array-api/issues/102 `_ for more details + Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. .. note:: A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification. @@ -117,10 +118,13 @@ Default Data Types A conforming implementation of the array API standard must define the following default data types. - a default floating-point data type (either ``float32`` or ``float64``). +- a default complex floating-point data type (either ``complex64`` or ``complex128``). - a default integer data type (either ``int32`` or ``int64``). - a default array index data type (either ``int32`` or ``int64``). -The default floating-point data type must be the same across platforms. +The default floating-point and complex floating-point data types must be the same across platforms. + +The default complex floating-point point data type should match the default floating-point data type. For example, if the default floating-point data type is ``float32``, the default complex floating-point data type must be ``complex64``. If the default floating-point data type is ``float64``, the default complex floating-point data type must be ``complex128``. The default integer data type should be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit. @@ -139,14 +143,11 @@ For the purpose of organizing functions within this specification, the following .. note:: Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification. -.. note:: - Future versions of the specification will include additional categories for complex data types. - Numeric Data Types ~~~~~~~~~~~~~~~~~~ -``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64`` (i.e., all data types except for ``bool``). +``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64``. Integer Data Types ~~~~~~~~~~~~~~~~~~ @@ -158,6 +159,11 @@ Floating-point Data Types ``float32`` and ``float64``. +Complex Floating-point Data Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``complex64`` and ``complex128``. + Boolean Data Types ~~~~~~~~~~~~~~~~~~ From fcf179a54b1cf2626ea6c9f7c205ceb8a640edf0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 2 May 2022 11:18:23 -0700 Subject: [PATCH 2/5] Add complex dtypes to numeric category and add real-valued data types category --- spec/API_specification/data_types.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst index 198a3aade..b1b8401a7 100644 --- a/spec/API_specification/data_types.rst +++ b/spec/API_specification/data_types.rst @@ -147,6 +147,11 @@ For the purpose of organizing functions within this specification, the following Numeric Data Types ~~~~~~~~~~~~~~~~~~ +``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, ``float64``, ``complex64``, and ``complex128``. + +Real-valued Data Types +~~~~~~~~~~~~~~~~~~~~~~ + ``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64``. Integer Data Types From 7b42623a8d626a87560ec6433d513f3125e66fc5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 2 May 2022 11:32:51 -0700 Subject: [PATCH 3/5] Replace "numeric data type" with "real-valued data type" This change ensures that the specification maintains the status quo in terms of accepted dtypes for the current set of APIs. Subsequent PRs will add support to APIs for complex number data types on a case-by-case basis. --- spec/API_specification/array_object.rst | 4 +- .../signatures/array_object.py | 54 ++++++------- .../signatures/creation_functions.py | 2 +- .../signatures/data_type_functions.py | 4 +- .../signatures/elementwise_functions.py | 76 +++++++++---------- spec/API_specification/signatures/linalg.py | 10 +-- .../signatures/linear_algebra_functions.py | 12 +-- .../signatures/searching_functions.py | 4 +- .../signatures/statistical_functions.py | 8 +- 9 files changed, 87 insertions(+), 87 deletions(-) diff --git a/spec/API_specification/array_object.rst b/spec/API_specification/array_object.rst index 55a8ff0ab..f9fa91b1e 100644 --- a/spec/API_specification/array_object.rst +++ b/spec/API_specification/array_object.rst @@ -82,7 +82,7 @@ A conforming implementation of the array API standard must provide and support a - `operator.pow(x1, x2) `_ - `operator.__pow__(x1, x2) `_ -Arithmetic operators should be defined for arrays having numeric data types. +Arithmetic operators should be defined for arrays having real-valued data types. Array Operators ~~~~~~~~~~~~~~~ @@ -94,7 +94,7 @@ A conforming implementation of the array API standard must provide and support a - `operator.matmul(x1, x2) `_ - `operator.__matmul__(x1, x2) `_ -The matmul ``@`` operator should be defined for arrays having numeric data types. +The matmul ``@`` operator should be defined for arrays having real-valued data types. Bitwise Operators ~~~~~~~~~~~~~~~~~ diff --git a/spec/API_specification/signatures/array_object.py b/spec/API_specification/signatures/array_object.py index 970f641a1..e4c93a15c 100644 --- a/spec/API_specification/signatures/array_object.py +++ b/spec/API_specification/signatures/array_object.py @@ -126,7 +126,7 @@ def __abs__(self: array, /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. Returns ------- @@ -170,9 +170,9 @@ def __add__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance (augend array). Should have a numeric data type. + array instance (augend array). Should have a real-valued data type. other: Union[int, float, array] - addend array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + addend array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -400,9 +400,9 @@ def __floordiv__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -421,9 +421,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -459,9 +459,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -532,9 +532,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -574,9 +574,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -598,9 +598,9 @@ def __matmul__(self: array, other: array, /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. Must have at least one dimension. If ``self`` is one-dimensional having shape ``(M,)`` and ``other`` has more than one dimension, ``self`` must be promoted to a two-dimensional array by prepending ``1`` to its dimensions (i.e., must have shape ``(1, M)``). After matrix multiplication, the prepended dimensions in the returned array must be removed. If ``self`` has more than one dimension (including after vector-to-matrix promotion), ``shape(self)[:-2]`` must be compatible with ``shape(other)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``self`` has shape ``(..., M, K)``, the innermost two dimensions form matrices on which to perform matrix multiplication. + array instance. Should have a real-valued data type. Must have at least one dimension. If ``self`` is one-dimensional having shape ``(M,)`` and ``other`` has more than one dimension, ``self`` must be promoted to a two-dimensional array by prepending ``1`` to its dimensions (i.e., must have shape ``(1, M)``). After matrix multiplication, the prepended dimensions in the returned array must be removed. If ``self`` has more than one dimension (including after vector-to-matrix promotion), ``shape(self)[:-2]`` must be compatible with ``shape(other)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``self`` has shape ``(..., M, K)``, the innermost two dimensions form matrices on which to perform matrix multiplication. other: array - other array. Should have a numeric data type. Must have at least one dimension. If ``other`` is one-dimensional having shape ``(N,)`` and ``self`` has more than one dimension, ``other`` must be promoted to a two-dimensional array by appending ``1`` to its dimensions (i.e., must have shape ``(N, 1)``). After matrix multiplication, the appended dimensions in the returned array must be removed. If ``other`` has more than one dimension (including after vector-to-matrix promotion), ``shape(other)[:-2]`` must be compatible with ``shape(self)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``other`` has shape ``(..., K, N)``, the innermost two dimensions form matrices on which to perform matrix multiplication. + other array. Should have a real-valued data type. Must have at least one dimension. If ``other`` is one-dimensional having shape ``(N,)`` and ``self`` has more than one dimension, ``other`` must be promoted to a two-dimensional array by appending ``1`` to its dimensions (i.e., must have shape ``(N, 1)``). After matrix multiplication, the appended dimensions in the returned array must be removed. If ``other`` has more than one dimension (including after vector-to-matrix promotion), ``shape(other)[:-2]`` must be compatible with ``shape(self)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``other`` has shape ``(..., K, N)``, the innermost two dimensions form matrices on which to perform matrix multiplication. Returns ------- @@ -665,9 +665,9 @@ def __mod__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -704,9 +704,9 @@ def __mul__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -749,7 +749,7 @@ def __neg__(self: array, /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. Returns ------- @@ -789,7 +789,7 @@ def __pos__(self: array, /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. Returns ------- @@ -842,9 +842,9 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance whose elements correspond to the exponentiation base. Should have a numeric data type. + array instance whose elements correspond to the exponentiation base. Should have a real-valued data type. other: Union[int, float, array] - other array whose elements correspond to the exponentiation exponent. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array whose elements correspond to the exponentiation exponent. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -907,9 +907,9 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance (minuend array). Should have a numeric data type. + array instance (minuend array). Should have a real-valued data type. other: Union[int, float, array] - subtrahend array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + subtrahend array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -960,9 +960,9 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: Parameters ---------- self: array - array instance. Should have a numeric data type. + array instance. Should have a real-valued data type. other: Union[int, float, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- diff --git a/spec/API_specification/signatures/creation_functions.py b/spec/API_specification/signatures/creation_functions.py index 88db02340..568e60e2d 100644 --- a/spec/API_specification/signatures/creation_functions.py +++ b/spec/API_specification/signatures/creation_functions.py @@ -247,7 +247,7 @@ def meshgrid(*arrays: array, indexing: str = 'xy') -> List[array]: Parameters ---------- arrays: array - an arbitrary number of one-dimensional arrays representing grid coordinates. Each array should have the same numeric data type. + an arbitrary number of one-dimensional arrays representing grid coordinates. Each array should have the same real-valued data type. indexing: str Cartesian ``'xy'`` or matrix ``'ij'`` indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the ``indexing`` keyword has no effect and should be ignored. Default: ``'xy'``. diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index 2356a8b2e..0b4493253 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -8,9 +8,9 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. .. note:: - When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. + When casting a boolean input array to a real-valued data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. - When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. + When casting a real-valued input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. Parameters ---------- diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index 213ebe53e..0176b7d9f 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -18,7 +18,7 @@ def abs(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -106,9 +106,9 @@ def add(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -393,7 +393,7 @@ def ceil(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -490,9 +490,9 @@ def divide(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - dividend input array. Should have a numeric data type. + dividend input array. Should have a real-valued data type. x2: array - divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -589,7 +589,7 @@ def floor(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -643,9 +643,9 @@ def floor_divide(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - dividend input array. Should have a numeric data type. + dividend input array. Should have a real-valued data type. x2: array - divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -660,9 +660,9 @@ def greater(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -677,9 +677,9 @@ def greater_equal(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -694,7 +694,7 @@ def isfinite(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -709,7 +709,7 @@ def isinf(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -724,7 +724,7 @@ def isnan(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -739,9 +739,9 @@ def less(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -756,9 +756,9 @@ def less_equal(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -900,7 +900,7 @@ def logical_and(x1: array, x2: array, /) -> array: Computes the logical AND for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. .. note:: - While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. + While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having real-valued data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. Parameters ---------- @@ -920,7 +920,7 @@ def logical_not(x: array, /) -> array: Computes the logical NOT for each element ``x_i`` of the input array ``x``. .. note:: - While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. + While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having real-valued data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. Parameters ---------- @@ -938,7 +938,7 @@ def logical_or(x1: array, x2: array, /) -> array: Computes the logical OR for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. .. note:: - While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. + While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having real-valued data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. Parameters ---------- @@ -958,7 +958,7 @@ def logical_xor(x1: array, x2: array, /) -> array: Computes the logical XOR for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. .. note:: - While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. + While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having real-valued data types. If non-boolean data types are supported, zeros must be considered the equivalent of ``False``, while non-zeros must be considered the equivalent of ``True``. Parameters ---------- @@ -997,9 +997,9 @@ def multiply(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -1017,7 +1017,7 @@ def negative(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -1049,7 +1049,7 @@ def positive(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -1098,9 +1098,9 @@ def pow(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array whose elements correspond to the exponentiation base. Should have a numeric data type. + first input array whose elements correspond to the exponentiation base. Should have a real-valued data type. x2: array - second input array whose elements correspond to the exponentiation exponent. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array whose elements correspond to the exponentiation exponent. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -1149,9 +1149,9 @@ def remainder(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - dividend input array. Should have a numeric data type. + dividend input array. Should have a real-valued data type. x2: array - divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + divisor input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -1179,7 +1179,7 @@ def round(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -1200,7 +1200,7 @@ def sign(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -1264,7 +1264,7 @@ def square(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- @@ -1304,9 +1304,9 @@ def subtract(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Returns ------- @@ -1382,7 +1382,7 @@ def trunc(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. Returns ------- diff --git a/spec/API_specification/signatures/linalg.py b/spec/API_specification/signatures/linalg.py index 275fa3158..a2878c803 100644 --- a/spec/API_specification/signatures/linalg.py +++ b/spec/API_specification/signatures/linalg.py @@ -31,9 +31,9 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must have the same shape as ``x1``. Should have a numeric data type. + second input array. Must have the same shape as ``x1``. Should have a real-valued data type. axis: int the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. If set to ``-1``, the function computes the cross product for vectors defined by the last axis (dimension). Default: ``-1``. @@ -259,9 +259,9 @@ def outer(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first one-dimensional input array of size ``N``. Should have a numeric data type. + first one-dimensional input array of size ``N``. Should have a real-valued data type. x2: array - second one-dimensional input array of size ``M``. Should have a numeric data type. + second one-dimensional input array of size ``M``. Should have a real-valued data type. Returns ------- @@ -416,7 +416,7 @@ def trace(x: array, /, *, offset: int = 0) -> array: Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a numeric data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a real-valued data type. offset: int offset specifying the off-diagonal relative to the main diagonal. diff --git a/spec/API_specification/signatures/linear_algebra_functions.py b/spec/API_specification/signatures/linear_algebra_functions.py index 30d09c254..275d91856 100644 --- a/spec/API_specification/signatures/linear_algebra_functions.py +++ b/spec/API_specification/signatures/linear_algebra_functions.py @@ -10,9 +10,9 @@ def matmul(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. Must have at least one dimension. If ``x1`` is one-dimensional having shape ``(M,)`` and ``x2`` has more than one dimension, ``x1`` must be promoted to a two-dimensional array by prepending ``1`` to its dimensions (i.e., must have shape ``(1, M)``). After matrix multiplication, the prepended dimensions in the returned array must be removed. If ``x1`` has more than one dimension (including after vector-to-matrix promotion), ``shape(x1)[:-2]`` must be compatible with ``shape(x2)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``x1`` has shape ``(..., M, K)``, the innermost two dimensions form matrices on which to perform matrix multiplication. + first input array. Should have a real-valued data type. Must have at least one dimension. If ``x1`` is one-dimensional having shape ``(M,)`` and ``x2`` has more than one dimension, ``x1`` must be promoted to a two-dimensional array by prepending ``1`` to its dimensions (i.e., must have shape ``(1, M)``). After matrix multiplication, the prepended dimensions in the returned array must be removed. If ``x1`` has more than one dimension (including after vector-to-matrix promotion), ``shape(x1)[:-2]`` must be compatible with ``shape(x2)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``x1`` has shape ``(..., M, K)``, the innermost two dimensions form matrices on which to perform matrix multiplication. x2: array - second input array. Should have a numeric data type. Must have at least one dimension. If ``x2`` is one-dimensional having shape ``(N,)`` and ``x1`` has more than one dimension, ``x2`` must be promoted to a two-dimensional array by appending ``1`` to its dimensions (i.e., must have shape ``(N, 1)``). After matrix multiplication, the appended dimensions in the returned array must be removed. If ``x2`` has more than one dimension (including after vector-to-matrix promotion), ``shape(x2)[:-2]`` must be compatible with ``shape(x1)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``x2`` has shape ``(..., K, N)``, the innermost two dimensions form matrices on which to perform matrix multiplication. + second input array. Should have a real-valued data type. Must have at least one dimension. If ``x2`` is one-dimensional having shape ``(N,)`` and ``x1`` has more than one dimension, ``x2`` must be promoted to a two-dimensional array by appending ``1`` to its dimensions (i.e., must have shape ``(N, 1)``). After matrix multiplication, the appended dimensions in the returned array must be removed. If ``x2`` has more than one dimension (including after vector-to-matrix promotion), ``shape(x2)[:-2]`` must be compatible with ``shape(x1)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``x2`` has shape ``(..., K, N)``, the innermost two dimensions form matrices on which to perform matrix multiplication. Returns ------- @@ -59,9 +59,9 @@ def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Should have a numeric data type. Corresponding contracted axes of ``x1`` and ``x2`` must be equal. + second input array. Should have a real-valued data type. Corresponding contracted axes of ``x1`` and ``x2`` must be equal. .. note:: Contracted axes (dimensions) must not be broadcasted. @@ -90,9 +90,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: Parameters ---------- x1: array - first input array. Should have a numeric data type. + first input array. Should have a real-valued data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. axis:int axis over which to compute the dot product. Must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting`. If specified as a negative integer, the function must determine the axis along which to compute the dot product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function must compute the dot product over the last axis. Default: ``-1``. diff --git a/spec/API_specification/signatures/searching_functions.py b/spec/API_specification/signatures/searching_functions.py index c2875adcc..37da37e24 100644 --- a/spec/API_specification/signatures/searching_functions.py +++ b/spec/API_specification/signatures/searching_functions.py @@ -7,7 +7,7 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[int] axis along which to search. If ``None``, the function must return the index of the maximum value of the flattened array. Default: ``None``. keepdims: bool @@ -26,7 +26,7 @@ def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[int] axis along which to search. If ``None``, the function must return the index of the minimum value of the flattened array. Default: ``None``. keepdims: bool diff --git a/spec/API_specification/signatures/statistical_functions.py b/spec/API_specification/signatures/statistical_functions.py index 4265f28f5..636092441 100644 --- a/spec/API_specification/signatures/statistical_functions.py +++ b/spec/API_specification/signatures/statistical_functions.py @@ -16,7 +16,7 @@ def max(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which maximum values must be computed. By default, the maximum value must be computed over the entire array. If a tuple of integers, maximum values must be computed over multiple axes. Default: ``None``. keepdims: bool @@ -73,7 +73,7 @@ def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which minimum values must be computed. By default, the minimum value must be computed over the entire array. If a tuple of integers, minimum values must be computed over multiple axes. Default: ``None``. keepdims: bool @@ -102,7 +102,7 @@ def prod(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dty Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which products must be computed. By default, the product must be computed over the entire array. If a tuple of integers, products must be computed over multiple axes. Default: ``None``. dtype: Optional[dtype] @@ -175,7 +175,7 @@ def sum(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtyp Parameters ---------- x: array - input array. Should have a numeric data type. + input array. Should have a real-valued data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which sums must be computed. By default, the sum must be computed over the entire array. If a tuple of integers, sums must be computed over multiple axes. Default: ``None``. dtype: Optional[dtype] From 4cee57fce75ed825922a2f30a8d5cde51b07afff Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 22 May 2022 15:32:08 -0700 Subject: [PATCH 4/5] Add category for real-valued floating-point data types --- spec/API_specification/data_types.rst | 11 ++- .../signatures/array_object.py | 10 +- .../signatures/creation_functions.py | 20 ++-- .../signatures/data_type_functions.py | 6 +- .../signatures/elementwise_functions.py | 94 +++++++++---------- spec/API_specification/signatures/linalg.py | 62 ++++++------ .../signatures/statistical_functions.py | 16 ++-- 7 files changed, 112 insertions(+), 107 deletions(-) diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst index b1b8401a7..5d42dcc5b 100644 --- a/spec/API_specification/data_types.rst +++ b/spec/API_specification/data_types.rst @@ -117,14 +117,14 @@ Default Data Types A conforming implementation of the array API standard must define the following default data types. -- a default floating-point data type (either ``float32`` or ``float64``). +- a default real-valued floating-point data type (either ``float32`` or ``float64``). - a default complex floating-point data type (either ``complex64`` or ``complex128``). - a default integer data type (either ``int32`` or ``int64``). - a default array index data type (either ``int32`` or ``int64``). -The default floating-point and complex floating-point data types must be the same across platforms. +The default real-valued floating-point and complex floating-point data types must be the same across platforms. -The default complex floating-point point data type should match the default floating-point data type. For example, if the default floating-point data type is ``float32``, the default complex floating-point data type must be ``complex64``. If the default floating-point data type is ``float64``, the default complex floating-point data type must be ``complex128``. +The default complex floating-point point data type should match the default real-valued floating-point data type. For example, if the default real-valued floating-point data type is ``float32``, the default complex floating-point data type must be ``complex64``. If the default real-valued floating-point data type is ``float64``, the default complex floating-point data type must be ``complex128``. The default integer data type should be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit. @@ -162,6 +162,11 @@ Integer Data Types Floating-point Data Types ~~~~~~~~~~~~~~~~~~~~~~~~~ +``float32``, ``float64``, ``complex64``, and ``complex128``. + +Real-valued Floating-point Data Types +~~~~~~~~~~~~~~~~~~~~~~~~~ + ``float32`` and ``float64``. Complex Floating-point Data Types diff --git a/spec/API_specification/signatures/array_object.py b/spec/API_specification/signatures/array_object.py index e4c93a15c..34a977301 100644 --- a/spec/API_specification/signatures/array_object.py +++ b/spec/API_specification/signatures/array_object.py @@ -346,7 +346,7 @@ def __float__(self: array, /) -> float: Parameters ---------- self: array - zero-dimensional array instance. Must have a floating-point data type. + zero-dimensional array instance. Must have a real-valued floating-point data type. Returns ------- @@ -672,7 +672,7 @@ def __mod__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element ``other_i``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the element-wise results. Each element-wise result must have the same sign as the respective element ``other_i``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. .. note:: @@ -808,7 +808,7 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array: .. note:: If both ``self`` and ``other`` have integer data types, the result of ``__pow__`` when `other_i` is negative (i.e., less than zero) is unspecified and thus implementation-dependent. - If ``self`` has an integer data type and ``other`` has a floating-point data type, behavior is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified. + If ``self`` has an integer data type and ``other`` has a real-valued floating-point data type, behavior is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified. **Special cases** @@ -928,7 +928,7 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: .. note:: If one or both of ``self`` and ``other`` have integer data types, the result is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified. - Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a floating-point data type. + Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a real-valued floating-point data type. **Special cases** @@ -967,7 +967,7 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array should have a floating-point data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array should have a real-valued floating-point data type determined by :ref:`type-promotion`. .. note:: diff --git a/spec/API_specification/signatures/creation_functions.py b/spec/API_specification/signatures/creation_functions.py index 568e60e2d..175cadcc0 100644 --- a/spec/API_specification/signatures/creation_functions.py +++ b/spec/API_specification/signatures/creation_functions.py @@ -14,7 +14,7 @@ def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None step: Union[int, float] the distance between two adjacent elements (``out[i+1] - out[i]``). Must not be ``0``; may be negative, this results in an empty array if ``stop >= start``. Default: ``1``. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``start``, ``stop`` and ``step``. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type ``float``, then the output array dtype must be the default floating-point data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``start``, ``stop`` and ``step``. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type ``float``, then the output array dtype must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. @@ -47,7 +47,7 @@ def asarray(obj: Union[array, bool, int, float, NestedSequence, SupportsBufferPr - if all values are of type ``bool``, the output data type must be ``bool``. - if the values are a mixture of ``bool``\s and ``int``, the output data type must be the default integer data type. - - if one or more values are ``float``\s, the output data type must be the default floating-point data type. + - if one or more values are ``float``\s, the output data type must be the default real-valued floating-point data type. Default: ``None``. @@ -79,7 +79,7 @@ def empty(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, shape: Union[int, Tuple[int, ...]] output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. @@ -121,7 +121,7 @@ def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Opti k: int index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and ``0`` to the main diagonal. Default: ``0``. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. @@ -162,7 +162,7 @@ def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[int, float], *, d fill_value: Union[int, float] fill value. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``fill_value``. If the fill value is an ``int``, the output array data type must be the default integer data type. If the fill value is a ``float``, the output array data type must be the default floating-point data type. If the fill value is a ``bool``, the output array must have boolean data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``fill_value``. If the fill value is an ``int``, the output array data type must be the default integer data type. If the fill value is a ``float``, the output array data type must be the default real-valued floating-point data type. If the fill value is a ``bool``, the output array must have boolean data type. Default: ``None``. .. note:: If the ``fill_value`` exceeds the precision of the resolved default output array data type, behavior is left unspecified and, thus, implementation-defined. @@ -221,7 +221,7 @@ def linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *, num: int number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception. dtype: Optional[dtype] - output array data type. Should be a floating-point data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``. + output array data type. Should be a real-valued floating-point data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. endpoint: bool @@ -234,10 +234,10 @@ def linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *, .. note:: - While this specification recommends that this function only return arrays having a floating-point data type, specification-compliant array libraries may choose to support output arrays having an integer data type (e.g., due to backward compatibility concerns). However, function behavior when generating integer output arrays is unspecified and, thus, is implementation-defined. Accordingly, using this function to generate integer output arrays is not portable. + While this specification recommends that this function only return arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to support output arrays having an integer data type (e.g., due to backward compatibility concerns). However, function behavior when generating integer output arrays is unspecified and, thus, is implementation-defined. Accordingly, using this function to generate integer output arrays is not portable. .. note:: - As mixed data type promotion is implementation-defined, behavior when ``start`` or ``stop`` exceeds the maximum safe integer of an output floating-point data type is implementation-defined. An implementation may choose to overflow or raise an exception. + As mixed data type promotion is implementation-defined, behavior when ``start`` or ``stop`` exceeds the maximum safe integer of an output real-valued floating-point data type is implementation-defined. An implementation may choose to overflow or raise an exception. """ def meshgrid(*arrays: array, indexing: str = 'xy') -> List[array]: @@ -275,7 +275,7 @@ def ones(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, d shape: Union[int, Tuple[int, ...]] output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. @@ -359,7 +359,7 @@ def zeros(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, shape: Union[int, Tuple[int, ...]] output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``. device: Optional[device] device on which to place the created array. Default: ``None``. diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py index 0b4493253..af54336a3 100644 --- a/spec/API_specification/signatures/data_type_functions.py +++ b/spec/API_specification/signatures/data_type_functions.py @@ -78,17 +78,17 @@ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: def finfo(type: Union[dtype, array], /) -> finfo_object: """ - Machine limits for floating-point data types. + Machine limits for real-valued floating-point data types. Parameters ---------- type: Union[dtype, array] - the kind of floating-point data-type about which to get information. + the kind of real-valued floating-point data-type about which to get information. Returns ------- out: finfo object - an object having the followng attributes: + an object having the following attributes: - **bits**: *int* diff --git a/spec/API_specification/signatures/elementwise_functions.py b/spec/API_specification/signatures/elementwise_functions.py index 0176b7d9f..f72af2089 100644 --- a/spec/API_specification/signatures/elementwise_functions.py +++ b/spec/API_specification/signatures/elementwise_functions.py @@ -42,12 +42,12 @@ def acos(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse cosine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse cosine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def acosh(x: array, /) -> array: @@ -66,12 +66,12 @@ def acosh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent the area of a hyperbolic sector. Should have a floating-point data type. + input array whose elements each represent the area of a hyperbolic sector. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse hyperbolic cosine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse hyperbolic cosine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def add(x1: array, x2: array, /) -> array: @@ -133,12 +133,12 @@ def asin(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse sine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse sine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def asinh(x: array, /) -> array: @@ -158,12 +158,12 @@ def asinh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent the area of a hyperbolic sector. Should have a floating-point data type. + input array whose elements each represent the area of a hyperbolic sector. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse hyperbolic sine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse hyperbolic sine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def atan(x: array, /) -> array: @@ -183,12 +183,12 @@ def atan(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse tangent of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse tangent of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def atan2(x1: array, x2: array, /) -> array: @@ -233,14 +233,14 @@ def atan2(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - input array corresponding to the y-coordinates. Should have a floating-point data type. + input array corresponding to the y-coordinates. Should have a real-valued floating-point data type. x2: array - input array corresponding to the x-coordinates. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a floating-point data type. + input array corresponding to the x-coordinates. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse tangent of the quotient ``x1/x2``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse tangent of the quotient ``x1/x2``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ @@ -263,12 +263,12 @@ def atanh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent the area of a hyperbolic sector. Should have a floating-point data type. + input array whose elements each represent the area of a hyperbolic sector. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the inverse hyperbolic tangent of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the inverse hyperbolic tangent of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def bitwise_and(x1: array, x2: array, /) -> array: @@ -418,12 +418,12 @@ def cos(x: array, /) -> array: Parameters ---------- x: array - input array whose elements are each expressed in radians. Should have a floating-point data type. + input array whose elements are each expressed in radians. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the cosine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the cosine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def cosh(x: array, /) -> array: @@ -443,12 +443,12 @@ def cosh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent a hyperbolic angle. Should have a floating-point data type. + input array whose elements each represent a hyperbolic angle. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the hyperbolic cosine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the hyperbolic cosine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def divide(x1: array, x2: array, /) -> array: @@ -458,7 +458,7 @@ def divide(x1: array, x2: array, /) -> array: .. note:: If one or both of the input arrays have integer data types, the result is implementation-dependent, as type promotion between data type "kinds" (e.g., integer versus floating-point) is unspecified. - Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a floating-point data type. + Specification-compliant libraries may choose to raise an error or return an array containing the element-wise results. If an array is returned, the array must have a real-valued floating-point data type. **Special cases** @@ -497,7 +497,7 @@ def divide(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def equal(x1: array, x2: array, /) -> array: @@ -534,12 +534,12 @@ def exp(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated exponential function result for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated exponential function result for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def expm1(x: array, /) -> array: @@ -562,12 +562,12 @@ def expm1(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated result for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def floor(x: array, /) -> array: @@ -783,12 +783,12 @@ def log(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated natural logarithm for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated natural logarithm for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def log1p(x: array, /) -> array: @@ -812,12 +812,12 @@ def log1p(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated result for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def log2(x: array, /) -> array: @@ -837,12 +837,12 @@ def log2(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated base ``2`` logarithm for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated base ``2`` logarithm for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def log10(x: array, /) -> array: @@ -862,12 +862,12 @@ def log10(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the evaluated base ``10`` logarithm for each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the evaluated base ``10`` logarithm for each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def logaddexp(x1: array, x2: array, /) -> array: @@ -885,14 +885,14 @@ def logaddexp(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - first input array. Should have a floating-point data type. + first input array. Should have a real-valued floating-point data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a floating-point data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def logical_and(x1: array, x2: array, /) -> array: @@ -1064,7 +1064,7 @@ def pow(x1: array, x2: array, /) -> array: .. note:: If both ``x1`` and ``x2`` have integer data types, the result of ``pow`` when ``x2_i`` is negative (i.e., less than zero) is unspecified and thus implementation-dependent. - If ``x1`` has an integer data type and ``x2`` has a floating-point data type, behavior is implementation-dependent (type promotion between data type "kinds" (integer versus floating-point) is unspecified). + If ``x1`` has an integer data type and ``x2`` has a real-valued floating-point data type, behavior is implementation-dependent (type promotion between data type "kinds" (integer versus floating-point) is unspecified). **Special cases** @@ -1224,12 +1224,12 @@ def sin(x: array, /) -> array: Parameters ---------- x: array - input array whose elements are each expressed in radians. Should have a floating-point data type. + input array whose elements are each expressed in radians. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the sine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the sine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def sinh(x: array, /) -> array: @@ -1249,12 +1249,12 @@ def sinh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent a hyperbolic angle. Should have a floating-point data type. + input array whose elements each represent a hyperbolic angle. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the hyperbolic sine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the hyperbolic sine of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def square(x: array, /) -> array: @@ -1289,12 +1289,12 @@ def sqrt(x: array, /) -> array: Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the square root of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the square root of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def subtract(x1: array, x2: array, /) -> array: @@ -1330,12 +1330,12 @@ def tan(x: array, /) -> array: Parameters ---------- x: array - input array whose elements are expressed in radians. Should have a floating-point data type. + input array whose elements are expressed in radians. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the tangent of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the tangent of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def tanh(x: array, /) -> array: @@ -1355,12 +1355,12 @@ def tanh(x: array, /) -> array: Parameters ---------- x: array - input array whose elements each represent a hyperbolic angle. Should have a floating-point data type. + input array whose elements each represent a hyperbolic angle. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the hyperbolic tangent of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the hyperbolic tangent of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def trunc(x: array, /) -> array: diff --git a/spec/API_specification/signatures/linalg.py b/spec/API_specification/signatures/linalg.py index a2878c803..7e838ddf1 100644 --- a/spec/API_specification/signatures/linalg.py +++ b/spec/API_specification/signatures/linalg.py @@ -14,14 +14,14 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square symmetric positive-definite matrices. Should have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square symmetric positive-definite matrices. Should have a real-valued floating-point data type. upper: bool If ``True``, the result must be the upper-triangular Cholesky factor ``U``. If ``False``, the result must be the lower-triangular Cholesky factor ``L``. Default: ``False``. Returns ------- out: array - an array containing the Cholesky factors for each square matrix. If ``upper`` is ``False``, the returned array must contain lower-triangular matrices; otherwise, the returned array must contain upper-triangular matrices. The returned array must have a floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. + an array containing the Cholesky factors for each square matrix. If ``upper`` is ``False``, the returned array must contain lower-triangular matrices; otherwise, the returned array must contain upper-triangular matrices. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. """ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: @@ -50,7 +50,7 @@ def det(x: array, /) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a real-valued floating-point data type. Returns ------- @@ -97,7 +97,7 @@ def eigh(x: array, /) -> Tuple[array]: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must have a real-valued floating-point data type. Returns ------- @@ -107,7 +107,7 @@ def eigh(x: array, /) -> Tuple[array]: - first element must have the field name ``eigenvalues`` (corresponding to ``L`` above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape ``(..., M)``. - second element have have the field name ``eigenvectors`` (corresponding to ``Q`` above) and must be an array where the columns of the inner most matrices contain the computed eigenvectors. These matrices must be orthogonal. The array containing the eigenvectors must have shape ``(..., M, M)``. - Each returned array must have the same floating-point data type as ``x``. + Each returned array must have the same real-valued floating-point data type as ``x``. .. note:: Eigenvalue sort order is left unspecified and is thus implementation-dependent. @@ -129,7 +129,7 @@ def eigvalsh(x: array, /) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must have a real-valued floating-point data type. Returns ------- @@ -147,12 +147,12 @@ def inv(x: array, /) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the multiplicative inverses. The returned array must have a floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. + an array containing the multiplicative inverses. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. """ def matmul(x1: array, x2: array, /) -> array: @@ -167,7 +167,7 @@ def matrix_norm(x: array, /, *, keepdims: bool = False, ord: Optional[Union[int, Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a real-valued floating-point data type. keepdims: bool If ``True``, the last two axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the last two axes (dimensions) must not be included in the result. Default: ``False``. ord: Optional[Union[int, float, Literal[inf, -inf, 'fro', 'nuc']]] @@ -210,7 +210,7 @@ def matrix_norm(x: array, /, *, keepdims: bool = False, ord: Optional[Union[int, Returns ------- out: array - an array containing the norms for each ``MxN`` matrix. If ``keepdims`` is ``False``, the returned array must have a rank which is two less than the rank of ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the norms for each ``MxN`` matrix. If ``keepdims`` is ``False``, the returned array must have a rank which is two less than the rank of ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def matrix_power(x: array, n: int, /) -> array: @@ -220,14 +220,14 @@ def matrix_power(x: array, n: int, /) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a real-valued floating-point data type. n: int integer exponent. Returns ------- out: array - if ``n`` is equal to zero, an array containing the identity matrix for each square matrix. If ``n`` is less than zero, an array containing the inverse of each square matrix raised to the absolute value of ``n``, provided that each square matrix is invertible. If ``n`` is greater than zero, an array containing the result of raising each square matrix to the power ``n``. The returned array must have the same shape as ``x`` and a floating-point data type determined by :ref:`type-promotion`. + if ``n`` is equal to zero, an array containing the identity matrix for each square matrix. If ``n`` is less than zero, an array containing the inverse of each square matrix raised to the absolute value of ``n``, provided that each square matrix is invertible. If ``n`` is greater than zero, an array containing the result of raising each square matrix to the power ``n``. The returned array must have the same shape as ``x`` and a real-valued floating-point data type determined by :ref:`type-promotion`. """ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: @@ -237,14 +237,14 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a real-valued floating-point data type. rtol: Optional[Union[float, array]] - relative tolerance for small singular values. Singular values approximately less than or equal to ``rtol * largest_singular_value`` are set to zero. If a ``float``, the value is equivalent to a zero-dimensional array having a floating-point data type determined by :ref:`type-promotion` (as applied to ``x``) and must be broadcast against each matrix. If an ``array``, must have a floating-point data type and must be compatible with ``shape(x)[:-2]`` (see :ref:`broadcasting`). If ``None``, the default value is ``max(M, N) * eps``, where ``eps`` must be the machine epsilon associated with the floating-point data type determined by :ref:`type-promotion` (as applied to ``x``). Default: ``None``. + relative tolerance for small singular values. Singular values approximately less than or equal to ``rtol * largest_singular_value`` are set to zero. If a ``float``, the value is equivalent to a zero-dimensional array having a real-valued floating-point data type determined by :ref:`type-promotion` (as applied to ``x``) and must be broadcast against each matrix. If an ``array``, must have a real-valued floating-point data type and must be compatible with ``shape(x)[:-2]`` (see :ref:`broadcasting`). If ``None``, the default value is ``max(M, N) * eps``, where ``eps`` must be the machine epsilon associated with the real-valued floating-point data type determined by :ref:`type-promotion` (as applied to ``x``). Default: ``None``. Returns ------- out: array - an array containing the ranks. The returned array must have a floating-point data type determined by :ref:`type-promotion` and must have shape ``(...)`` (i.e., must have a shape equal to ``shape(x)[:-2]``). + an array containing the ranks. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion` and must have shape ``(...)`` (i.e., must have a shape equal to ``shape(x)[:-2]``). """ def matrix_transpose(x: array, /) -> array: @@ -276,14 +276,14 @@ def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a real-valued floating-point data type. rtol: Optional[Union[float, array]] - relative tolerance for small singular values. Singular values approximately less than or equal to ``rtol * largest_singular_value`` are set to zero. If a ``float``, the value is equivalent to a zero-dimensional array having a floating-point data type determined by :ref:`type-promotion` (as applied to ``x``) and must be broadcast against each matrix. If an ``array``, must have a floating-point data type and must be compatible with ``shape(x)[:-2]`` (see :ref:`broadcasting`). If ``None``, the default value is ``max(M, N) * eps``, where ``eps`` must be the machine epsilon associated with the floating-point data type determined by :ref:`type-promotion` (as applied to ``x``). Default: ``None``. + relative tolerance for small singular values. Singular values approximately less than or equal to ``rtol * largest_singular_value`` are set to zero. If a ``float``, the value is equivalent to a zero-dimensional array having a real-valued floating-point data type determined by :ref:`type-promotion` (as applied to ``x``) and must be broadcast against each matrix. If an ``array``, must have a real-valued floating-point data type and must be compatible with ``shape(x)[:-2]`` (see :ref:`broadcasting`). If ``None``, the default value is ``max(M, N) * eps``, where ``eps`` must be the machine epsilon associated with the real-valued floating-point data type determined by :ref:`type-promotion` (as applied to ``x``). Default: ``None``. Returns ------- out: array - an array containing the pseudo-inverses. The returned array must have a floating-point data type determined by :ref:`type-promotion` and must have shape ``(..., N, M)`` (i.e., must have the same shape as ``x``, except the innermost two dimensions must be transposed). + an array containing the pseudo-inverses. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion` and must have shape ``(..., N, M)`` (i.e., must have the same shape as ``x``, except the innermost two dimensions must be transposed). """ def qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') -> Tuple[array, array]: @@ -296,7 +296,7 @@ def qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') -> Tupl Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices of rank ``N``. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices of rank ``N``. Should have a real-valued floating-point data type. mode: Literal['reduced', 'complete'] decomposition mode. Should be one of the following modes: @@ -313,7 +313,7 @@ def qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') -> Tupl - first element must have the field name ``Q`` and must be an array whose shape depends on the value of ``mode`` and contain matrices with orthonormal columns. If ``mode`` is ``'complete'``, the array must have shape ``(..., M, M)``. If ``mode`` is ``'reduced'``, the array must have shape ``(..., M, K)``, where ``K = min(M, N)``. The first ``x.ndim-2`` dimensions must have the same size as those of the input array ``x``. - second element must have the field name ``R`` and must be an array whose shape depends on the value of ``mode`` and contain upper-triangular matrices. If ``mode`` is ``'complete'``, the array must have shape ``(..., M, N)``. If ``mode`` is ``'reduced'``, the array must have shape ``(..., K, N)``, where ``K = min(M, N)``. The first ``x.ndim-2`` dimensions must have the same size as those of the input ``x``. - Each returned array must have a floating-point data type determined by :ref:`type-promotion`. + Each returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def slogdet(x: array, /) -> Tuple[array, array]: @@ -326,7 +326,7 @@ def slogdet(x: array, /) -> Tuple[array, array]: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Should have a real-valued floating-point data type. Returns ------- @@ -338,7 +338,7 @@ def slogdet(x: array, /) -> Tuple[array, array]: For a real matrix, the sign of the determinant must be either ``1``, ``0``, or ``-1``. - Each returned array must have shape ``shape(x)[:-2]`` and a floating-point data type determined by :ref:`type-promotion`. + Each returned array must have shape ``shape(x)[:-2]`` and a real-valued floating-point data type determined by :ref:`type-promotion`. .. note:: If a determinant is zero, then the corresponding ``sign`` should be ``0`` and ``logabsdet`` should be ``-infinity``; however, depending on the underlying algorithm, the returned result may differ. In all cases, the determinant should be equal to ``sign * exp(logsabsdet)`` (although, again, the result may be subject to numerical precision errors). @@ -354,14 +354,14 @@ def solve(x1: array, x2: array, /) -> array: Parameters ---------- x1: array - coefficient array ``A`` having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must be of full rank (i.e., all rows or, equivalently, columns must be linearly independent). Should have a floating-point data type. + coefficient array ``A`` having shape ``(..., M, M)`` and whose innermost two dimensions form square matrices. Must be of full rank (i.e., all rows or, equivalently, columns must be linearly independent). Should have a real-valued floating-point data type. x2: array - ordinate (or "dependent variable") array ``B``. If ``x2`` has shape ``(M,)``, ``x2`` is equivalent to an array having shape ``(..., M, 1)``. If ``x2`` has shape ``(..., M, K)``, each column ``k`` defines a set of ordinate values for which to compute a solution, and ``shape(x2)[:-1]`` must be compatible with ``shape(x1)[:-1]`` (see :ref:`broadcasting`). Should have a floating-point data type. + ordinate (or "dependent variable") array ``B``. If ``x2`` has shape ``(M,)``, ``x2`` is equivalent to an array having shape ``(..., M, 1)``. If ``x2`` has shape ``(..., M, K)``, each column ``k`` defines a set of ordinate values for which to compute a solution, and ``shape(x2)[:-1]`` must be compatible with ``shape(x1)[:-1]`` (see :ref:`broadcasting`). Should have a real-valued floating-point data type. Returns ------- out: array - an array containing the solution to the system ``AX = B`` for each square matrix. The returned array must have the same shape as ``x2`` (i.e., the array corresponding to ``B``) and must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the solution to the system ``AX = B`` for each square matrix. The returned array must have the same shape as ``x2`` (i.e., the array corresponding to ``B``) and must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, ...]]: @@ -371,7 +371,7 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a real-valued floating-point data type. full_matrices: bool If ``True``, compute full-sized ``U`` and ``Vh``, such that ``U`` has shape ``(..., M, M)`` and ``Vh`` has shape ``(..., N, N)``. If ``False``, compute on the leading ``K`` singular vectors, such that ``U`` has shape ``(..., M, K)`` and ``Vh`` has shape ``(..., K, N)`` and where ``K = min(M, N)``. Default: ``True``. @@ -386,7 +386,7 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, - second element must have the field name ``S`` and must be an array with shape ``(..., K)`` that contains the vector(s) of singular values of length ``K``, where ``K = min(M, N)``. For each vector, the singular values must be sorted in descending order by magnitude, such that ``s[..., 0]`` is the largest value, ``s[..., 1]`` is the second largest value, et cetera. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. - third element must have the field name ``Vh`` and must be an array whose shape depends on the value of ``full_matrices`` and contain orthonormal rows (i.e., the rows are the right singular vectors and the array is the adjoint). If ``full_matrices`` is ``True``, the array must have shape ``(..., N, N)``. If ``full_matrices`` is ``False``, the array must have shape ``(..., K, N)`` where ``K = min(M, N)``. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. - Each returned array must have the same floating-point data type as ``x``. + Each returned array must have the same real-valued floating-point data type as ``x``. """ def svdvals(x: array, /) -> array: @@ -396,12 +396,12 @@ def svdvals(x: array, /) -> array: Parameters ---------- x: array - input array having shape ``(..., M, N)`` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type. + input array having shape ``(..., M, N)`` and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a real-valued floating-point data type. Returns ------- out: array - an array with shape ``(..., K)`` that contains the vector(s) of singular values of length ``K``, where ``K = min(M, N)``. For each vector, the singular values must be sorted in descending order by magnitude, such that ``s[..., 0]`` is the largest value, ``s[..., 1]`` is the second largest value, et cetera. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. The returned array must have the same floating-point data type as ``x``. + an array with shape ``(..., K)`` that contains the vector(s) of singular values of length ``K``, where ``K = min(M, N)``. For each vector, the singular values must be sorted in descending order by magnitude, such that ``s[..., 0]`` is the largest value, ``s[..., 1]`` is the second largest value, et cetera. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. The returned array must have the same real-valued floating-point data type as ``x``. """ def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2) -> array: @@ -450,7 +450,7 @@ def vector_norm(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = No Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. axis: Optional[Union[int, Tuple[int, ...]]] If an integer, ``axis`` specifies the axis (dimension) along which to compute vector norms. If an n-tuple, ``axis`` specifies the axes (dimensions) along which to compute batched vector norms. If ``None``, the vector norm must be computed over all array values (i.e., equivalent to computing the vector norm of a flattened array). Negative indices must be supported. Default: ``None``. keepdims: bool @@ -491,7 +491,7 @@ def vector_norm(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = No Returns ------- out: array - an array containing the vector norms. If ``axis`` is ``None``, the returned array must be a zero-dimensional array containing a vector norm. If ``axis`` is a scalar value (``int`` or ``float``), the returned array must have a rank which is one less than the rank of ``x``. If ``axis`` is a ``n``-tuple, the returned array must have a rank which is ``n`` less than the rank of ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. + an array containing the vector norms. If ``axis`` is ``None``, the returned array must be a zero-dimensional array containing a vector norm. If ``axis`` is a scalar value (``int`` or ``float``), the returned array must have a rank which is one less than the rank of ``x``. If ``axis`` is a ``n``-tuple, the returned array must have a rank which is ``n`` less than the rank of ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. """ __all__ = ['cholesky', 'cross', 'det', 'diagonal', 'eigh', 'eigvalsh', 'inv', 'matmul', 'matrix_norm', 'matrix_power', 'matrix_rank', 'matrix_transpose', 'outer', 'pinv', 'qr', 'slogdet', 'solve', 'svd', 'svdvals', 'tensordot', 'trace', 'vecdot', 'vector_norm'] diff --git a/spec/API_specification/signatures/statistical_functions.py b/spec/API_specification/signatures/statistical_functions.py index 636092441..6cdbbb338 100644 --- a/spec/API_specification/signatures/statistical_functions.py +++ b/spec/API_specification/signatures/statistical_functions.py @@ -42,7 +42,7 @@ def mean(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, kee Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which arithmetic means must be computed. By default, the mean must be computed over the entire array. If a tuple of integers, arithmetic means must be computed over multiple axes. Default: ``None``. keepdims: bool @@ -54,7 +54,7 @@ def mean(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, kee if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. The returned array must have the same data type as ``x``. .. note:: - While this specification recommends that this function only accept input arrays having a floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default floating-point data type. + While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: @@ -109,7 +109,7 @@ def prod(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dty data type of the returned array. If ``None``, - if the default data type corresponding to the data type "kind" (integer or floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - if ``x`` has a floating-point data type, the returned array must have the default floating-point data type. + - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). @@ -141,7 +141,7 @@ def std(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which standard deviations must be computed. By default, the standard deviation must be computed over the entire array. If a tuple of integers, standard deviations must be computed over multiple axes. Default: ``None``. correction: Union[int, float] @@ -155,7 +155,7 @@ def std(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr if the standard deviation was computed over the entire array, a zero-dimensional array containing the standard deviation; otherwise, a non-zero-dimensional array containing the standard deviations. The returned array must have the same data type as ``x``. .. note:: - While this specification recommends that this function only accept input arrays having a floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default floating-point data type. + While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ def sum(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtype: Optional[dtype] = None, keepdims: bool = False) -> array: @@ -182,7 +182,7 @@ def sum(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtyp data type of the returned array. If ``None``, - if the default data type corresponding to the data type "kind" (integer or floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - if ``x`` has a floating-point data type, the returned array must have the default floating-point data type. + - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). @@ -214,7 +214,7 @@ def var(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a real-valued floating-point data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which variances must be computed. By default, the variance must be computed over the entire array. If a tuple of integers, variances must be computed over multiple axes. Default: ``None``. correction: Union[int, float] @@ -229,7 +229,7 @@ def var(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr .. note:: - While this specification recommends that this function only accept input arrays having a floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default floating-point data type. + While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ __all__ = ['max', 'mean', 'min', 'prod', 'std', 'sum', 'var'] From 5ee1efbdd5e071b0e24cc1c4106241616c356ef2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 22 May 2022 15:39:27 -0700 Subject: [PATCH 5/5] Fix underline --- spec/API_specification/data_types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/data_types.rst b/spec/API_specification/data_types.rst index 5d42dcc5b..f27fdd445 100644 --- a/spec/API_specification/data_types.rst +++ b/spec/API_specification/data_types.rst @@ -165,7 +165,7 @@ Floating-point Data Types ``float32``, ``float64``, ``complex64``, and ``complex128``. Real-valued Floating-point Data Types -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``float32`` and ``float64``.