From 8944a5f78bd8eb46a9a306a1a4a200b7f603ce83 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 10 Dec 2024 17:31:44 +0200 Subject: [PATCH 1/4] DOC: italicize RFC magic must/must not, should/should not $ sed -E -i "/not/! s/must/\*must\*/g" ./*.rst $ sed -E -i "s/must not/\*must not\*/g" ./*.rst $ sed -E -i "/not/! s/should/\*should\*/g" ./*.rst etc --- spec/draft/API_specification/array_object.rst | 38 +++++------ spec/draft/API_specification/broadcasting.rst | 4 +- spec/draft/API_specification/constants.rst | 4 +- .../API_specification/creation_functions.rst | 2 +- .../API_specification/data_type_functions.rst | 2 +- spec/draft/API_specification/data_types.rst | 22 +++---- .../function_and_method_signatures.rst | 4 +- spec/draft/API_specification/index.rst | 16 ++--- spec/draft/API_specification/indexing.rst | 64 +++++++++---------- .../API_specification/indexing_functions.rst | 2 +- spec/draft/API_specification/inspection.rst | 4 +- .../linear_algebra_functions.rst | 2 +- .../manipulation_functions.rst | 2 +- .../API_specification/searching_functions.rst | 2 +- .../draft/API_specification/set_functions.rst | 2 +- .../API_specification/sorting_functions.rst | 4 +- .../statistical_functions.rst | 2 +- .../API_specification/type_promotion.rst | 6 +- .../API_specification/utility_functions.rst | 2 +- spec/draft/API_specification/version.rst | 2 +- spec/draft/design_topics/C_API.rst | 2 +- spec/draft/design_topics/accuracy.rst | 4 +- spec/draft/design_topics/complex_numbers.rst | 6 +- .../copies_views_and_mutation.rst | 4 +- spec/draft/design_topics/data_interchange.rst | 12 ++-- spec/draft/design_topics/device_support.rst | 2 +- spec/draft/design_topics/exceptions.rst | 6 +- spec/draft/design_topics/static_typing.rst | 4 +- .../fourier_transform_functions.rst | 6 +- spec/draft/extensions/index.rst | 8 +-- .../extensions/linear_algebra_functions.rst | 20 +++--- 31 files changed, 130 insertions(+), 130 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index f8a586ade..7490f1a08 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -5,12 +5,12 @@ Array object Array API specification for array object attributes and methods. -A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods. +A conforming implementation of the array API standard *must* provide and support an array object having the following attributes and methods. -Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and must explicitly document their maximum supported rank ``N``. +Furthermore, a conforming implementation of the array API standard *must* support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and *must* explicitly document their maximum supported rank ``N``. .. note:: - Conforming implementations must support zero-dimensional arrays. + Conforming implementations *must* support zero-dimensional arrays. Apart from array object attributes, such as ``ndim``, ``device``, and ``dtype``, all operations in this standard return arrays (or tuples of arrays), including those operations, such as ``mean``, ``var``, and ``std``, from which some common array libraries (e.g., NumPy) return scalar values. @@ -23,12 +23,12 @@ Furthermore, a conforming implementation of the array API standard must support, Operators --------- -A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python operators. Arithmetic Operators ~~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following Python arithmetic operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python arithmetic operators. - ``+x``: :meth:`.array.__pos__` @@ -75,24 +75,24 @@ 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 real-valued data types. +Arithmetic operators *should* be defined for arrays having real-valued data types. Array Operators ~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following Python array operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python array operators. - `x1 @ x2`: :meth:`.array.__matmul__` - `operator.matmul(x1, x2) `_ - `operator.__matmul__(x1, x2) `_ -The matmul ``@`` operator should be defined for arrays having real-valued data types. +The matmul ``@`` operator *should* be defined for arrays having real-valued data types. Bitwise Operators ~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following Python bitwise operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python bitwise operators. - `~x`: :meth:`.array.__invert__` @@ -126,12 +126,12 @@ A conforming implementation of the array API standard must provide and support a - `operator.rshift(x1, x2) `_ - `operator.__rshift__(x1, x2) `_ -Bitwise operators should be defined for arrays having integer and boolean data types. +Bitwise operators *should* be defined for arrays having integer and boolean data types. Comparison Operators ~~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following Python comparison operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python comparison operators. - `x1 < x2`: :meth:`.array.__lt__` @@ -163,20 +163,20 @@ A conforming implementation of the array API standard must provide and support a - `operator.ne(x1, x2) `_ - `operator.__ne__(x1, x2) `_ -:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type. +:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators *should* be defined for arrays having any data type. For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). In-place Operators ~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following in-place Python operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following in-place Python operators. -An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. +An in-place operation *must not* change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. -An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. +An in-place operation *must* have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` *must* always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. .. note:: - In-place operators must be supported as discussed in :ref:`copyview-mutability`. + In-place operators *must* be supported as discussed in :ref:`copyview-mutability`. Arithmetic Operators """""""""""""""""""" @@ -206,12 +206,12 @@ Bitwise Operators Reflected Operators ~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following reflected operators. +A conforming implementation of the array API standard *must* provide and support an array object supporting the following reflected operators. -The results of applying reflected operators must match their non-reflected equivalents. +The results of applying reflected operators *must* match their non-reflected equivalents. .. note:: - All operators for which ``array scalar`` is implemented must have an equivalent reflected operator implementation. + All operators for which ``array scalar`` is implemented *must* have an equivalent reflected operator implementation. Arithmetic Operators """""""""""""""""""" diff --git a/spec/draft/API_specification/broadcasting.rst b/spec/draft/API_specification/broadcasting.rst index abb3ed222..9522f74ac 100644 --- a/spec/draft/API_specification/broadcasting.rst +++ b/spec/draft/API_specification/broadcasting.rst @@ -19,7 +19,7 @@ Given an element-wise operation involving two compatible arrays, an array having If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank. -The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm. +The results of the element-wise operation *must* be stored in an array having a shape determined by the following algorithm. #. Let ``A`` and ``B`` both be arrays. @@ -112,7 +112,7 @@ The following examples demonstrate array shapes which do **not** broadcast. In-place Semantics ------------------ -As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) must not change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed. +As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) *must not* change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed. For example: diff --git a/spec/draft/API_specification/constants.rst b/spec/draft/API_specification/constants.rst index 71cb8688d..822ffa1c4 100644 --- a/spec/draft/API_specification/constants.rst +++ b/spec/draft/API_specification/constants.rst @@ -3,9 +3,9 @@ Constants Array API specification for constants. -A conforming implementation of the array API standard must provide and support the following constants adhering to the following conventions. +A conforming implementation of the array API standard *must* provide and support the following constants adhering to the following conventions. -- Each constant must have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value. +- Each constant *must* have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value. Objects in API -------------- diff --git a/spec/draft/API_specification/creation_functions.rst b/spec/draft/API_specification/creation_functions.rst index ff5c06368..6a9728f45 100644 --- a/spec/draft/API_specification/creation_functions.rst +++ b/spec/draft/API_specification/creation_functions.rst @@ -3,7 +3,7 @@ Creation Functions Array API specification for creating arrays. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/data_type_functions.rst b/spec/draft/API_specification/data_type_functions.rst index d42968c7b..1a35292dd 100644 --- a/spec/draft/API_specification/data_type_functions.rst +++ b/spec/draft/API_specification/data_type_functions.rst @@ -3,7 +3,7 @@ Data Type Functions Array API specification for data type functions. -A conforming implementation of the array API standard must provide and support the following data type functions. +A conforming implementation of the array API standard *must* provide and support the following data type functions. Objects in API diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index 5987dd322..f86a70bd8 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -5,7 +5,7 @@ Data Types Array API specification for supported data types. -A conforming implementation of the array API standard must provide and support +A conforming implementation of the array API standard *must* provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: @@ -34,12 +34,12 @@ objects in its main namespace under the specified names: +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex64 | 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). | +| complex64 | 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). | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex128 | 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). | +| complex128 | 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). | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -Data type objects must have the following methods (no attributes are required): +Data type objects *must* have the following methods (no attributes are required): .. NOTE: please keep the functions in alphabetical order @@ -89,28 +89,28 @@ See :ref:`type-promotion` for specification guidance describing the rules govern Default Data Types ------------------ -A conforming implementation of the array API standard must define the following default data types. +A conforming implementation of the array API standard *must* define the following default data types. - 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 real-valued 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 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 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. +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. -The default array index data type may be ``int32`` on 32-bit platforms, but the default should be ``int64`` otherwise. +The default array index data type may be ``int32`` on 32-bit platforms, but the default *should* be ``int64`` otherwise. Note that it is possible that a library supports multiple devices, with not all those device types supporting the same data types. In this case, the default integer or floating-point data types may vary with device. If that is the case, -the library should clearly warn about this in its documentation. +the library *should* clearly warn about this in its documentation. .. note:: - The default data types should be clearly defined in a conforming library's documentation. + The default data types *should* be clearly defined in a conforming library's documentation. .. _data-type-categories: diff --git a/spec/draft/API_specification/function_and_method_signatures.rst b/spec/draft/API_specification/function_and_method_signatures.rst index 0eca2ac69..ac4fc9acc 100644 --- a/spec/draft/API_specification/function_and_method_signatures.rst +++ b/spec/draft/API_specification/function_and_method_signatures.rst @@ -5,7 +5,7 @@ Function and method signatures Function signatures in this standard adhere to the following: -1. Positional parameters should be `positional-only `_ parameters. +1. Positional parameters *should* be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. @@ -20,7 +20,7 @@ Function signatures in this standard adhere to the following: namespace >= 3.8. Alternatively, they can add guidance to their users in the documentation to use the functions as if they were positional-only. -2. Optional parameters should be `keyword-only `_ arguments. +2. Optional parameters *should* be `keyword-only `_ arguments. *Rationale: this leads to more readable code, and it makes it easier to evolve an API over time by adding keywords without having to worry about diff --git a/spec/draft/API_specification/index.rst b/spec/draft/API_specification/index.rst index ffc3d3775..26e60e470 100644 --- a/spec/draft/API_specification/index.rst +++ b/spec/draft/API_specification/index.rst @@ -3,16 +3,16 @@ API specification ================= -A conforming implementation of the array API standard must provide and support the APIs and behavior detailed in this specification while adhering to the following conventions. +A conforming implementation of the array API standard *must* provide and support the APIs and behavior detailed in this specification while adhering to the following conventions. -- When a function signature includes a `/`, positional parameters must be `positional-only `_ parameters. See :ref:`function-and-method-signatures`. -- When a function signature includes a `*`, optional parameters must be `keyword-only `_ arguments. See :ref:`function-and-method-signatures`. -- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. +- When a function signature includes a `/`, positional parameters *must* be `positional-only `_ parameters. See :ref:`function-and-method-signatures`. +- When a function signature includes a `*`, optional parameters *must* be `keyword-only `_ arguments. See :ref:`function-and-method-signatures`. +- Broadcasting semantics *must* follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions *must* support the data types defined in :ref:`data-types`. - Functions may only be required for a subset of input data types. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. -- Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`. +- Unless stated otherwise, functions *must* adhere to the type promotion rules defined in :ref:`type-promotion`. +- Unless stated otherwise, floating-point operations *must* adhere to IEEE 754-2019. +- Unless stated otherwise, element-wise mathematical functions *must* satisfy the minimum accuracy requirements defined in :ref:`accuracy`. .. toctree:: diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index eb61c26d5..6a60382d4 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -5,35 +5,35 @@ Indexing Array API specification for indexing arrays. -A conforming implementation of the array API standard must adhere to the following conventions. +A conforming implementation of the array API standard *must* adhere to the following conventions. Single-axis Indexing -------------------- -To index a single array axis, an array must support standard Python indexing rules. Let ``n`` be the axis (dimension) size. +To index a single array axis, an array *must* support standard Python indexing rules. Let ``n`` be the axis (dimension) size. -- An integer index must be an object satisfying `operator.index `_ (e.g., ``int``). +- An integer index *must* be an object satisfying `operator.index `_ (e.g., ``int``). -- Nonnegative indices must start at ``0`` (i.e., zero-based indexing). +- Nonnegative indices *must* start at ``0`` (i.e., zero-based indexing). -- **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``. +- **Valid** nonnegative indices *must* reside on the half-open interval ``[0, n)``. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. -- Negative indices must count backward from the last array index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last array index). +- Negative indices *must* count backward from the last array index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last array index). .. note:: A negative index ``j`` is equivalent to ``n-j``; the former is syntactic sugar for the latter, providing a shorthand for indexing elements that would otherwise need to be specified in terms of the axis (dimension) size. -- **Valid** negative indices must reside on the closed interval ``[-n, -1]``. +- **Valid** negative indices *must* reside on the closed interval ``[-n, -1]``. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``. -- Colons ``:`` must be used for `slices `_: ``start:stop:step``, where ``start`` is inclusive and ``stop`` is exclusive. +- Colons ``:`` *must* be used for `slices `_: ``start:stop:step``, where ``start`` is inclusive and ``stop`` is exclusive. .. note:: The specification does not support returning scalar (i.e., non-array) values from operations, including indexing. In contrast to standard Python indexing rules, for any index, or combination of indices, which select a single value, the result must be a zero-dimensional array containing the selected value. @@ -62,7 +62,7 @@ The basic slice syntax is ``i:j:k`` where ``i`` is the starting index, ``j`` is .. note:: Slice syntax can be equivalently achieved using the Python built-in `slice() `_ API. From the perspective of ``A``, the behavior of ``A[i:j:k]`` and ``A[slice(i, j, k)]`` is indistinguishable (i.e., both retrieve the same set of items from ``__getitem__``). -Using a slice to index a single array axis must select ``m`` elements with index values +Using a slice to index a single array axis *must* select ``m`` elements with index values :: @@ -90,9 +90,9 @@ such that For ``i`` on the interval ``[0, n)`` (where ``n`` is the axis size), ``j`` on the interval ``(0, n]``, ``i`` less than ``j``, and positive step ``k``, a starting index ``i`` is **always** included, while the stopping index ``j`` is **always** excluded. This preserves ``x[:i]+x[i:]`` always being equal to ``x``. .. note:: - Using a slice to index into a single array axis should select the same elements as using a slice to index a Python list of the same size. + Using a slice to index into a single array axis *should* select the same elements as using a slice to index a Python list of the same size. -Slice syntax must have the following defaults. Let ``n`` be the axis (dimension) size. +Slice syntax *must* have the following defaults. Let ``n`` be the axis (dimension) size. - If ``k`` is not provided (e.g., ``0:10``), ``k`` must equal ``1``. - If ``k`` is greater than ``0`` and ``i`` is not provided (e.g., ``:10:2``), ``i`` must equal ``0``. @@ -100,16 +100,16 @@ Slice syntax must have the following defaults. Let ``n`` be the axis (dimension) - If ``k`` is less than ``0`` and ``i`` is not provided (e.g., ``:10:-2``), ``i`` must equal ``n-1``. - If ``k`` is less than ``0`` and ``j`` is not provided (e.g., ``0::-2``), ``j`` must equal ``-n-1``. -Using a slice to index a single array axis must adhere to the following rules. Let ``n`` be the axis (dimension) size. +Using a slice to index a single array axis *must* adhere to the following rules. Let ``n`` be the axis (dimension) size. -- If ``i`` equals ``j``, a slice must return an empty array, whose axis (dimension) size along the indexed axis is ``0``. +- If ``i`` equals ``j``, a slice *must* return an empty array, whose axis (dimension) size along the indexed axis is ``0``. -- Indexing via ``:`` and ``::`` must be equivalent and have defaults derived from the rules above. Both ``:`` and ``::`` indicate to select all elements along a single axis (dimension). +- Indexing via ``:`` and ``::`` *must* be equivalent and have defaults derived from the rules above. Both ``:`` and ``::`` indicate to select all elements along a single axis (dimension). .. note:: This specification does not require "clipping" out-of-bounds slice indices. This is in contrast to Python slice semantics where ``0:100`` and ``0:10`` are equivalent on a list of length ``10``. -The following ranges for the start and stop values of a slice must be supported. Let ``n`` be the axis (dimension) size being sliced. For a slice ``i:j:k``, the behavior specified above should be implemented for the following: +The following ranges for the start and stop values of a slice *must* be supported. Let ``n`` be the axis (dimension) size being sliced. For a slice ``i:j:k``, the behavior specified above *should* be implemented for the following: - ``i`` or ``j`` omitted (``None``). - ``-n <= i <= n``. @@ -124,34 +124,34 @@ The behavior outside of these bounds is unspecified. Multi-axis Indexing ------------------- -Multi-dimensional arrays must extend the concept of single-axis indexing to multiple axes by applying single-axis indexing rules along each axis (dimension) and supporting the following additional rules. Let ``N`` be the number of dimensions ("rank") of a multi-dimensional array ``A``. +Multi-dimensional arrays *must* extend the concept of single-axis indexing to multiple axes by applying single-axis indexing rules along each axis (dimension) and supporting the following additional rules. Let ``N`` be the number of dimensions ("rank") of a multi-dimensional array ``A``. - Each axis may be independently indexed via single-axis indexing by providing a comma-separated sequence ("selection tuple") of single-axis indexing expressions (e.g., ``A[:, 2:10, :, 5]``). .. note:: In Python, ``A[(exp1, exp2, ..., expN)]`` is equivalent to ``A[exp1, exp2, ..., expN]``; the latter is syntactic sugar for the former. - Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` must be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` must be equivalent to ``A[2:10, :]``. And so on and so forth. + Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` *must* be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` *must* be equivalent to ``A[2:10, :]``. And so on and so forth. -- Providing a single nonnegative integer ``i`` as a single-axis index must index the same elements as the slice ``i:i+1``. +- Providing a single nonnegative integer ``i`` as a single-axis index *must* index the same elements as the slice ``i:i+1``. -- Providing a single negative integer ``i`` as a single-axis index must index the same elements as the slice ``n+i:n+i+1``, where ``n`` is the axis (dimension) size. +- Providing a single negative integer ``i`` as a single-axis index *must* index the same elements as the slice ``n+i:n+i+1``, where ``n`` is the axis (dimension) size. -- Providing a single integer as a single-axis index must reduce the number of array dimensions by ``1`` (i.e., the array rank must decrease by one; if ``A`` has rank ``2``, ``rank(A)-1 == rank(A[0, :])``). In particular, a selection tuple with the ``m``\th element an integer (and all other entries ``:``) indexes a sub-array with rank ``N-1``. +- Providing a single integer as a single-axis index *must* reduce the number of array dimensions by ``1`` (i.e., the array rank *must* decrease by one; if ``A`` has rank ``2``, ``rank(A)-1 == rank(A[0, :])``). In particular, a selection tuple with the ``m``\th element an integer (and all other entries ``:``) indexes a sub-array with rank ``N-1``. .. note:: When providing a single integer as a single-axis index to an array of rank ``1``, the result should be an array of rank ``0``, not a NumPy scalar. Note that this behavior differs from NumPy. -- Providing a slice must retain array dimensions (i.e., the array rank must remain the same; ``rank(A) == rank(A[:])``). +- Providing a slice *must* retain array dimensions (i.e., the array rank *must* remain the same; ``rank(A) == rank(A[:])``). -- Providing `ellipsis `_ must apply ``:`` to each dimension necessary to index all dimensions (e.g., if ``A`` has rank ``4``, ``A[1:, ..., 2:5] == A[1:, :, :, 2:5]``). Only a single ellipsis must be allowed. An ``IndexError`` exception must be raised if more than one ellipsis is provided. +- Providing `ellipsis `_ *must* apply ``:`` to each dimension necessary to index all dimensions (e.g., if ``A`` has rank ``4``, ``A[1:, ..., 2:5] == A[1:, :, :, 2:5]``). Only a single ellipsis *must* be allowed. An ``IndexError`` exception *must* be raised if more than one ellipsis is provided. -- Providing an empty tuple or an ellipsis to an array of rank ``0`` must result in an array of the same rank (i.e., if ``A`` has rank ``0``, ``A == A[()]`` and ``A == A[...]``). +- Providing an empty tuple or an ellipsis to an array of rank ``0`` *must* result in an array of the same rank (i.e., if ``A`` has rank ``0``, ``A == A[()]`` and ``A == A[...]``). .. note:: This behavior differs from NumPy where providing an empty tuple to an array of rank ``0`` returns a NumPy scalar. -- Each ``None`` in the selection tuple must expand the dimensions of the resulting selection by one dimension of size ``1``. The position of the added dimension must be the same as the position of ``None`` in the selection tuple. +- Each ``None`` in the selection tuple *must* expand the dimensions of the resulting selection by one dimension of size ``1``. The position of the added dimension *must* be the same as the position of ``None`` in the selection tuple. .. note:: Expanding dimensions can be equivalently achieved via repeated invocation of :func:`~array_api.expand_dims`. @@ -159,14 +159,14 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult .. note:: The constant ``newaxis`` is an alias of ``None`` and can thus be used in a similar manner as ``None``. -- Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) should equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression should be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception should be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``. +- Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) *should* equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression *should* be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception *should* be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``. .. note:: Some libraries, such as SymPy, support flat indexing (i.e., providing a single-axis indexing expression to a higher-dimensional array). That practice is not supported here. To perform flat indexing, use ``reshape(x, (-1,))[integer]``. -- An ``IndexError`` exception must be raised if the number of provided single-axis indexing expressions (excluding ``None``) is greater than ``N``. +- An ``IndexError`` exception *must* be raised if the number of provided single-axis indexing expressions (excluding ``None``) is greater than ``N``. .. note:: This specification leaves unspecified the behavior of providing a slice which attempts to select elements along a particular axis, but whose starting index is out-of-bounds. @@ -181,28 +181,28 @@ Boolean Array Indexing For common boolean array use cases (e.g., using a dynamically-sized boolean array mask to filter the values of another array), the shape of the output array is data-dependent; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find boolean array indexing difficult to implement. Accordingly, such libraries may choose to omit boolean array indexing. See :ref:`data-dependent-output-shapes` section for more details. -An array must support indexing where the **sole index** is an ``M``-dimensional boolean array ``B`` with shape ``S1 = (s1, ..., sM)`` according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S2 = (s1, ..., sM, ..., sN)``. +An array *must* support indexing where the **sole index** is an ``M``-dimensional boolean array ``B`` with shape ``S1 = (s1, ..., sM)`` according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S2 = (s1, ..., sM, ..., sN)``. .. note:: The prohibition against combining boolean array indices with other single-axis indexing expressions includes the use of ``None``. To expand dimensions of the returned array, use repeated invocation of :func:`~array_api.expand_dims`. -- If ``N >= M``, then ``A[B]`` must replace the first ``M`` dimensions of ``A`` with a single dimension having a size equal to the number of ``True`` elements in ``B``. The values in the resulting array must be in row-major (C-style order); this is equivalent to ``A[nonzero(B)]``. +- If ``N >= M``, then ``A[B]`` *must* replace the first ``M`` dimensions of ``A`` with a single dimension having a size equal to the number of ``True`` elements in ``B``. The values in the resulting array *must* be in row-major (C-style order); this is equivalent to ``A[nonzero(B)]``. .. note:: For example, if ``N == M == 2``, indexing ``A`` via a boolean array ``B`` will return a one-dimensional array whose size is equal to the number of ``True`` elements in ``B``. -- If ``N < M``, then an ``IndexError`` exception must be raised. +- If ``N < M``, then an ``IndexError`` exception *must* be raised. - The size of each dimension in ``B`` must equal the size of the corresponding dimension in ``A`` or be ``0``, beginning with the first dimension in ``A``. If a dimension size does not equal the size of the corresponding dimension in ``A`` and is not ``0``, then an ``IndexError`` exception must be raised. -- The elements of a boolean index array must be iterated in row-major, C-style order, with the exception of zero-dimensional boolean arrays. +- The elements of a boolean index array *must* be iterated in row-major, C-style order, with the exception of zero-dimensional boolean arrays. -- A zero-dimensional boolean index array (equivalent to ``True`` or ``False``) must follow the same axis replacement rules stated above. Namely, a zero-dimensional boolean index array removes zero dimensions and adds a single dimension of length ``1`` if the index array's value is ``True`` and of length ``0`` if the index array's value is ``False``. Accordingly, for a zero-dimensional boolean index array ``B``, the result of ``A[B]`` has shape ``S = (1, s1, ..., sN)`` if the index array's value is ``True`` and has shape ``S = (0, s1, ..., sN)`` if the index array's value is ``False``. +- A zero-dimensional boolean index array (equivalent to ``True`` or ``False``) *must* follow the same axis replacement rules stated above. Namely, a zero-dimensional boolean index array removes zero dimensions and adds a single dimension of length ``1`` if the index array's value is ``True`` and of length ``0`` if the index array's value is ``False``. Accordingly, for a zero-dimensional boolean index array ``B``, the result of ``A[B]`` has shape ``S = (1, s1, ..., sN)`` if the index array's value is ``True`` and has shape ``S = (0, s1, ..., sN)`` if the index array's value is ``False``. Return Values ------------- -The result of an indexing operation (e.g., multi-axis indexing, boolean array indexing, etc) must be an array of the same data type as the indexed array. +The result of an indexing operation (e.g., multi-axis indexing, boolean array indexing, etc) *must* be an array of the same data type as the indexed array. .. note:: The specified return value behavior includes indexing operations which return a single value (e.g., accessing a single element within a one-dimensional array). diff --git a/spec/draft/API_specification/indexing_functions.rst b/spec/draft/API_specification/indexing_functions.rst index c13e55ecf..bae575ce9 100644 --- a/spec/draft/API_specification/indexing_functions.rst +++ b/spec/draft/API_specification/indexing_functions.rst @@ -5,7 +5,7 @@ Indexing Functions Array API specification for functions for indexing arrays. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/inspection.rst b/spec/draft/API_specification/inspection.rst index 89d9c602a..a28c7c37d 100644 --- a/spec/draft/API_specification/inspection.rst +++ b/spec/draft/API_specification/inspection.rst @@ -5,7 +5,7 @@ Inspection Array API specification for namespace inspection utilities. -A conforming implementation of the array API standard must provide and support the following functions and associated inspection APIs. +A conforming implementation of the array API standard *must* provide and support the following functions and associated inspection APIs. Objects in API @@ -26,7 +26,7 @@ Objects in API Inspection APIs --------------- -In the namespace (or class) returned by ``__array_namespace_info__``, a conforming implementation of the array API standard must provide and support the following functions (or methods) for programmatically querying data type and device support, capabilities, and other specification-defined implementation-specific behavior, as documented in the functions described below. +In the namespace (or class) returned by ``__array_namespace_info__``, a conforming implementation of the array API standard *must* provide and support the following functions (or methods) for programmatically querying data type and device support, capabilities, and other specification-defined implementation-specific behavior, as documented in the functions described below. .. NOTE: please keep the functions in alphabetical order diff --git a/spec/draft/API_specification/linear_algebra_functions.rst b/spec/draft/API_specification/linear_algebra_functions.rst index 04d36f50a..670cbdc24 100644 --- a/spec/draft/API_specification/linear_algebra_functions.rst +++ b/spec/draft/API_specification/linear_algebra_functions.rst @@ -3,7 +3,7 @@ Linear Algebra Functions Array API specification for linear algebra functions. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. .. currentmodule:: array_api diff --git a/spec/draft/API_specification/manipulation_functions.rst b/spec/draft/API_specification/manipulation_functions.rst index 395c1c3e2..bb7d00711 100644 --- a/spec/draft/API_specification/manipulation_functions.rst +++ b/spec/draft/API_specification/manipulation_functions.rst @@ -3,7 +3,7 @@ Manipulation Functions Array API specification for manipulating arrays. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/searching_functions.rst b/spec/draft/API_specification/searching_functions.rst index 1a584f158..0c5d8b696 100644 --- a/spec/draft/API_specification/searching_functions.rst +++ b/spec/draft/API_specification/searching_functions.rst @@ -5,7 +5,7 @@ Searching Functions Array API specification for functions for searching arrays. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/set_functions.rst b/spec/draft/API_specification/set_functions.rst index addf31e1f..c7e027eaa 100644 --- a/spec/draft/API_specification/set_functions.rst +++ b/spec/draft/API_specification/set_functions.rst @@ -3,7 +3,7 @@ Set Functions Array API specification for creating and operating on sets. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/sorting_functions.rst b/spec/draft/API_specification/sorting_functions.rst index ad3af8857..d19527612 100644 --- a/spec/draft/API_specification/sorting_functions.rst +++ b/spec/draft/API_specification/sorting_functions.rst @@ -3,7 +3,7 @@ Sorting Functions Array API specification for sorting functions. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. .. note:: @@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t Implementations may choose to sort signed zeros (``-0 < +0``) or may choose to rely solely on value equality (``==``). - Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention should be clearly documented in the conforming implementation's documentation. + Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention *should* be clearly documented in the conforming implementation's documentation. While defining a sort order for IEEE 754 floating-point numbers is recommended in order to facilitate reproducible and consistent sort results, doing so is not currently required by this specification. diff --git a/spec/draft/API_specification/statistical_functions.rst b/spec/draft/API_specification/statistical_functions.rst index eb5e1a5d6..5e981251b 100644 --- a/spec/draft/API_specification/statistical_functions.rst +++ b/spec/draft/API_specification/statistical_functions.rst @@ -3,7 +3,7 @@ Statistical Functions Array API specification for statistical functions. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/type_promotion.rst b/spec/draft/API_specification/type_promotion.rst index 339b90e45..00248e473 100644 --- a/spec/draft/API_specification/type_promotion.rst +++ b/spec/draft/API_specification/type_promotion.rst @@ -15,7 +15,7 @@ Type promotion rules can be understood at a high level from the following diagra Rules ----- -A conforming implementation of the array API standard must implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation. +A conforming implementation of the array API standard *must* implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation. A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification. @@ -114,7 +114,7 @@ where Notes ~~~~~ -- Type promotion rules must apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays must be subject to the same type promotion rules as dimensional arrays. +- Type promotion rules *must* apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays *must* be subject to the same type promotion rules as dimensional arrays. - Type promotion of non-numerical data types to numerical data types is unspecified (e.g., ``bool`` to ``intxx`` or ``floatxx``). .. note:: @@ -123,7 +123,7 @@ Notes Mixing arrays with Python scalars ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using Python scalars (i.e., instances of ``bool``, ``int``, ``float``, ``complex``) together with arrays must be supported for: +Using Python scalars (i.e., instances of ``bool``, ``int``, ``float``, ``complex``) together with arrays *must* be supported for: - ``array scalar`` - ``scalar array`` diff --git a/spec/draft/API_specification/utility_functions.rst b/spec/draft/API_specification/utility_functions.rst index a09c99f79..084da845a 100644 --- a/spec/draft/API_specification/utility_functions.rst +++ b/spec/draft/API_specification/utility_functions.rst @@ -3,7 +3,7 @@ Utility Functions Array API specification for utility functions. -A conforming implementation of the array API standard must provide and support the following functions. +A conforming implementation of the array API standard *must* provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/version.rst b/spec/draft/API_specification/version.rst index 346395d9a..289a0c216 100644 --- a/spec/draft/API_specification/version.rst +++ b/spec/draft/API_specification/version.rst @@ -3,7 +3,7 @@ Version Array API specification for versioning. -A conforming implementation of the array API standard must provide a `__array_api_version__` attribute - see :ref:`api-versioning` for details. +A conforming implementation of the array API standard *must* provide a `__array_api_version__` attribute - see :ref:`api-versioning` for details. Objects in API diff --git a/spec/draft/design_topics/C_API.rst b/spec/draft/design_topics/C_API.rst index 6a44596b0..388eab5da 100644 --- a/spec/draft/design_topics/C_API.rst +++ b/spec/draft/design_topics/C_API.rst @@ -19,7 +19,7 @@ to the supported array type. Often a zero-copy conversion to ``numpy.ndarray`` is possible, at least for CPU arrays. If that's the case, this may be a good way to support other array types. The main difficulty in that case will be getting the return array type right - however, - this standard does provide a Python-level API for array construction that should allow + this standard does provide a Python-level API for array construction that *should* allow doing this. A relevant question is if it's possible to know with certainty that a conversion will be zero-copy. This may indeed be possible, see :ref:`data-interchange`. diff --git a/spec/draft/design_topics/accuracy.rst b/spec/draft/design_topics/accuracy.rst index 61a2c49aa..5cc1d855a 100644 --- a/spec/draft/design_topics/accuracy.rst +++ b/spec/draft/design_topics/accuracy.rst @@ -23,7 +23,7 @@ including the corresponding element-wise array APIs defined in this standard - multiply - divide -for floating-point operands must return the nearest representable value according to IEEE 754-2019 and a supported rounding mode. By default, the rounding mode should be ``roundTiesToEven`` (i.e., round to nearest with ties rounded toward the nearest value with an even least significant bit). +for floating-point operands *must* return the nearest representable value according to IEEE 754-2019 and a supported rounding mode. By default, the rounding mode *should* be ``roundTiesToEven`` (i.e., round to nearest with ties rounded toward the nearest value with an even least significant bit). Mathematical Functions ---------------------- @@ -56,7 +56,7 @@ except to require specific results for certain argument values that represent bo .. note:: To help readers identify functions lacking precisely defined accuracy behavior, this specification uses the phrase "implementation-dependent approximation" in function descriptions. -For other argument values, these functions should compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. +For other argument values, these functions *should* compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in `FDLIBM `_, the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. diff --git a/spec/draft/design_topics/complex_numbers.rst b/spec/draft/design_topics/complex_numbers.rst index 0eca79e91..a76d12870 100644 --- a/spec/draft/design_topics/complex_numbers.rst +++ b/spec/draft/design_topics/complex_numbers.rst @@ -37,7 +37,7 @@ In contrast to real-valued floating-point numbers which have well-defined behavi Complex Number Ordering ----------------------- -Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties: +Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation *must* satisfy the following properties: 1. **Reflexive**: for any :math:`a` in the set, :math:`a \leq a`. 2. **Transitive**: for any :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b` and :math:`b \leq c`, then :math:`a \leq c`. @@ -50,7 +50,7 @@ Defining an order relation for complex numbers which satisfies all six propertie In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an ordering for complex numbers (e.g., lexicographic); however, consumers of the array API standard should **not** assume that complex number ordering is consistent between implementations or even supported. -If a conforming implementation chooses to define an ordering for complex numbers, the ordering must be clearly documented. +If a conforming implementation chooses to define an ordering for complex numbers, the ordering *must* be clearly documented. Valued-based Promotion @@ -58,4 +58,4 @@ Valued-based Promotion According to the type promotion rules described in this specification (see :ref:`type-promotion`), only the data types of the input arrays participating in an operation matter, not their values. The same principle applies to situations in which one or more results of operations on real-valued arrays are mathematically defined in the complex domain, but not in their real domain. -By convention, the principal square root of :math:`-1` is :math:`j`, where :math:`j` is the imaginary unit. Despite this convention, for those operations supporting type promotion, conforming implementations must only consider input array data types when determining the data type of the output array. For example, if a real-valued input array is provided to :func:`~array_api.sqrt`, the output array must also be real-valued, even if the input array contains negative values. Accordingly, if a consumer of a conforming implementation of this specification desires for an operation's results to include the complex domain, the consumer should first cast the input array(s) to an appropriate complex floating-point data type before performing the operation. +By convention, the principal square root of :math:`-1` is :math:`j`, where :math:`j` is the imaginary unit. Despite this convention, for those operations supporting type promotion, conforming implementations *must* only consider input array data types when determining the data type of the output array. For example, if a real-valued input array is provided to :func:`~array_api.sqrt`, the output array *must* also be real-valued, even if the input array contains negative values. Accordingly, if a consumer of a conforming implementation of this specification desires for an operation's results to include the complex domain, the consumer *should* first cast the input array(s) to an appropriate complex floating-point data type before performing the operation. diff --git a/spec/draft/design_topics/copies_views_and_mutation.rst b/spec/draft/design_topics/copies_views_and_mutation.rst index 1ca5a039c..36a44fe14 100644 --- a/spec/draft/design_topics/copies_views_and_mutation.rst +++ b/spec/draft/design_topics/copies_views_and_mutation.rst @@ -61,7 +61,7 @@ standard chooses to include them. The situation with ``out=`` is slightly different - it's less heavily used, and easier to avoid. It's also not an optimal API, because it mixes an "efficiency of implementation" consideration ("you're allowed to do this -inplace") with the semantics of a function ("the output _must_ be placed into +inplace") with the semantics of a function ("the output _*must*_ be placed into this array). There are libraries that do some form of tracing or abstract interpretation over a language that does not support mutation (to make analysis easier); in those cases implementing ``out=`` with correct handling of @@ -74,4 +74,4 @@ of reusing arrays that are no longer needed as buffers. This leaves the problem of the initial example - with this API standard it remains possible to write code that will not work the same for all array -libraries. This is something that the user must be careful about. +libraries. This is something that the user *must* be careful about. diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 3b3040672..37a1eb0f3 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -9,17 +9,17 @@ As discussed in the :ref:`assumptions-dependencies ` section, *array types* implemented by another library. Instead, the array can be converted to a "native" array type. -The interchange mechanism must offer the following: +The interchange mechanism *must* offer the following: 1. Data access via a protocol that describes the memory layout of the array in an implementation-independent manner. - *Rationale: any number of libraries must be able to exchange data, and no - particular package must be needed to do so.* + *Rationale: any number of libraries *must* be able to exchange data, and no + particular package *must* be needed to do so.* 2. Support for all dtypes in this API standard (see :ref:`data-types`). -3. Device support. It must be possible to determine on what device the array +3. Device support. It *must* be possible to determine on what device the array that is to be converted lives. *Rationale: there are CPU-only, GPU-only, and multi-device array types; @@ -57,7 +57,7 @@ support libraries that already implement buffer protocol support. (Python-side only at the moment) An issue with device-specific protocols are: if two libraries both - support multiple device types, in which order should the protocols be + support multiple device types, in which order *should* the protocols be tried? A growth in the number of protocols to support each time a new device gets supported by array libraries (e.g. TPUs, AMD GPUs, emerging hardware accelerators) also seems undesirable. @@ -67,7 +67,7 @@ support libraries that already implement buffer protocol support. being a lot older and standardized as part of Python itself via PEP 3118, hardly has any support from array libraries. CPU interoperability is mostly dealt with via the NumPy-specific ``__array__`` (which, when called, - means the object it is attached to must return a ``numpy.ndarray`` + means the object it is attached to *must* return a ``numpy.ndarray`` containing the data the object holds). See the `RFC to adopt DLPack `_ diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index 593b0b9fa..2b3079a0d 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -78,7 +78,7 @@ rather than hard requirements: - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function). - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices). - Use a default for ``device=None`` which is consistent between functions within the same library. -- If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority. For example: +- If a library has multiple ways of controlling device placement, the most explicit method *should* have the highest priority. For example: 1. If ``device=`` keyword is specified, that always takes precedence diff --git a/spec/draft/design_topics/exceptions.rst b/spec/draft/design_topics/exceptions.rst index 570fe56e3..e8ecd4f2a 100644 --- a/spec/draft/design_topics/exceptions.rst +++ b/spec/draft/design_topics/exceptions.rst @@ -18,11 +18,11 @@ ones. In specific cases, it may be useful to provide guidance to array library authors regarding what an appropriate exception is. That guidance will be -phrased as *should* rather than *must* (typically in a *Raises* section), +phrased as **should** rather than **must** (typically in a *Raises* section), because (a) there may be reasons for an implementer to deviate, and (b) more often than not, existing array library implementation already differ in their choices, and it may not be worth them breaking backward compatibility in order -to comply with a "must" in this standard. +to comply with a "*must*" in this standard. -In other cases, this standard will only specify that an exception should or +In other cases, this standard will only specify that an exception *should* or must be raised, but not mention what type of exception that is. diff --git a/spec/draft/design_topics/static_typing.rst b/spec/draft/design_topics/static_typing.rst index 26a1fb901..72834a126 100644 --- a/spec/draft/design_topics/static_typing.rst +++ b/spec/draft/design_topics/static_typing.rst @@ -39,12 +39,12 @@ should both be fine. There may be other variations possible. Also note that this standard does not require that input and output array types are the same (they're expected to be defined in the same library though). Given that array libraries don't have to be aware of other types of arrays defined in -other libraries (see :ref:`assumptions-dependencies`), this should be enough +other libraries (see :ref:`assumptions-dependencies`), this *should* be enough for a single array library. That said, an array-consuming library aiming to support multiple array types may need more - for example a protocol to enable structural subtyping. This API standard currently takes the position that it does not provide any -reference implementation or package that can or should be relied on at +reference implementation or package that can or *should* be relied on at runtime, hence no such protocol is defined here. This may be dealt with in a future version of this standard. diff --git a/spec/draft/extensions/fourier_transform_functions.rst b/spec/draft/extensions/fourier_transform_functions.rst index 170ae390b..d0882bb0a 100644 --- a/spec/draft/extensions/fourier_transform_functions.rst +++ b/spec/draft/extensions/fourier_transform_functions.rst @@ -6,9 +6,9 @@ Fourier transform Functions Extension name and usage ------------------------ -The name of the namespace providing the extension must be: ``fft``. +The name of the namespace providing the extension *must* be: ``fft``. -If implemented, this ``fft`` extension must be retrievable via:: +If implemented, this ``fft`` extension *must* be retrievable via:: >>> xp = x.__array_namespace__() >>> if hasattr(xp, 'fft'): @@ -18,7 +18,7 @@ If implemented, this ``fft`` extension must be retrievable via:: Objects in API -------------- -A conforming implementation of this ``fft`` extension must provide and support the following functions. +A conforming implementation of this ``fft`` extension *must* provide and support the following functions. .. currentmodule:: array_api.fft diff --git a/spec/draft/extensions/index.rst b/spec/draft/extensions/index.rst index 3b9409954..377fbeb3d 100644 --- a/spec/draft/extensions/index.rst +++ b/spec/draft/extensions/index.rst @@ -6,13 +6,13 @@ Extensions Extensions are coherent sets of functionality that are commonly implemented across array libraries. Each array library supporting this standard may, but is not required to, implement an extension. If an extension is supported, it -must be accessible inside the main array API supporting namespace as a separate +*must* be accessible inside the main array API supporting namespace as a separate namespace. -Extension module implementors must aim to provide all functions and other +Extension module implementors *must* aim to provide all functions and other public objects in an extension. The rationale for this is that downstream usage can then check whether or not the extension is present (using ``hasattr(xp, -'extension_name')`` should be enough), and can then assume that functions are +'extension_name')`` *should* be enough), and can then assume that functions are implemented. This in turn makes it also easy for array-consuming libraries to document which array libraries they support - e.g., "all libraries implementing the array API standard and its linear algebra extension". @@ -21,7 +21,7 @@ The mechanism through which the extension namespace is made available is up to the implementer, e.g. via a regular submodule that is imported under the ``linalg`` name, or via a module-level ``__getattr__``. -The functions in an extension must adhere to the same conventions as those in +The functions in an extension *must* adhere to the same conventions as those in the array API standard. See :ref:`api-specification`. ------------------------------------------------------------------------------ diff --git a/spec/draft/extensions/linear_algebra_functions.rst b/spec/draft/extensions/linear_algebra_functions.rst index 938221c79..abf5a590f 100644 --- a/spec/draft/extensions/linear_algebra_functions.rst +++ b/spec/draft/extensions/linear_algebra_functions.rst @@ -8,9 +8,9 @@ Linear Algebra Extension Extension name and usage ------------------------ -The name of the namespace providing the extension must be: ``linalg``. +The name of the namespace providing the extension *must* be: ``linalg``. -If implemented, this ``linalg`` extension must be retrievable via:: +If implemented, this ``linalg`` extension *must* be retrievable via:: >>> xp = x.__array_namespace__() >>> if hasattr(xp, 'linalg'): @@ -24,13 +24,13 @@ A principal goal of this specification is to standardize commonly implemented in Accordingly, the standardization process affords the opportunity to reduce interface complexity among linear algebra APIs by inferring and subsequently codifying common design themes, thus allowing more consistent APIs. What follows is the set of design principles governing the APIs which follow: -1. **Batching**: if an operation is explicitly defined in terms of matrices (i.e., two-dimensional arrays), then the associated interface should support "batching" (i.e., the ability to perform the operation over a "stack" of matrices). Example operations include: +1. **Batching**: if an operation is explicitly defined in terms of matrices (i.e., two-dimensional arrays), then the associated interface *should* support "batching" (i.e., the ability to perform the operation over a "stack" of matrices). Example operations include: - ``inv``: computing the multiplicative inverse of a square matrix. - ``cholesky``: performing Cholesky decomposition. - ``matmul``: performing matrix multiplication. -2. **Data types**: if an operation requires decimal operations and :ref:`type-promotion` semantics are undefined (e.g., as is the case for mixed-kind promotions), then the associated interface should be specified as being restricted to floating-point data types. While the specification uses the term "SHOULD" rather than "MUST", a conforming implementation of the array API standard should only ignore the restriction provided overly compelling reasons for doing so. Example operations which should be limited to floating-point data types include: +2. **Data types**: if an operation requires decimal operations and :ref:`type-promotion` semantics are undefined (e.g., as is the case for mixed-kind promotions), then the associated interface *should* be specified as being restricted to floating-point data types. While the specification uses the term "*SHOULD*" rather than "*MUST*", a conforming implementation of the array API standard *should* only ignore the restriction provided overly compelling reasons for doing so. Example operations which *should* be limited to floating-point data types include: - ``inv``: computing the multiplicative inverse. - ``slogdet``: computing the natural logarithm of the absolute value of the determinant. @@ -42,23 +42,23 @@ Accordingly, the standardization process affords the opportunity to reduce inter - ``trace``: computing the sum along the diagonal. - ``cross``: computing the vector cross product. - Lastly, certain operations may be performed independent of data type, and, thus, the associated interfaces should support all data types specified in this standard. Example operations include: + Lastly, certain operations may be performed independent of data type, and, thus, the associated interfaces *should* support all data types specified in this standard. Example operations include: - ``matrix_transpose``: computing the transpose. - ``diagonal``: returning the diagonal. -3. **Return values**: if an interface has more than one return value, the interface should return a namedtuple consisting of each value. +3. **Return values**: if an interface has more than one return value, the interface *should* return a namedtuple consisting of each value. In general, interfaces should avoid polymorphic return values (e.g., returning an array **or** a namedtuple, dependent on, e.g., an optional keyword argument). Dedicated interfaces for each return value type are preferred, as dedicated interfaces are easier to reason about at both the implementation level and user level. Example interfaces which could be combined into a single overloaded interface, but are not, include: - ``eigh``: computing both eigenvalues and eigenvectors. - ``eigvalsh``: computing only eigenvalues. -4. **Implementation agnosticism**: a standardized interface should eschew parameterization (including keyword arguments) biased toward particular implementations. +4. **Implementation agnosticism**: a standardized interface *should* eschew parameterization (including keyword arguments) biased toward particular implementations. - Historically, at a time when all array computing happened on CPUs, BLAS and LAPACK underpinned most numerical computing libraries and environments. Naturally, language and library abstractions catered to the parameterization of those libraries, often exposing low-level implementation details verbatim in their higher-level interfaces, even if such choices would be considered poor or ill-advised by today's standards (e.g., NumPy's use of `UPLO` in `eigh`). However, the present day is considerably different. While still important, BLAS and LAPACK no longer hold a monopoly over linear algebra operations, especially given the proliferation of devices and hardware on which such operations must be performed. Accordingly, interfaces must be conservative in the parameterization they support in order to best ensure universality. Such conservatism applies even to performance optimization parameters afforded by certain hardware. + Historically, at a time when all array computing happened on CPUs, BLAS and LAPACK underpinned most numerical computing libraries and environments. Naturally, language and library abstractions catered to the parameterization of those libraries, often exposing low-level implementation details verbatim in their higher-level interfaces, even if such choices would be considered poor or ill-advised by today's standards (e.g., NumPy's use of `UPLO` in `eigh`). However, the present day is considerably different. While still important, BLAS and LAPACK no longer hold a monopoly over linear algebra operations, especially given the proliferation of devices and hardware on which such operations *must* be performed. Accordingly, interfaces *must* be conservative in the parameterization they support in order to best ensure universality. Such conservatism applies even to performance optimization parameters afforded by certain hardware. -5. **Orthogonality**: an interface should have clearly defined and delineated functionality which, ideally, has no overlap with the functionality of other interfaces in the specification. Providing multiple interfaces which can all perform the same operation creates unnecessary confusion regarding interface applicability (i.e., which interface is best at which time) and decreases readability of both library and user code. Where overlap is possible, the specification must be parsimonious in the number of interfaces, ensuring that each interface provides a unique and compelling abstraction. Examples of related interfaces which provide distinct levels of abstraction (and generality) include: +5. **Orthogonality**: an interface *should* have clearly defined and delineated functionality which, ideally, has no overlap with the functionality of other interfaces in the specification. Providing multiple interfaces which can all perform the same operation creates unnecessary confusion regarding interface applicability (i.e., which interface is best at which time) and decreases readability of both library and user code. Where overlap is possible, the specification *must* be parsimonious in the number of interfaces, ensuring that each interface provides a unique and compelling abstraction. Examples of related interfaces which provide distinct levels of abstraction (and generality) include: - ``vecdot``: computing the dot product of two vectors. - ``matmul``: performing matrix multiplication (including between two vectors and thus the dot product). @@ -82,7 +82,7 @@ Accordingly, the standardization process affords the opportunity to reduce inter Objects in API -------------- -A conforming implementation of this ``linalg`` extension must provide and support the following functions. +A conforming implementation of this ``linalg`` extension *must* provide and support the following functions. .. NOTE: please keep the functions in alphabetical order From 0390ded35f57972eaac1001a00018e307b64fb91 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 10 Dec 2024 17:53:23 +0200 Subject: [PATCH 2/4] DOC: italicize should/must in stubs docstrings --- src/array_api_stubs/_draft/_types.py | 2 +- src/array_api_stubs/_draft/array_object.py | 182 ++++++------ .../_draft/creation_functions.py | 90 +++--- .../_draft/data_type_functions.py | 28 +- .../_draft/elementwise_functions.py | 258 +++++++++--------- src/array_api_stubs/_draft/fft.py | 168 ++++++------ .../_draft/indexing_functions.py | 10 +- src/array_api_stubs/_draft/info.py | 34 +-- src/array_api_stubs/_draft/linalg.py | 118 ++++---- .../_draft/linear_algebra_functions.py | 36 +-- .../_draft/manipulation_functions.py | 66 ++--- .../_draft/searching_functions.py | 34 +-- src/array_api_stubs/_draft/set_functions.py | 64 ++--- .../_draft/sorting_functions.py | 10 +- .../_draft/statistical_functions.py | 90 +++--- .../_draft/utility_functions.py | 32 +-- 16 files changed, 611 insertions(+), 611 deletions(-) diff --git a/src/array_api_stubs/_draft/_types.py b/src/array_api_stubs/_draft/_types.py index f2fa356f2..813a91212 100644 --- a/src/array_api_stubs/_draft/_types.py +++ b/src/array_api_stubs/_draft/_types.py @@ -1,7 +1,7 @@ """ Types for type annotations used in the array API standard. -The type variables should be replaced with the actual types for a given +The type variables *should* be replaced with the actual types for a given library, e.g., for NumPy TypeVar('array') would be replaced with ndarray. """ from __future__ import annotations diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 3c6fa8763..554d938e4 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -47,12 +47,12 @@ def mT(self: array) -> array: """ Transpose of a matrix (or a stack of matrices). - If an array instance has fewer than two dimensions, an error should be raised. + If an array instance has fewer than two dimensions, an error *should* be raised. Returns ------- out: array - array whose last two dimensions (axes) are permuted in reverse order relative to original array (i.e., for an array instance having shape ``(..., M, N)``, the returned array must have shape ``(..., N, M)``). The returned array must have the same data type as the original array. + array whose last two dimensions (axes) are permuted in reverse order relative to original array (i.e., for an array instance having shape ``(..., M, N)``, the returned array *must* have shape ``(..., N, M)``). The returned array *must* have the same data type as the original array. """ @property @@ -74,14 +74,14 @@ def shape(self: array) -> Tuple[Optional[int], ...]: Returns ------- out: Tuple[Optional[int], ...] - array dimensions. An array dimension must be ``None`` if and only if a dimension is unknown. + array dimensions. An array dimension *must* be ``None`` if and only if a dimension is unknown. .. note:: For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; ``A[:, B > 0]``) and thus cannot be statically resolved without knowing array contents. .. note:: - The returned value should be a tuple; however, where warranted, an array library may choose to return a custom shape object. If an array library returns a custom shape object, the object must be immutable, must support indexing for dimension retrieval, and must behave similarly to a tuple. + The returned value *should* be a tuple; however, where warranted, an array library may choose to return a custom shape object. If an array library returns a custom shape object, the object *must* be immutable, *must* support indexing for dimension retrieval, and *must* behave similarly to a tuple. """ @property @@ -90,12 +90,12 @@ def size(self: array) -> Optional[int]: Number of elements in an array. .. note:: - This must equal the product of the array's dimensions. + This *must* equal the product of the array's dimensions. Returns ------- out: Optional[int] - number of elements in an array. The returned value must be ``None`` if and only if one or more array dimensions are unknown. + number of elements in an array. The returned value *must* be ``None`` if and only if one or more array dimensions are unknown. .. note:: @@ -112,7 +112,7 @@ def T(self: array) -> array: Returns ------- out: array - two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array. + two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array *must* have the same data type as the original array. .. note:: @@ -136,13 +136,13 @@ def __abs__(self: array, /) -> array: Returns ------- out: array - an array containing the element-wise absolute value. If ``self`` has a real-valued data type, the returned array must have the same data type as ``self``. If ``self`` has a complex floating-point data type, the returned arrayed must have a real-valued floating-point data type whose precision matches the precision of ``self`` (e.g., if ``self`` is ``complex128``, then the returned array must have a ``float64`` data type). + an array containing the element-wise absolute value. If ``self`` has a real-valued data type, the returned array *must* have the same data type as ``self``. If ``self`` has a complex floating-point data type, the returned arrayed *must* have a real-valued floating-point data type whose precision matches the precision of ``self`` (e.g., if ``self`` is ``complex128``, then the returned array *must* have a ``float64`` data type). Notes ----- .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.abs`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.abs`. .. versionchanged:: 2022.12 Added complex data type support. @@ -162,13 +162,13 @@ def __add__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise sums. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.add`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.add`. .. versionchanged:: 2022.12 Added complex data type support. @@ -188,11 +188,11 @@ def __and__(self: array, other: Union[int, bool, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_and`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_and`. """ def __array_namespace__( @@ -211,7 +211,7 @@ def __array_namespace__( Returns ------- out: Any - an object representing the array API namespace. It should have every top-level function defined in the specification as an attribute. It may contain other public names as well, but it is recommended to only include those names that are part of the specification. + an object representing the array API namespace. It *should* have every top-level function defined in the specification as an attribute. It may contain other public names as well, but it is recommended to only include those names that are part of the specification. """ def __bool__(self: array, /) -> bool: @@ -239,7 +239,7 @@ def __bool__(self: array, /) -> bool: - If ``self`` is either ``+infinity`` or ``-infinity``, the result is ``True``. - If ``self`` is either ``+0`` or ``-0``, the result is ``False``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as the logical OR of ``bool(real(self))`` and ``bool(imag(self))``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as the logical OR of ``bool(real(self))`` and ``bool(imag(self))``. **Lazy implementations** @@ -310,7 +310,7 @@ def __dlpack__( self: array array instance. stream: Optional[Union[int, Any]] - for CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. ``stream`` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array (e.g., by inserting a dependency between streams via "wait for event"). The pointer must be an integer larger than or equal to ``-1`` (see below for allowed values on each platform). If ``stream`` is ``-1``, the value may be used by the consumer to signal "producer must not perform any synchronization". The ownership of the stream stays with the consumer. On CPU and other device types without streams, only ``None`` is accepted. + for CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. ``stream`` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array (e.g., by inserting a dependency between streams via "wait for event"). The pointer must be an integer larger than or equal to ``-1`` (see below for allowed values on each platform). If ``stream`` is ``-1``, the value may be used by the consumer to signal "producer *must not* perform any synchronization". The ownership of the stream stays with the consumer. On CPU and other device types without streams, only ``None`` is accepted. For other device types which do have a stream, queue, or similar synchronization/ordering mechanism, the most appropriate type to use for ``stream`` is not yet determined. E.g., for SYCL one may want to use an object containing an in-order ``cl::sycl::queue``. This is allowed when libraries agree on such a convention, and may be standardized in a future version of this API standard. @@ -319,7 +319,7 @@ def __dlpack__( Device-specific values of ``stream`` for CUDA: - - ``None``: producer must assume the legacy default stream (default). + - ``None``: producer *must* assume the legacy default stream (default). - ``1``: the legacy default stream. - ``2``: the per-thread default stream. - ``> 2``: stream number represented as a Python integer. @@ -327,15 +327,15 @@ def __dlpack__( Device-specific values of ``stream`` for ROCm: - - ``None``: producer must assume the legacy default stream (default). + - ``None``: producer *must* assume the legacy default stream (default). - ``0``: the default stream. - ``> 2``: stream number represented as a Python integer. - Using ``1`` and ``2`` is not supported. .. note:: - When ``dl_device`` is provided explicitly, ``stream`` must be a valid + When ``dl_device`` is provided explicitly, ``stream`` *must* be a valid construct for the specified device type. In particular, when ``kDLCPU`` - is in use, ``stream`` must be ``None`` and a synchronization must be + is in use, ``stream`` *must* be ``None`` and a synchronization *must* be performed to ensure data safety. .. admonition:: Tip @@ -351,36 +351,36 @@ def __dlpack__( ``__dlpack__``) supports, in the form of a 2-tuple ``(major, minor)``. This method may return a capsule of version ``max_version`` (recommended if it does support that), or of a different version. - This means the consumer must verify the version even when + This means the consumer *must* verify the version even when `max_version` is passed. dl_device: Optional[tuple[enum.Enum, int]] the DLPack device type. Default is ``None``, meaning the exported capsule - should be on the same device as ``self`` is. When specified, the format - must be a 2-tuple, following that of the return value of :meth:`array.__dlpack_device__`. + *should* be on the same device as ``self`` is. When specified, the format + *must* be a 2-tuple, following that of the return value of :meth:`array.__dlpack_device__`. If the device type cannot be handled by the producer, this function must raise ``BufferError``. - The v2023.12 standard only mandates that a compliant library should offer a way for + The v2023.12 standard only mandates that a compliant library *should* offer a way for ``__dlpack__`` to return a capsule referencing an array whose underlying memory is accessible to the Python interpreter (represented by the ``kDLCPU`` enumerator in DLPack). - If a copy must be made to enable this support but ``copy`` is set to ``False``, the - function must raise ``ValueError``. + If a copy *must* be made to enable this support but ``copy`` is set to ``False``, the + function *must* raise ``ValueError``. Other device kinds will be considered for standardization in a future version of this API standard. copy: Optional[bool] boolean indicating whether or not to copy the input. If ``True``, the - function must always copy (performed by the producer). If ``False``, the - function must never copy, and raise a ``BufferError`` in case a copy is + function *must* always copy (performed by the producer). If ``False``, the + function *must* never copy, and raise a ``BufferError`` in case a copy is deemed necessary (e.g. if a cross-device data movement is requested, and it is not possible without a copy). If ``None``, the function must reuse the existing memory buffer if possible and copy otherwise. Default: ``None``. - When a copy happens, the ``DLPACK_FLAG_BITMASK_IS_COPIED`` flag must be set. + When a copy happens, the ``DLPACK_FLAG_BITMASK_IS_COPIED`` flag *must* be set. .. note:: If a copy happens, and if the consumer-provided ``stream`` and ``dl_device`` - can be understood by the producer, the copy must be performed over ``stream``. + can be understood by the producer, the copy *must* be performed over ``stream``. Returns ------- @@ -424,7 +424,7 @@ def __dlpack__( if max_version >= our_own_dlpack_version: # Consumer understands us, just return a Capsule with our max version elif max_version[0] == our_own_dlpack_version[0]: - # major versions match, we should still be fine here - + # major versions match, we *should* still be fine here - # return our own max version else: # if we're at a higher major version internally, did we @@ -432,7 +432,7 @@ def __dlpack__( # For example, if the producer is on DLPack 1.x and the consumer # is 0.y, can the producer still export a capsule containing # DLManagedTensor and not DLManagedTensorVersioned? - # If so, use that. Else, the producer should raise a BufferError + # If so, use that. Else, the producer *should* raise a BufferError # here to tell users that the consumer's max_version is too # old to allow the data exchange to happen. @@ -452,7 +452,7 @@ def __dlpack__( DLPack 1.0 added a flag to indicate that the array is read-only (``DLPACK_FLAG_BITMASK_READ_ONLY``). A consumer that does not support - read-only arrays should ignore this flag (this is preferred over + read-only arrays *should* ignore this flag (this is preferred over raising an exception; the user is then responsible for ensuring the memory isn't modified). @@ -508,11 +508,11 @@ def __eq__(self: array, other: Union[int, float, bool, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.equal`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.equal`. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -528,7 +528,7 @@ def __float__(self: array, /) -> float: Parameters ---------- self: array - zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``. + zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function *must* raise a ``TypeError``. Returns ------- @@ -573,11 +573,11 @@ def __floordiv__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.floor_divide`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.floor_divide`. """ def __ge__(self: array, other: Union[int, float, array], /) -> array: @@ -597,11 +597,11 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -634,10 +634,10 @@ def __getitem__( Returns ------- out: array - an array containing the accessed value(s). The returned array must have the same data type as ``self``. + an array containing the accessed value(s). The returned array *must* have the same data type as ``self``. .. note:: - When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined. + When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration *should* produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined. """ @@ -658,11 +658,11 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.greater`. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -678,7 +678,7 @@ def __index__(self: array, /) -> int: Parameters ---------- self: array - zero-dimensional array instance. Should have an integer data type. If ``self`` has a floating-point data type, the function must raise a ``TypeError``. + zero-dimensional array instance. Should have an integer data type. If ``self`` has a floating-point data type, the function *must* raise a ``TypeError``. Returns ------- @@ -703,7 +703,7 @@ def __int__(self: array, /) -> int: Parameters ---------- self: array - zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``. + zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function *must* raise a ``TypeError``. Returns ------- @@ -758,11 +758,11 @@ def __invert__(self: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as `self`. + an array containing the element-wise results. The returned array *must* have the same data type as `self`. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_invert`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_invert`. """ def __le__(self: array, other: Union[int, float, array], /) -> array: @@ -782,11 +782,11 @@ def __le__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -801,16 +801,16 @@ def __lshift__(self: array, other: Union[int, array], /) -> array: self: array array instance. Should have an integer data type. other: Union[int, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer data type. Each element must be greater than or equal to ``0``. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer data type. Each element *must* be greater than or equal to ``0``. Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as ``self``. + an array containing the element-wise results. The returned array *must* have the same data type as ``self``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_left_shift`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_left_shift`. """ def __lt__(self: array, other: Union[int, float, array], /) -> array: @@ -830,11 +830,11 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.less`. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -845,36 +845,36 @@ def __matmul__(self: array, other: array, /) -> array: Computes the matrix product. .. note:: - The ``matmul`` function must implement the same semantics as the built-in ``@`` operator (see `PEP 465 `_). + The ``matmul`` function *must* implement the same semantics as the built-in ``@`` operator (see `PEP 465 `_). 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 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. 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 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. .. note:: - If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument must be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the matrix product. + If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument *must* be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations *should* be explicitly performed prior to computing the matrix product. Returns ------- out: array - if both ``self`` and ``other`` are one-dimensional arrays having shape ``(N,)``, a zero-dimensional array containing the inner product as its only element. - if ``self`` is a two-dimensional array having shape ``(M, K)`` and ``other`` is a two-dimensional array having shape ``(K, N)``, a two-dimensional array containing the `conventional matrix product `_ and having shape ``(M, N)``. - - if ``self`` is a one-dimensional array having shape ``(K,)`` and ``other`` is an array having shape ``(..., K, N)``, an array having shape ``(..., N)`` (i.e., prepended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product `_. - - if ``self`` is an array having shape ``(..., M, K)`` and ``other`` is a one-dimensional array having shape ``(K,)``, an array having shape ``(..., M)`` (i.e., appended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product `_. + - if ``self`` is a one-dimensional array having shape ``(K,)`` and ``other`` is an array having shape ``(..., K, N)``, an array having shape ``(..., N)`` (i.e., prepended dimensions during vector-to-matrix promotion *must* be removed) and containing the `conventional matrix product `_. + - if ``self`` is an array having shape ``(..., M, K)`` and ``other`` is a one-dimensional array having shape ``(K,)``, an array having shape ``(..., M)`` (i.e., appended dimensions during vector-to-matrix promotion *must* be removed) and containing the `conventional matrix product `_. - if ``self`` is a two-dimensional array having shape ``(M, K)`` and ``other`` is an array having shape ``(..., K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product `_ for each stacked matrix. - if ``self`` is an array having shape ``(..., M, K)`` and ``other`` is a two-dimensional array having shape ``(K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product `_ for each stacked matrix. - if either ``self`` or ``other`` has more than two dimensions, an array having a shape determined by :ref:`broadcasting` ``shape(self)[:-2]`` against ``shape(other)[:-2]`` and containing the `conventional matrix product `_ for each stacked matrix. - - The returned array must have a data type determined by :ref:`type-promotion`. + - The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Results must equal the results returned by the equivalent function :func:`~array_api.matmul`. + Results *must* equal the results returned by the equivalent function :func:`~array_api.matmul`. **Raises** @@ -905,11 +905,11 @@ 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 real-valued 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:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.remainder`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.remainder`. """ def __mul__(self: array, other: Union[int, float, array], /) -> array: @@ -929,13 +929,13 @@ def __mul__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise products. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.multiply`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.multiply`. .. versionchanged:: 2022.12 Added complex data type support. @@ -955,7 +955,7 @@ def __ne__(self: array, other: Union[int, float, bool, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool`` (i.e., must be a boolean array). + an array containing the element-wise results. The returned array *must* have a data type of ``bool`` (i.e., *must* be a boolean array). Notes @@ -979,7 +979,7 @@ def __neg__(self: array, /) -> array: For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent. .. note:: - If ``self`` has a complex floating-point data type, both the real and imaginary components for each ``self_i`` must be negated (a result which follows from the rules of complex number multiplication). + If ``self`` has a complex floating-point data type, both the real and imaginary components for each ``self_i`` *must* be negated (a result which follows from the rules of complex number multiplication). Parameters ---------- @@ -989,13 +989,13 @@ def __neg__(self: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``self``. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the evaluated result for each element in ``self``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.negative`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.negative`. .. versionchanged:: 2022.12 Added complex data type support. @@ -1015,11 +1015,11 @@ def __or__(self: array, other: Union[int, bool, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_or`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_or`. """ def __pos__(self: array, /) -> array: @@ -1034,13 +1034,13 @@ def __pos__(self: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element. The returned array must have the same data type as ``self``. + an array containing the evaluated result for each element. The returned array *must* have the same data type as ``self``. Notes ----- .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.positive`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.positive`. .. versionchanged:: 2022.12 Added complex data type support. @@ -1065,13 +1065,13 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.pow`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.pow`. .. versionchanged:: 2022.12 Added complex data type support. @@ -1086,16 +1086,16 @@ def __rshift__(self: array, other: Union[int, array], /) -> array: self: array array instance. Should have an integer data type. other: Union[int, array] - other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer data type. Each element must be greater than or equal to ``0``. + other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer data type. Each element *must* be greater than or equal to ``0``. Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as ``self``. + an array containing the element-wise results. The returned array *must* have the same data type as ``self``. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_right_shift`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_right_shift`. """ def __setitem__( @@ -1123,9 +1123,9 @@ def __setitem__( .. note:: - Setting array values must not affect the data type of ``self``. + Setting array values *must not* affect the data type of ``self``. - When ``value`` is a Python scalar (i.e., ``int``, ``float``, ``bool``), behavior must follow specification guidance on mixing arrays with Python scalars (see :ref:`type-promotion`). + When ``value`` is a Python scalar (i.e., ``int``, ``float``, ``bool``), behavior *must* follow specification guidance on mixing arrays with Python scalars (see :ref:`type-promotion`). When ``value`` is an ``array`` of a different data type than ``self``, how values are cast to the data type of ``self`` is implementation defined. """ @@ -1134,7 +1134,7 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array: """ Calculates the difference for each element of an array instance with the respective element of the array ``other``. - The result of ``self_i - other_i`` must be the same as ``self_i + (-other_i)`` and must be governed by the same floating-point rules as addition (see :meth:`array.__add__`). + The result of ``self_i - other_i`` *must* be the same as ``self_i + (-other_i)`` and *must* be governed by the same floating-point rules as addition (see :meth:`array.__add__`). Parameters ---------- @@ -1146,13 +1146,13 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array: Returns ------- out: array - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise differences. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.subtract`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.subtract`. .. versionchanged:: 2022.12 Added complex data type support. @@ -1165,7 +1165,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 real-valued 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. Parameters ---------- @@ -1177,13 +1177,13 @@ 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.divide`. + Element-wise results, including special cases, *must* equal the results returned by the equivalent element-wise function :func:`~array_api.divide`. .. versionchanged:: 2022.12 Added complex data type support. @@ -1203,11 +1203,11 @@ def __xor__(self: array, other: Union[int, bool, array], /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. .. note:: - Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_xor`. + Element-wise results *must* equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_xor`. """ def to_device( @@ -1235,7 +1235,7 @@ def to_device( ----- - When a provided ``device`` object corresponds to the same device on which an array instance resides, implementations may choose to perform an explicit copy or return ``self``. - - If ``stream`` is provided, the copy operation should be enqueued on the provided ``stream``; otherwise, the copy operation should be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this must be clearly explained in a conforming array library's documentation. + - If ``stream`` is provided, the copy operation *should* be enqueued on the provided ``stream``; otherwise, the copy operation *should* be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this *must* be clearly explained in a conforming array library's documentation. .. versionchanged:: 2023.12 Clarified behavior when a provided ``device`` object corresponds to the device on which an array instance resides. diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 6de79268e..ed8eec6da 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -52,7 +52,7 @@ def arange( 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 real-valued 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``. @@ -63,7 +63,7 @@ def arange( Returns ------- out: array - a one-dimensional array containing evenly spaced values. The length of the output array must be ``ceil((stop-start)/step)`` if ``stop - start`` and ``step`` have the same sign, and length ``0`` otherwise. + a one-dimensional array containing evenly spaced values. The length of the output array *must* be ``ceil((stop-start)/step)`` if ``stop - start`` and ``step`` have the same sign, and length ``0`` otherwise. """ @@ -91,12 +91,12 @@ def asarray( An object supporting the buffer protocol can be turned into a memoryview through ``memoryview(obj)``. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from the data type(s) in ``obj``. If all input values are Python scalars, then, in order of precedence, + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from the data type(s) in ``obj``. If all input values are Python scalars, then, in order of precedence, - - if all values are of type ``bool``, the output data type must be ``bool``. - - if all values are of type ``int`` or are a mixture of ``bool`` and ``int``, the output data type must be the default integer data type. - - if one or more values are ``complex`` numbers, the output data type must be the default complex 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. + - if all values are of type ``bool``, the output data type *must* be ``bool``. + - if all values are of type ``int`` or are a mixture of ``bool`` and ``int``, the output data type *must* be the default integer data type. + - if one or more values are ``complex`` numbers, the output data type *must* be the default complex 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``. @@ -109,7 +109,7 @@ def asarray( If an input value exceeds the precision of the resolved output array data type, behavior is left unspecified and, thus, implementation-defined. device: Optional[device] - device on which to place the created array. If ``device`` is ``None`` and ``obj`` is an array, the output array device must be inferred from ``obj``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None`` and ``obj`` is an array, the output array device *must* be inferred from ``obj``. Default: ``None``. copy: Optional[bool] boolean indicating whether or not to copy the input. If ``True``, the function must always copy. If ``False``, the function must never copy for input which supports the buffer protocol and must raise a ``ValueError`` in case a copy would be necessary. If ``None``, the function must reuse existing memory buffer if possible and copy otherwise. Default: ``None``. @@ -140,7 +140,7 @@ def empty( 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 real-valued 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,9 +162,9 @@ def empty_like( x: array input array from which to derive the output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``x``. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from ``x``. Default: ``None``. device: Optional[device] - device on which to place the created array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None``, the output array device *must* be inferred from ``x``. Default: ``None``. Returns ------- @@ -186,7 +186,7 @@ def eye( Returns a two-dimensional array with ones on the ``k``\th diagonal and zeros elsewhere. .. note:: - An output array having a complex floating-point data type must have the value ``1 + 0j`` along the ``k``\th diagonal and ``0 + 0j`` elsewhere. + An output array having a complex floating-point data type *must* have the value ``1 + 0j`` along the ``k``\th diagonal and ``0 + 0j`` elsewhere. Parameters ---------- @@ -197,7 +197,7 @@ def eye( 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 real-valued 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``. @@ -229,12 +229,12 @@ def from_dlpack( x: object input (array) object. device: Optional[device] - device on which to place the created array. If ``device`` is ``None`` and ``x`` supports DLPack, the output array must be on the same device as ``x``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None`` and ``x`` supports DLPack, the output array *must* be on the same device as ``x``. Default: ``None``. - The v2023.12 standard only mandates that a compliant library should offer a way for ``from_dlpack`` to return an array + The v2023.12 standard only mandates that a compliant library *should* offer a way for ``from_dlpack`` to return an array whose underlying memory is accessible to the Python interpreter, when the corresponding ``device`` is provided. If the array library does not support such cases at all, the function must raise ``BufferError``. If a copy must be made to - enable this support but ``copy`` is set to ``False``, the function must raise ``ValueError``. + enable this support but ``copy`` is set to ``False``, the function *must* raise ``ValueError``. Other device kinds will be considered for standardization in a future version of this API standard. copy: Optional[bool] @@ -257,7 +257,7 @@ def from_dlpack( may raise ``BufferError`` when the data cannot be exported as DLPack (e.g., incompatible dtype, strides, or device). It may also raise other errors when export fails for other reasons (e.g., not enough memory available - to materialize the data). ``from_dlpack`` must propagate such + to materialize the data). ``from_dlpack`` *must* propagate such exceptions. AttributeError If the ``__dlpack__`` and ``__dlpack_device__`` methods are not present @@ -314,12 +314,12 @@ def full( fill_value: Union[bool, int, float, complex] fill value. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``fill_value`` according to the following rules: + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from ``fill_value`` according to the following rules: - - 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 ``complex`` number, the output array data type must be the default complex floating-point data type. - - If the fill value is a ``bool``, the output array must have a boolean data type. Default: ``None``. + - 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 ``complex`` number, the output array data type *must* be the default complex floating-point data type. + - If the fill value is a ``bool``, the output array *must* have a 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. @@ -358,7 +358,7 @@ def full_like( fill_value: Union[bool, int, float, complex] fill value. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``x``. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from ``x``. Default: ``None``. .. note:: If the ``fill_value`` exceeds the precision of the resolved output array data type, behavior is unspecified and, thus, implementation-defined. @@ -367,7 +367,7 @@ def full_like( If the ``fill_value`` has a data type which is not of the same data type kind (boolean, integer, or floating-point) as the resolved output array data type (see :ref:`type-promotion`), behavior is unspecified and, thus, implementation-defined. device: Optional[device] - device on which to place the created array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None``, the output array device *must* be inferred from ``x``. Default: ``None``. Returns ------- @@ -410,7 +410,7 @@ def linspace( start: Union[int, float, complex] the start of the interval. stop: Union[int, float, complex] - the end of the interval. If ``endpoint`` is ``False``, the function must generate a sequence of ``num+1`` evenly spaced numbers starting with ``start`` and ending with ``stop`` and exclude the ``stop`` from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval ``[start, stop)``. If ``endpoint`` is ``True``, the output array must consist of evenly spaced numbers over the closed interval ``[start, stop]``. Default: ``True``. + the end of the interval. If ``endpoint`` is ``False``, the function *must* generate a sequence of ``num+1`` evenly spaced numbers starting with ``start`` and ending with ``stop`` and exclude the ``stop`` from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval ``[start, stop)``. If ``endpoint`` is ``True``, the output array *must* consist of evenly spaced numbers over the closed interval ``[start, stop]``. Default: ``True``. .. note:: The step size changes when `endpoint` is `False`. @@ -420,8 +420,8 @@ def linspace( dtype: Optional[dtype] output array data type. Should be a floating-point data type. If ``dtype`` is ``None``, - - if either ``start`` or ``stop`` is a ``complex`` number, the output data type must be the default complex floating-point data type. - - if both ``start`` and ``stop`` are real-valued, the output data type must be the default real-valued floating-point data type. + - if either ``start`` or ``stop`` is a ``complex`` number, the output data type *must* be the default complex floating-point data type. + - if both ``start`` and ``stop`` are real-valued, the output data type *must* be the default real-valued floating-point data type. Default: ``None``. @@ -461,23 +461,23 @@ 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 numeric 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'``. + 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'``. Returns ------- out: List[array] - list of N arrays, where ``N`` is the number of provided one-dimensional input arrays. Each returned array must have rank ``N``. For ``N`` one-dimensional arrays having lengths ``Ni = len(xi)``, + list of N arrays, where ``N`` is the number of provided one-dimensional input arrays. Each returned array *must* have rank ``N``. For ``N`` one-dimensional arrays having lengths ``Ni = len(xi)``, - - if matrix indexing ``ij``, then each returned array must have the shape ``(N1, N2, N3, ..., Nn)``. - - if Cartesian indexing ``xy``, then each returned array must have shape ``(N2, N1, N3, ..., Nn)``. + - if matrix indexing ``ij``, then each returned array *must* have the shape ``(N1, N2, N3, ..., Nn)``. + - if Cartesian indexing ``xy``, then each returned array *must* have shape ``(N2, N1, N3, ..., Nn)``. - Accordingly, for the two-dimensional case with input one-dimensional arrays of length ``M`` and ``N``, if matrix indexing ``ij``, then each returned array must have shape ``(M, N)``, and, if Cartesian indexing ``xy``, then each returned array must have shape ``(N, M)``. + Accordingly, for the two-dimensional case with input one-dimensional arrays of length ``M`` and ``N``, if matrix indexing ``ij``, then each returned array *must* have shape ``(M, N)``, and, if Cartesian indexing ``xy``, then each returned array *must* have shape ``(N, M)``. - Similarly, for the three-dimensional case with input one-dimensional arrays of length ``M``, ``N``, and ``P``, if matrix indexing ``ij``, then each returned array must have shape ``(M, N, P)``, and, if Cartesian indexing ``xy``, then each returned array must have shape ``(N, M, P)``. + Similarly, for the three-dimensional case with input one-dimensional arrays of length ``M``, ``N``, and ``P``, if matrix indexing ``ij``, then each returned array *must* have shape ``(M, N, P)``, and, if Cartesian indexing ``xy``, then each returned array *must* have shape ``(N, M, P)``. - Each returned array should have the same data type as the input arrays. + Each returned array *should* have the same data type as the input arrays. Notes ----- @@ -497,14 +497,14 @@ def ones( Returns a new array having a specified ``shape`` and filled with ones. .. note:: - An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``). + An output array having a complex floating-point data type *must* contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``). Parameters ---------- 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 real-valued 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``. @@ -528,16 +528,16 @@ def ones_like( Returns a new array filled with ones and having the same ``shape`` as an input array ``x``. .. note:: - An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``). + An output array having a complex floating-point data type *must* contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``). Parameters ---------- x: array input array from which to derive the output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``x``. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from ``x``. Default: ``None``. device: Optional[device] - device on which to place the created array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None``, the output array device *must* be inferred from ``x``. Default: ``None``. Returns ------- @@ -572,7 +572,7 @@ def tril(x: array, /, *, k: int = 0) -> array: Returns ------- out: array - an array containing the lower triangular part(s). The returned array must have the same shape and data type as ``x``. All elements above the specified diagonal ``k`` must be zeroed. The returned array should be allocated on the same device as ``x``. + an array containing the lower triangular part(s). The returned array *must* have the same shape and data type as ``x``. All elements above the specified diagonal ``k`` *must* be zeroed. The returned array *should* be allocated on the same device as ``x``. """ @@ -596,7 +596,7 @@ def triu(x: array, /, *, k: int = 0) -> array: Returns ------- out: array - an array containing the upper triangular part(s). The returned array must have the same shape and data type as ``x``. All elements below the specified diagonal ``k`` must be zeroed. The returned array should be allocated on the same device as ``x``. + an array containing the upper triangular part(s). The returned array *must* have the same shape and data type as ``x``. All elements below the specified diagonal ``k`` *must* be zeroed. The returned array *should* be allocated on the same device as ``x``. """ @@ -614,7 +614,7 @@ def zeros( 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 real-valued 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``. @@ -636,9 +636,9 @@ def zeros_like( x: array input array from which to derive the output array shape. dtype: Optional[dtype] - output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``x``. Default: ``None``. + output array data type. If ``dtype`` is ``None``, the output array data type *must* be inferred from ``x``. Default: ``None``. device: Optional[device] - device on which to place the created array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``. + device on which to place the created array. If ``device`` is ``None``, the output array device *must* be inferred from ``x``. Default: ``None``. Returns ------- diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index e12d349c6..a2a076b77 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -22,19 +22,19 @@ def astype( Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. .. note:: - Casting a complex floating-point array to a real-valued data type should not be permitted. + Casting a complex floating-point array to a real-valued data type *should not* be permitted. - Historically, when casting a complex floating-point array to a real-valued data type, libraries such as NumPy have discarded imaginary components such that, for a complex floating-point array ``x``, ``astype(x)`` equals ``astype(real(x))``). This behavior is considered problematic as the choice to discard the imaginary component is arbitrary and introduces more than one way to achieve the same outcome (i.e., for a complex floating-point array ``x``, ``astype(x)`` and ``astype(real(x))`` versus only ``astype(imag(x))``). Instead, in order to avoid ambiguity and to promote clarity, this specification requires that array API consumers explicitly express which component should be cast to a specified real-valued data type. + Historically, when casting a complex floating-point array to a real-valued data type, libraries such as NumPy have discarded imaginary components such that, for a complex floating-point array ``x``, ``astype(x)`` equals ``astype(real(x))``). This behavior is considered problematic as the choice to discard the imaginary component is arbitrary and introduces more than one way to achieve the same outcome (i.e., for a complex floating-point array ``x``, ``astype(x)`` and ``astype(real(x))`` versus only ``astype(imag(x))``). Instead, in order to avoid ambiguity and to promote clarity, this specification requires that array API consumers explicitly express which component *should* be cast to a specified real-valued data type. .. note:: - When casting a boolean input array to a real-valued data type, a value of ``True`` must cast to a real-valued number equal to ``1``, and a value of ``False`` must cast to a real-valued number equal to ``0``. + When casting a boolean input array to a real-valued data type, a value of ``True`` *must* cast to a real-valued number equal to ``1``, and a value of ``False`` *must* cast to a real-valued number equal to ``0``. - When casting a boolean input array to a complex floating-point data type, a value of ``True`` must cast to a complex number equal to ``1 + 0j``, and a value of ``False`` must cast to a complex number equal to ``0 + 0j``. + When casting a boolean input array to a complex floating-point data type, a value of ``True`` *must* cast to a complex number equal to ``1 + 0j``, and a value of ``False`` *must* cast to a complex number equal to ``0 + 0j``. .. note:: - 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``. + 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``. - When casting a complex floating-point array to ``bool``, a value of ``0 + 0j`` must cast to ``False``, and all other values must cast to ``True``. + When casting a complex floating-point array to ``bool``, a value of ``0 + 0j`` *must* cast to ``False``, and all other values *must* cast to ``True``. Parameters ---------- @@ -43,14 +43,14 @@ def astype( dtype: dtype desired data type. copy: bool - specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``. + specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array *must* always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array *must* be returned; otherwise, a newly allocated array *must* be returned. Default: ``True``. device: Optional[device] - device on which to place the returned array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``. + device on which to place the returned array. If ``device`` is ``None``, the output array device *must* be inferred from ``x``. Default: ``None``. Returns ------- out: array - an array having the specified data type. The returned array must have the same shape as ``x``. + an array having the specified data type. The returned array *must* have the same shape as ``x``. Notes ----- @@ -91,7 +91,7 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: the kind of floating-point data-type about which to get information. If complex, the information is about its component data type. .. note:: - Complex floating-point data types are specified to always use the same precision for both its real and imaginary components, so the information should be true for either component. + Complex floating-point data types are specified to always use the same precision for both its real and imaginary components, so the information *should* be true for either component. Returns ------- @@ -179,8 +179,8 @@ def isdtype( kind: Union[str, dtype, Tuple[Union[str, dtype], ...]] data type kind. - - If ``kind`` is a dtype, the function must return a boolean indicating whether the input ``dtype`` is equal to the dtype specified by ``kind``. - - If ``kind`` is a string, the function must return a boolean indicating whether the input ``dtype`` is of a specified data type kind. The following dtype kinds must be supported: + - If ``kind`` is a dtype, the function *must* return a boolean indicating whether the input ``dtype`` is equal to the dtype specified by ``kind``. + - If ``kind`` is a string, the function *must* return a boolean indicating whether the input ``dtype`` is of a specified data type kind. The following dtype kinds *must* be supported: - ``'bool'``: boolean data types (e.g., ``bool``). - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). @@ -190,12 +190,12 @@ def isdtype( - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). - ``'numeric'``: numeric data types. Shorthand for ``('integral', 'real floating', 'complex floating')``. - - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. + - If ``kind`` is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function *must* return a boolean indicating whether the input ``dtype`` is either equal to a specified dtype or belongs to at least one specified data type kind. .. note:: A conforming implementation of the array API standard is **not** limited to only including the dtypes described in this specification in the required data type kinds. For example, implementations supporting ``float16`` and ``bfloat16`` can include ``float16`` and ``bfloat16`` in the ``real floating`` data type kind. Similarly, implementations supporting ``int128`` can include ``int128`` in the ``signed integer`` data type kind. - In short, conforming implementations may extend data type kinds; however, data type kinds must remain consistent (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to floating-point data type kinds), and extensions must be clearly documented as such in library documentation. + In short, conforming implementations may extend data type kinds; however, data type kinds *must* remain consistent (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to floating-point data type kinds), and extensions *must* be clearly documented as such in library documentation. Returns ------- diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 156715200..881216621 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -88,7 +88,7 @@ def abs(x: array, /) -> array: \operatorname{abs}(z) = \sqrt{a^2 + b^2} .. note:: - For complex floating-point operands, conforming implementations should take care to avoid undue overflow or underflow during intermediate stages of computation. + For complex floating-point operands, conforming implementations *should* take care to avoid undue overflow or underflow during intermediate stages of computation. .. TODO: once ``hypot`` is added to the specification, remove the special cases for complex floating-point operands and the note concerning guarding against undue overflow/underflow, and state that special cases must be handled as if implemented as ``hypot(real(x), imag(x))``. @@ -101,7 +101,7 @@ def abs(x: array, /) -> array: Returns ------- out: array - an array containing the absolute value of each element in ``x``. If ``x`` has a real-valued data type, the returned array must have the same data type as ``x``. If ``x`` has a complex floating-point data type, the returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). + an array containing the absolute value of each element in ``x``. If ``x`` has a real-valued data type, the returned array *must* have the same data type as ``x``. If ``x`` has a complex floating-point data type, the returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). Notes ----- @@ -147,7 +147,7 @@ def acos(x: array, /) -> array: \operatorname{acos}(z) = \pi - \operatorname{acos}(-z) .. note:: - For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``. + For complex floating-point operands, ``acos(conj(x))`` *must* equal ``conj(acos(x))``. .. note:: The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, -1)` and :math:`(1, \infty)` of the real axis. @@ -164,7 +164,7 @@ def acos(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -221,7 +221,7 @@ def acosh(x: array, /) -> array: in the upper half of the complex plane. .. note:: - For complex floating-point operands, ``acosh(conj(x))`` must equal ``conj(acosh(x))``. + For complex floating-point operands, ``acosh(conj(x))`` *must* equal ``conj(acosh(x))``. .. note:: The inverse hyperbolic cosine is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segment :math:`(-\infty, 1)` of the real axis. @@ -238,7 +238,7 @@ def acosh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -286,7 +286,7 @@ def add(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise sums. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -311,7 +311,7 @@ def add(x1: array, x2: array, /) -> array: - If ``x1_i`` is either ``+0`` or ``-0`` and ``x2_i`` is a nonzero finite number, the result is ``x2_i``. - If ``x1_i`` is a nonzero finite number and ``x2_i`` is either ``+0`` or ``-0``, the result is ``x1_i``. - If ``x1_i`` is a nonzero finite number and ``x2_i`` is ``-x1_i``, the result is ``+0``. - - In the remaining cases, when neither ``infinity``, ``+0``, ``-0``, nor a ``NaN`` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. + - In the remaining cases, when neither ``infinity``, ``+0``, ``-0``, nor a ``NaN`` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum *must* be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign. .. note:: Floating-point addition is a commutative operation, but not always associative. @@ -328,7 +328,7 @@ def add(x1: array, x2: array, /) -> array: | **a + bj** | (a+c) + bj | a + (b+d)j | (a+c) + (b+d)j | +------------+------------+------------+----------------+ - For complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table. For example, let ``a = real(x1_i)``, ``b = imag(x1_i)``, ``c = real(x2_i)``, ``d = imag(x2_i)``, and + For complex floating-point operands, real-valued floating-point special cases *must* independently apply to the real and imaginary component operations involving real numbers as described in the above table. For example, let ``a = real(x1_i)``, ``b = imag(x1_i)``, ``c = real(x2_i)``, ``d = imag(x2_i)``, and - If ``a`` is ``-0`` and ``c`` is ``-0``, the real component of the result is ``-0``. - Similarly, if ``b`` is ``+0`` and ``d`` is ``-0``, the imaginary component of the result is ``+0``. @@ -358,7 +358,7 @@ def asin(x: array, /) -> array: \operatorname{asin}(z) = \operatorname{acos}(-z) - \frac{\pi}{2} .. note:: - For complex floating-point operands, ``asin(conj(x))`` must equal ``conj(asin(x))``. + For complex floating-point operands, ``asin(conj(x))`` *must* equal ``conj(asin(x))``. .. note:: The inverse sine (or arc sine) is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, -1)` and :math:`(1, \infty)` of the real axis. @@ -375,7 +375,7 @@ def asin(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -390,7 +390,7 @@ def asin(x: array, /) -> array: - If ``x_i`` is ``+0``, the result is ``+0``. - If ``x_i`` is ``-0``, the result is ``-0``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as ``-1j * asinh(x*1j)``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as ``-1j * asinh(x*1j)``. .. versionchanged:: 2022.12 Added complex data type support. @@ -413,7 +413,7 @@ def asinh(x: array, /) -> array: \operatorname{asinh}(z) = \frac{\operatorname{asin}(zj)}{j} .. note:: - For complex floating-point operands, ``asinh(conj(x))`` must equal ``conj(asinh(x))`` and ``asinh(-z)`` must equal ``-asinh(z)``. + For complex floating-point operands, ``asinh(conj(x))`` *must* equal ``conj(asinh(x))`` and ``asinh(-z)`` *must* equal ``-asinh(z)``. .. note:: The inverse hyperbolic sine is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty j, -j)` and :math:`(j, \infty j)` of the imaginary axis. @@ -430,7 +430,7 @@ def asinh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -475,7 +475,7 @@ def atan(x: array, /) -> array: \operatorname{atan}(z) = -\frac{\ln(1 - zj) - \ln(1 + zj)}{2}j .. note:: - For complex floating-point operands, ``atan(conj(x))`` must equal ``conj(atan(x))``. + For complex floating-point operands, ``atan(conj(x))`` *must* equal ``conj(atan(x))``. .. note:: The inverse tangent (or arc tangent) is a multi-valued function and requires a branch on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty j, -j)` and :math:`(+j, \infty j)` of the imaginary axis. @@ -492,7 +492,7 @@ def atan(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -507,7 +507,7 @@ def atan(x: array, /) -> array: - If ``x_i`` is ``+infinity``, the result is an implementation-dependent approximation to ``+π/2``. - If ``x_i`` is ``-infinity``, the result is an implementation-dependent approximation to ``-π/2``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as ``-1j * atanh(x*1j)``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as ``-1j * atanh(x*1j)``. .. versionchanged:: 2022.12 Added complex data type support. @@ -535,7 +535,7 @@ def atan2(x1: array, x2: array, /) -> array: Returns ------- out: array - 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`. + 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`. Notes ----- @@ -586,7 +586,7 @@ def atanh(x: array, /) -> array: \operatorname{atanh}(z) = \frac{\operatorname{atan}(zj)}{j} .. note:: - For complex floating-point operands, ``atanh(conj(x))`` must equal ``conj(atanh(x))`` and ``atanh(-x)`` must equal ``-atanh(x)``. + For complex floating-point operands, ``atanh(conj(x))`` *must* equal ``conj(atanh(x))`` and ``atanh(-x)`` *must* equal ``-atanh(x)``. .. note:: The inverse hyperbolic tangent is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, 1]` and :math:`[1, \infty)` of the real axis. @@ -603,7 +603,7 @@ def atanh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -653,7 +653,7 @@ def bitwise_and(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. """ @@ -666,12 +666,12 @@ def bitwise_left_shift(x1: array, x2: array, /) -> array: x1: array first input array. Should have an integer data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have an integer data type. Each element must be greater than or equal to ``0``. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have an integer data type. Each element *must* be greater than or equal to ``0``. Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. """ @@ -687,7 +687,7 @@ def bitwise_invert(x: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as ``x``. + an array containing the element-wise results. The returned array *must* have the same data type as ``x``. """ @@ -705,7 +705,7 @@ def bitwise_or(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. """ @@ -714,19 +714,19 @@ def bitwise_right_shift(x1: array, x2: array, /) -> array: Shifts the bits of each element ``x1_i`` of the input array ``x1`` to the right according to the respective element ``x2_i`` of the input array ``x2``. .. note:: - This operation must be an arithmetic shift (i.e., sign-propagating) and thus equivalent to floor division by a power of two. + This operation *must* be an arithmetic shift (i.e., sign-propagating) and thus equivalent to floor division by a power of two. Parameters ---------- x1: array first input array. Should have an integer data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have an integer data type. Each element must be greater than or equal to ``0``. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have an integer data type. Each element *must* be greater than or equal to ``0``. Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. """ @@ -744,7 +744,7 @@ def bitwise_xor(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. """ @@ -760,7 +760,7 @@ def ceil(x: array, /) -> array: Returns ------- out: array - an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the rounded result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- @@ -793,19 +793,19 @@ def clip( x: array input array. Should have a real-valued data type. min: Optional[Union[int, float, array]] - lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + lower-bound of the range to which to clamp. If ``None``, no lower bound *must* be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. max: Optional[Union[int, float, array]] - upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + upper-bound of the range to which to clamp. If ``None``, no upper bound *must* be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. Returns ------- out: array - an array containing element-wise results. The returned array must have the same data type as ``x``. + an array containing element-wise results. The returned array *must* have the same data type as ``x``. Notes ----- - - If both ``min`` and ``max`` are ``None``, the elements of the returned array must equal the respective elements in ``x``. + - If both ``min`` and ``max`` are ``None``, the elements of the returned array *must* equal the respective elements in ``x``. - If a broadcasted element in ``min`` is greater than a corresponding broadcasted element in ``max``, behavior is unspecified and thus implementation-dependent. - If ``x`` and either ``min`` or ``max`` have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent. @@ -833,7 +833,7 @@ def conj(x: array, /) -> array: .. math:: a - bj - Hence, the returned complex conjugates must be computed by negating the imaginary component of each element ``x_i``. + Hence, the returned complex conjugates *must* be computed by negating the imaginary component of each element ``x_i``. Parameters ---------- @@ -843,7 +843,7 @@ def conj(x: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as ``x``. + an array containing the element-wise results. The returned array *must* have the same data type as ``x``. Notes ----- @@ -866,7 +866,7 @@ def copysign(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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -918,7 +918,7 @@ def cos(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -933,7 +933,7 @@ def cos(x: array, /) -> array: - If ``x_i`` is ``+infinity``, the result is ``NaN``. - If ``x_i`` is ``-infinity``, the result is ``NaN``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as ``cosh(x*1j)``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as ``cosh(x*1j)``. .. versionchanged:: 2022.12 Added complex data type support. @@ -960,7 +960,7 @@ def cosh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -968,7 +968,7 @@ def cosh(x: array, /) -> array: **Special cases** .. note:: - For all operands, ``cosh(x)`` must equal ``cosh(-x)``. + For all operands, ``cosh(x)`` *must* equal ``cosh(-x)``. For real-valued floating-point operands, @@ -981,7 +981,7 @@ def cosh(x: array, /) -> array: For complex floating-point operands, let ``a = real(x_i)``, ``b = imag(x_i)``, and .. note:: - For complex floating-point operands, ``cosh(conj(x))`` must equal ``conj(cosh(x))``. + For complex floating-point operands, ``cosh(conj(x))`` *must* equal ``conj(cosh(x))``. - If ``a`` is ``+0`` and ``b`` is ``+0``, the result is ``1 + 0j``. - If ``a`` is ``+0`` and ``b`` is ``+infinity``, the result is ``NaN + 0j`` (sign of the imaginary component is unspecified). @@ -1010,7 +1010,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 real-valued 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. Parameters ---------- @@ -1022,7 +1022,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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1052,7 +1052,7 @@ def divide(x1: array, x2: array, /) -> array: - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``+0``. - If ``x1_i`` and ``x2_i`` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign. - If ``x1_i`` and ``x2_i`` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign. - - In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the operation overflows and the result is an ``infinity`` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. + - In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient *must* be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the operation overflows and the result is an ``infinity`` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign. For complex floating-point operands, division is defined according to the following table. For real components ``a`` and ``c`` and imaginary components ``b`` and ``d``, @@ -1066,9 +1066,9 @@ def divide(x1: array, x2: array, /) -> array: | **a + bj** | (a/c) + (b/c)j | b/d - (a/d)j | special rules | +------------+----------------+-----------------+--------------------------+ - In general, for complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table. + In general, for complex floating-point operands, real-valued floating-point special cases *must* independently apply to the real and imaginary component operations involving real numbers as described in the above table. - When ``a``, ``b``, ``c``, or ``d`` are all finite numbers (i.e., a value other than ``NaN``, ``+infinity``, or ``-infinity``), division of complex floating-point operands should be computed as if calculated according to the textbook formula for complex number division + When ``a``, ``b``, ``c``, or ``d`` are all finite numbers (i.e., a value other than ``NaN``, ``+infinity``, or ``-infinity``), division of complex floating-point operands *should* be computed as if calculated according to the textbook formula for complex number division .. math:: \frac{a + bj}{c + dj} = \frac{(ac + bd) + (bc - ad)j}{c^2 + d^2} @@ -1100,7 +1100,7 @@ def equal(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -1138,7 +1138,7 @@ def exp(x: array, /) -> array: Calculates an implementation-dependent approximation to the exponential function for each element ``x_i`` of the input array ``x`` (``e`` raised to the power of ``x_i``, where ``e`` is the base of the natural logarithm). .. note:: - For complex floating-point operands, ``exp(conj(x))`` must equal ``conj(exp(x))``. + For complex floating-point operands, ``exp(conj(x))`` *must* equal ``conj(exp(x))``. .. note:: The exponential function is an entire function in the complex plane and has no branch cuts. @@ -1151,7 +1151,7 @@ def exp(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1194,10 +1194,10 @@ def expm1(x: array, /) -> array: Calculates an implementation-dependent approximation to ``exp(x)-1`` for each element ``x_i`` of the input array ``x``. .. note:: - The purpose of this function is to calculate ``exp(x)-1.0`` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply ``exp(x)-1.0``. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate ``exp(x)-1.0`` more accurately when `x` is close to zero. Accordingly, conforming implementations *should* avoid implementing this function as simply ``exp(x)-1.0``. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. .. note:: - For complex floating-point operands, ``expm1(conj(x))`` must equal ``conj(expm1(x))``. + For complex floating-point operands, ``expm1(conj(x))`` *must* equal ``conj(expm1(x))``. .. note:: The exponential function is an entire function in the complex plane and has no branch cuts. @@ -1210,7 +1210,7 @@ def expm1(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1260,7 +1260,7 @@ def floor(x: array, /) -> array: Returns ------- out: array - an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the rounded result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- @@ -1296,7 +1296,7 @@ def floor_divide(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -1356,7 +1356,7 @@ def greater(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -1381,7 +1381,7 @@ def greater_equal(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -1405,12 +1405,12 @@ def hypot(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a real-valued 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`. Notes ----- - The purpose of this function is to avoid underflow and overflow during intermediate stages of computation. Accordingly, conforming implementations should not use naive implementations. + The purpose of this function is to avoid underflow and overflow during intermediate stages of computation. Accordingly, conforming implementations *should not* use naive implementations. **Special Cases** @@ -1424,7 +1424,7 @@ def hypot(x1: array, x2: array, /) -> array: - If ``x2_i`` is a finite number or ``NaN`` and ``x1_i`` is ``NaN``, the result is ``NaN``. - Underflow may only occur when both arguments are subnormal and the correct result is also subnormal. - For real-valued floating-point operands, ``hypot(x1, x2)`` must equal ``hypot(x2, x1)``, ``hypot(x1, -x2)``, ``hypot(-x1, x2)``, and ``hypot(-x1, -x2)``. + For real-valued floating-point operands, ``hypot(x1, x2)`` *must* equal ``hypot(x2, x1)``, ``hypot(x1, -x2)``, ``hypot(-x1, x2)``, and ``hypot(-x1, -x2)``. .. 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. @@ -1447,7 +1447,7 @@ def imag(x: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a floating-point data type with the same floating-point precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array must have the floating-point data type ``float32``). + an array containing the element-wise results. The returned array *must* have a floating-point data type with the same floating-point precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array *must* have the floating-point data type ``float32``). Notes ----- @@ -1468,7 +1468,7 @@ def isfinite(x: array, /) -> array: Returns ------- out: array - an array containing test results. The returned array must have a data type of ``bool``. + an array containing test results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -1505,7 +1505,7 @@ def isinf(x: array, /) -> array: Returns ------- out: array - an array containing test results. The returned array must have a data type of ``bool``. + an array containing test results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -1540,7 +1540,7 @@ def isnan(x: array, /) -> array: Returns ------- out: array - an array containing test results. The returned array should have a data type of ``bool``. + an array containing test results. The returned array *should* have a data type of ``bool``. Notes ----- @@ -1579,7 +1579,7 @@ def less(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -1603,7 +1603,7 @@ def less_equal(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. .. note:: Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent. @@ -1618,7 +1618,7 @@ def log(x: array, /) -> array: The natural logarithm of a complex number :math:`z` with polar coordinates :math:`(r,\theta)` equals :math:`\ln r + (\theta + 2n\pi)j` with principal value :math:`\ln r + \theta j`. .. note:: - For complex floating-point operands, ``log(conj(x))`` must equal ``conj(log(x))``. + For complex floating-point operands, ``log(conj(x))`` *must* equal ``conj(log(x))``. .. note:: By convention, the branch cut of the natural logarithm is the negative real axis :math:`(-\infty, 0)`. @@ -1637,7 +1637,7 @@ def log(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1677,10 +1677,10 @@ def log1p(x: array, /) -> array: Calculates an implementation-dependent approximation to ``log(1+x)``, where ``log`` refers to the natural (base ``e``) logarithm, for each element ``x_i`` of the input array ``x``. .. note:: - The purpose of this function is to calculate ``log(1+x)`` more accurately when `x` is close to zero. Accordingly, conforming implementations should avoid implementing this function as simply ``log(1+x)``. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. + The purpose of this function is to calculate ``log(1+x)`` more accurately when `x` is close to zero. Accordingly, conforming implementations *should* avoid implementing this function as simply ``log(1+x)``. See FDLIBM, or some other IEEE 754-2019 compliant mathematical library, for a potential reference implementation. .. note:: - For complex floating-point operands, ``log1p(conj(x))`` must equal ``conj(log1p(x))``. + For complex floating-point operands, ``log1p(conj(x))`` *must* equal ``conj(log1p(x))``. .. note:: By convention, the branch cut of the natural logarithm is the negative real axis :math:`(-\infty, 0)`. @@ -1699,7 +1699,7 @@ def log1p(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1739,7 +1739,7 @@ def log2(x: array, /) -> array: Calculates an implementation-dependent approximation to the base ``2`` logarithm for each element ``x_i`` of the input array ``x``. .. note:: - For complex floating-point operands, ``log2(conj(x))`` must equal ``conj(log2(x))``. + For complex floating-point operands, ``log2(conj(x))`` *must* equal ``conj(log2(x))``. Parameters ---------- @@ -1749,7 +1749,7 @@ def log2(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1764,7 +1764,7 @@ def log2(x: array, /) -> array: - If ``x_i`` is ``1``, the result is ``+0``. - If ``x_i`` is ``+infinity``, the result is ``+infinity``. - For complex floating-point operands, special cases must be handled as if the operation is implemented using the standard change of base formula + For complex floating-point operands, special cases *must* be handled as if the operation is implemented using the standard change of base formula .. math:: \log_{2} x = \frac{\log_{e} x}{\log_{e} 2} @@ -1781,7 +1781,7 @@ def log10(x: array, /) -> array: Calculates an implementation-dependent approximation to the base ``10`` logarithm for each element ``x_i`` of the input array ``x``. .. note:: - For complex floating-point operands, ``log10(conj(x))`` must equal ``conj(log10(x))``. + For complex floating-point operands, ``log10(conj(x))`` *must* equal ``conj(log10(x))``. Parameters ---------- @@ -1791,7 +1791,7 @@ def log10(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -1806,7 +1806,7 @@ def log10(x: array, /) -> array: - If ``x_i`` is ``1``, the result is ``+0``. - If ``x_i`` is ``+infinity``, the result is ``+infinity``. - For complex floating-point operands, special cases must be handled as if the operation is implemented using the standard change of base formula + For complex floating-point operands, special cases *must* be handled as if the operation is implemented using the standard change of base formula .. math:: \log_{10} x = \frac{\log_{e} x}{\log_{e} 10} @@ -1832,7 +1832,7 @@ def logaddexp(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a real-valued 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`. Notes ----- @@ -1852,7 +1852,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 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``. + 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 ---------- @@ -1864,7 +1864,7 @@ def logical_and(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of `bool`. + an array containing the element-wise results. The returned array *must* have a data type of `bool`. """ @@ -1873,7 +1873,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 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``. + 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 ---------- @@ -1883,7 +1883,7 @@ def logical_not(x: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. """ @@ -1892,7 +1892,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 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``. + 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 ---------- @@ -1904,7 +1904,7 @@ def logical_or(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. """ @@ -1913,7 +1913,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 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``. + 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 ---------- @@ -1925,7 +1925,7 @@ def logical_xor(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. """ @@ -1943,7 +1943,7 @@ def maximum(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise maximum values. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise maximum values. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -1976,7 +1976,7 @@ def minimum(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise minimum values. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise minimum values. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2012,7 +2012,7 @@ def multiply(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise products. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2029,7 +2029,7 @@ def multiply(x1: array, x2: array, /) -> array: - If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If ``x1_i`` is either ``+infinity`` or ``-infinity`` and ``x2_i`` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If ``x1_i`` is a nonzero finite number and ``x2_i`` is either ``+infinity`` or ``-infinity``, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - - In the remaining cases, where neither ``infinity`` nor ``NaN`` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. + - In the remaining cases, where neither ``infinity`` nor ``NaN`` is involved, the product *must* be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign. For complex floating-point operands, multiplication is defined according to the following table. For real components ``a`` and ``c`` and imaginary components ``b`` and ``d``, @@ -2043,9 +2043,9 @@ def multiply(x1: array, x2: array, /) -> array: | **a + bj** | (a*c) + (b*c)j | -(b*d) + (a*d)j | special rules | +------------+----------------+-----------------+--------------------------+ - In general, for complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table. + In general, for complex floating-point operands, real-valued floating-point special cases *must* independently apply to the real and imaginary component operations involving real numbers as described in the above table. - When ``a``, ``b``, ``c``, or ``d`` are all finite numbers (i.e., a value other than ``NaN``, ``+infinity``, or ``-infinity``), multiplication of complex floating-point operands should be computed as if calculated according to the textbook formula for complex number multiplication + When ``a``, ``b``, ``c``, or ``d`` are all finite numbers (i.e., a value other than ``NaN``, ``+infinity``, or ``-infinity``), multiplication of complex floating-point operands *should* be computed as if calculated according to the textbook formula for complex number multiplication .. math:: (a + bj) \cdot (c + dj) = (ac - bd) + (bc + ad)j @@ -2071,7 +2071,7 @@ def negative(x: array, /) -> array: For signed integer data types, the numerical negative of the minimum representable integer is implementation-dependent. .. note:: - If ``x`` has a complex floating-point data type, both the real and imaginary components for each ``x_i`` must be negated (a result which follows from the rules of complex number multiplication). + If ``x`` has a complex floating-point data type, both the real and imaginary components for each ``x_i`` *must* be negated (a result which follows from the rules of complex number multiplication). Parameters ---------- @@ -2081,7 +2081,7 @@ def negative(x: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the evaluated result for each element in ``x``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2105,7 +2105,7 @@ def nextafter(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have the same data type as ``x1``. + an array containing the element-wise results. The returned array *must* have the same data type as ``x1``. Notes ----- @@ -2134,7 +2134,7 @@ def not_equal(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type of ``bool``. + an array containing the element-wise results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -2177,7 +2177,7 @@ def positive(x: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the evaluated result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- @@ -2199,7 +2199,7 @@ def pow(x1: array, x2: array, /) -> array: .. note:: By convention, the branch cut of the natural logarithm is the negative real axis :math:`(-\infty, 0)`. - The natural logarithm is a continuous function from above the branch cut, taking into account the sign of the imaginary component. As special cases involving complex floating-point operands should be handled according to ``exp(x2*log(x1))``, exponentiation has the same branch cut for ``x1`` as the natural logarithm (see :func:`~array_api.log`). + The natural logarithm is a continuous function from above the branch cut, taking into account the sign of the imaginary component. As special cases involving complex floating-point operands *should* be handled according to ``exp(x2*log(x1))``, exponentiation has the same branch cut for ``x1`` as the natural logarithm (see :func:`~array_api.log`). *Note: branch cuts follow C99 and have provisional status* (see :ref:`branch-cuts`). @@ -2213,7 +2213,7 @@ def pow(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise results. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2247,7 +2247,7 @@ def pow(x1: array, x2: array, /) -> array: - If ``x1_i`` is ``-0``, ``x2_i`` is less than ``0``, and ``x2_i`` is not an odd integer value, the result is ``+infinity``. - If ``x1_i`` is less than ``0``, ``x1_i`` is a finite number, ``x2_i`` is a finite number, and ``x2_i`` is not an integer value, the result is ``NaN``. - For complex floating-point operands, special cases should be handled as if the operation is implemented as ``exp(x2*log(x1))``. + For complex floating-point operands, special cases *should* be handled as if the operation is implemented as ``exp(x2*log(x1))``. .. note:: Conforming implementations are allowed to treat special cases involving complex floating-point operands more carefully than as described in this specification. @@ -2269,7 +2269,7 @@ def real(x: array, /) -> array: Returns ------- out: array - an array containing the element-wise results. The returned array must have a floating-point data type with the same floating-point precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array must have the floating-point data type ``float32``). + an array containing the element-wise results. The returned array *must* have a floating-point data type with the same floating-point precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array *must* have the floating-point data type ``float32``). Notes ----- @@ -2290,14 +2290,14 @@ def reciprocal(x: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- **Special cases** - For floating-point operands, special cases must be handled as if the operation is implemented as ``1.0 / x`` (see :func:`~array_api.divide`). + For floating-point operands, special cases *must* be handled as if the operation is implemented as ``1.0 / x`` (see :func:`~array_api.divide`). """ @@ -2321,7 +2321,7 @@ def remainder(x1: array, x2: 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 ``x2_i``. The returned array must have a 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 ``x2_i``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2352,7 +2352,7 @@ def remainder(x1: array, x2: array, /) -> array: - If ``x1_i`` is a positive (i.e., greater than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x2_i``. (**note**: this result matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.) - If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.) - - In the remaining cases, the result must match that of the Python ``%`` operator. + - In the remaining cases, the result *must* match that of the Python ``%`` operator. """ @@ -2361,9 +2361,9 @@ def round(x: array, /) -> array: Rounds each element ``x_i`` of the input array ``x`` to the nearest integer-valued number. .. note:: - For complex floating-point operands, real and imaginary components must be independently rounded to the nearest integer-valued number. + For complex floating-point operands, real and imaginary components *must* be independently rounded to the nearest integer-valued number. - Rounded real and imaginary components must be equal to their equivalent rounded real-valued floating-point counterparts (i.e., for complex-valued ``x``, ``real(round(x))`` must equal ``round(real(x)))`` and ``imag(round(x))`` must equal ``round(imag(x))``). + Rounded real and imaginary components *must* be equal to their equivalent rounded real-valued floating-point counterparts (i.e., for complex-valued ``x``, ``real(round(x))`` *must* equal ``round(real(x)))`` and ``imag(round(x))`` *must* equal ``round(imag(x))``). Parameters ---------- @@ -2373,7 +2373,7 @@ def round(x: array, /) -> array: Returns ------- out: array - an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the rounded result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- @@ -2421,7 +2421,7 @@ def sign(x: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the evaluated result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- @@ -2439,7 +2439,7 @@ def sign(x: array, /) -> array: - If ``a`` is either ``-0`` or ``+0`` and ``b`` is either ``-0`` or ``+0``, the result is ``0 + 0j``. - If ``a`` is ``NaN`` or ``b`` is ``NaN``, the result is ``NaN + NaN j``. - - In the remaining cases, special cases must be handled according to the rules of complex number division (see :func:`~array_api.divide`). + - In the remaining cases, special cases *must* be handled according to the rules of complex number division (see :func:`~array_api.divide`). .. versionchanged:: 2022.12 Added complex data type support. @@ -2460,7 +2460,7 @@ def signbit(x: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have a data type of ``bool``. + an array containing the evaluated result for each element in ``x``. The returned array *must* have a data type of ``bool``. Notes ----- @@ -2507,7 +2507,7 @@ def sin(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -2521,7 +2521,7 @@ def sin(x: array, /) -> array: - If ``x_i`` is ``-0``, the result is ``-0``. - If ``x_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as ``-1j * sinh(x*1j)``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as ``-1j * sinh(x*1j)``. .. versionchanged:: 2022.12 Added complex data type support. @@ -2548,7 +2548,7 @@ def sinh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -2556,7 +2556,7 @@ def sinh(x: array, /) -> array: **Special cases** .. note:: - For all operands, ``sinh(x)`` must equal ``-sinh(-x)``. + For all operands, ``sinh(x)`` *must* equal ``-sinh(-x)``. For real-valued floating-point operands, @@ -2569,7 +2569,7 @@ def sinh(x: array, /) -> array: For complex floating-point operands, let ``a = real(x_i)``, ``b = imag(x_i)``, and .. note:: - For complex floating-point operands, ``sinh(conj(x))`` must equal ``conj(sinh(x))``. + For complex floating-point operands, ``sinh(conj(x))`` *must* equal ``conj(sinh(x))``. - If ``a`` is ``+0`` and ``b`` is ``+0``, the result is ``+0 + 0j``. - If ``a`` is ``+0`` and ``b`` is ``+infinity``, the result is ``0 + NaN j`` (sign of the real component is unspecified). @@ -2608,14 +2608,14 @@ def square(x: array, /) -> array: Returns ------- out: array - an array containing the evaluated result for each element in ``x``. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the evaluated result for each element in ``x``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- **Special cases** - For floating-point operands, special cases must be handled as if the operation is implemented as ``x * x`` (see :func:`~array_api.multiply`). + For floating-point operands, special cases *must* be handled as if the operation is implemented as ``x * x`` (see :func:`~array_api.multiply`). .. versionchanged:: 2022.12 Added complex data type support. @@ -2627,10 +2627,10 @@ def sqrt(x: array, /) -> array: Calculates the principal square root for each element ``x_i`` of the input array ``x``. .. note:: - After rounding, each result must be indistinguishable from the infinitely precise result (as required by IEEE 754). + After rounding, each result *must* be indistinguishable from the infinitely precise result (as required by IEEE 754). .. note:: - For complex floating-point operands, ``sqrt(conj(x))`` must equal ``conj(sqrt(x))``. + For complex floating-point operands, ``sqrt(conj(x))`` *must* equal ``conj(sqrt(x))``. .. note:: By convention, the branch cut of the square root is the negative real axis :math:`(-\infty, 0)`. @@ -2649,7 +2649,7 @@ def sqrt(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -2685,7 +2685,7 @@ def subtract(x1: array, x2: array, /) -> array: """ Calculates the difference for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. - The result of ``x1_i - x2_i`` must be the same as ``x1_i + (-x2_i)`` and must be governed by the same floating-point rules as addition (see :meth:`add`). + The result of ``x1_i - x2_i`` *must* be the same as ``x1_i + (-x2_i)`` and *must* be governed by the same floating-point rules as addition (see :meth:`add`). Parameters ---------- @@ -2697,7 +2697,7 @@ def subtract(x1: array, x2: array, /) -> array: Returns ------- out: array - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the element-wise differences. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -2732,7 +2732,7 @@ def tan(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -2746,7 +2746,7 @@ def tan(x: array, /) -> array: - If ``x_i`` is ``-0``, the result is ``-0``. - If ``x_i`` is either ``+infinity`` or ``-infinity``, the result is ``NaN``. - For complex floating-point operands, special cases must be handled as if the operation is implemented as ``-1j * tanh(x*1j)``. + For complex floating-point operands, special cases *must* be handled as if the operation is implemented as ``-1j * tanh(x*1j)``. .. versionchanged:: 2022.12 Added complex data type support. @@ -2775,7 +2775,7 @@ def tanh(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -2783,7 +2783,7 @@ def tanh(x: array, /) -> array: **Special cases** .. note:: - For all operands, ``tanh(-x)`` must equal ``-tanh(x)``. + For all operands, ``tanh(-x)`` *must* equal ``-tanh(x)``. For real-valued floating-point operands, @@ -2796,7 +2796,7 @@ def tanh(x: array, /) -> array: For complex floating-point operands, let ``a = real(x_i)``, ``b = imag(x_i)``, and .. note:: - For complex floating-point operands, ``tanh(conj(x))`` must equal ``conj(tanh(x))``. + For complex floating-point operands, ``tanh(conj(x))`` *must* equal ``conj(tanh(x))``. - If ``a`` is ``+0`` and ``b`` is ``+0``, the result is ``+0 + 0j``. - If ``a`` is a nonzero finite number and ``b`` is ``+infinity``, the result is ``NaN + NaN j``. @@ -2832,7 +2832,7 @@ def trunc(x: array, /) -> array: Returns ------- out: array - an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. + an array containing the rounded result for each element in ``x``. The returned array *must* have the same data type as ``x``. Notes ----- diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 7a4538ccb..338edcc5d 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -30,22 +30,22 @@ def fft( Computes the one-dimensional discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex floating-point data type. n: Optional[int] - number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``M``. - - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. - - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` *must* be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` *must* be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -58,7 +58,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have the same data type as ``x`` and *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n``. Notes ----- @@ -82,22 +82,22 @@ def ifft( Computes the one-dimensional inverse discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex floating-point data type. n: Optional[int] - number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``M``. - - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. - - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` *must* be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` *must* be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -110,7 +110,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have the same data type as ``x`` and *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n``. Notes ----- @@ -134,24 +134,24 @@ def fftn( Computes the n-dimensional discrete Fourier transform. .. note:: - Applying the n-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode). + Applying the n-dimensional inverse discrete Fourier transform to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode). Parameters ---------- x: array input array. Should have a complex floating-point data type. s: Optional[Sequence[int]] - number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function *must* set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. - - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. - - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. - - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` *must* be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` *must* be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` *must* be used when computing the transform. - If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. + If ``s`` is not ``None``, ``axes`` *must not* be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the transform. A valid axis in ``axes`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). + axes (dimensions) over which to compute the transform. A valid axis in ``axes`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed *must* also be provided. If ``axes`` is ``None``, the function *must* compute the transform over all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. norm: Literal['backward', 'ortho', 'forward'] @@ -168,7 +168,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array *must* have the same data type as ``x`` and *must* have the same shape as ``x``, except for the axes specified by ``axes`` which *must* have size ``s[i]``. Notes ----- @@ -192,24 +192,24 @@ def ifftn( Computes the n-dimensional inverse discrete Fourier transform. .. note:: - Applying the n-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode). + Applying the n-dimensional inverse discrete Fourier transform to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode). Parameters ---------- x: array input array. Should have a complex floating-point data type. s: Optional[Sequence[int]] - number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function *must* set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. - - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. - - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. - - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` *must* be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` *must* be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` *must* be used when computing the transform. - If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. + If ``s`` is not ``None``, ``axes`` *must not* be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the transform. A valid axis in ``axes`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). + axes (dimensions) over which to compute the transform. A valid axis in ``axes`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed *must* also be provided. If ``axes`` is ``None``, the function *must* compute the transform over all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. norm: Literal['backward', 'ortho', 'forward'] @@ -226,7 +226,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array *must* have the same data type as ``x`` and *must* have the same shape as ``x``, except for the axes specified by ``axes`` which *must* have size ``s[i]``. Notes ----- @@ -250,22 +250,22 @@ def rfft( Computes the one-dimensional discrete Fourier transform for real-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent values for the number of elements over which to compute the transforms. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- x: array input array. Must have a real-valued floating-point data type. n: Optional[int] - number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``M``. - - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. - - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` *must* be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` *must* be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -278,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array *must* have a ``complex128`` data type). The returned array *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n//2 + 1``. Notes ----- @@ -299,22 +299,22 @@ def irfft( Computes the one-dimensional inverse of ``rfft`` for complex-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent values for the number of elements over which to compute the transforms. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- x: array input array. Should have a complex floating-point data type. n: Optional[int] - number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``2*(M-1)``. - - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to size ``n//2+1``. - - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. - - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` *must* be zero-padded to size ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` *must* be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -327,12 +327,12 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). The returned array *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n``. Notes ----- - - In order to return an array having an odd number of elements along the transformed axis, the function must be provided an odd integer for ``n``. + - In order to return an array having an odd number of elements along the transformed axis, the function *must* be provided an odd integer for ``n``. .. versionadded:: 2022.12 @@ -353,24 +353,24 @@ def rfftn( Computes the n-dimensional discrete Fourier transform for real-valued input. .. note:: - Applying the n-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes. + Applying the n-dimensional inverse discrete Fourier transform for real-valued input to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes. Parameters ---------- x: array input array. Must have a real-valued floating-point data type. s: Optional[Sequence[int]] - number of elements over which to compute the transform along axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. + number of elements over which to compute the transform along axes (dimensions) specified by ``axes``. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function *must* set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``. - - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. - - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. - - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` *must* be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` *must* be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` *must* be used when computing the transform. - If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. + If ``s`` is not ``None``, ``axes`` *must not* be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the transform. A valid axis in ``axes`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). + axes (dimensions) over which to compute the transform. A valid axis in ``axes`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed *must* also be provided. If ``axes`` is ``None``, the function *must* compute the transform over all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. norm: Literal['backward', 'ortho', 'forward'] @@ -387,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the last transformed axis which must have size ``s[-1]//2 + 1`` and the remaining transformed axes which must have size ``s[i]``. + an array transformed along the axes (dimension) specified by ``axes``. The returned array *must* have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array *must* have a ``complex128`` data type). The returned array *must* have the same shape as ``x``, except for the last transformed axis which *must* have size ``s[-1]//2 + 1`` and the remaining transformed axes which *must* have size ``s[i]``. Notes ----- @@ -408,24 +408,24 @@ def irfftn( Computes the n-dimensional inverse of ``rfftn`` for complex-valued input. .. note:: - Applying the n-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes. + Applying the n-dimensional inverse discrete Fourier transform for real-valued input to the output of this function *must* return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes. Parameters ---------- x: array input array. Should have a complex floating-point data type. s: Optional[Sequence[int]] - number of elements along the transformed axes (dimensions) specified by ``axes`` in the **output array**. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``, except for the last transformed axis in which ``s[i]`` equals ``2*(M[i]-1)``. For each ``i``, let ``n`` equal ``s[i]``, except for the last transformed axis in which ``n`` equals ``s[i]//2+1``. + number of elements along the transformed axes (dimensions) specified by ``axes`` in the **output array**. Let ``i`` be the index of the ``n``-th axis specified by ``axes`` (i.e., ``i = axes[n]``) and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function *must* set ``s`` equal to a sequence of integers such that ``s[i]`` equals ``M[i]`` for all ``i``, except for the last transformed axis in which ``s[i]`` equals ``2*(M[i]-1)``. For each ``i``, let ``n`` equal ``s[i]``, except for the last transformed axis in which ``n`` equals ``s[i]//2+1``. - - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array must be zero-padded to size ``n``. - - If ``n`` is less than ``M[i]``, axis ``i`` of the input array must be trimmed to size ``n``. - - If ``n`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` of the input array must be used when computing the transform. + - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array *must* be zero-padded to size ``n``. + - If ``n`` is less than ``M[i]``, axis ``i`` of the input array *must* be trimmed to size ``n``. + - If ``n`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` of the input array *must* be used when computing the transform. - If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. + If ``s`` is not ``None``, ``axes`` *must not* be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the transform. A valid axis in ``axes`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). + axes (dimensions) over which to compute the transform. A valid axis in ``axes`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed *must* also be provided. If ``axes`` is ``None``, the function *must* compute the transform over all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. norm: Literal['backward', 'ortho', 'forward'] @@ -442,12 +442,12 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the transformed axes which must have size ``s[i]``. + an array transformed along the axes (dimension) specified by ``axes``. The returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). The returned array *must* have the same shape as ``x``, except for the transformed axes which *must* have size ``s[i]``. Notes ----- - - In order to return an array having an odd number of elements along the last transformed axis, the function must be provided an odd integer for ``s[-1]``. + - In order to return an array having an odd number of elements along the last transformed axis, the function *must* be provided an odd integer for ``s[-1]``. .. versionadded:: 2022.12 @@ -472,15 +472,15 @@ def hfft( x: array input array. Should have a complex floating-point data type. n: Optional[int] - number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``2*(M-1)``. - - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to length ``n//2+1``. - - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. - - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` *must* be zero-padded to length ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` *must* be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). The returned array *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n``. Notes ----- @@ -521,15 +521,15 @@ def ihfft( x: array input array. Must have a real-valued floating-point data type. n: Optional[int] - number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function *must* set ``n`` equal to ``M``. - - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. - - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` *must* be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` *must* be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` *must* be used when computing the transform. Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -542,7 +542,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. + an array transformed along the axis (dimension) specified by ``axis``. The returned array *must* have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array *must* have a ``complex128`` data type). The returned array *must* have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have size ``n//2 + 1``. Notes ----- @@ -574,7 +574,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar Returns ------- out: array - an array of shape ``(n,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. + an array of shape ``(n,)`` containing the sample frequencies. The returned array *must* have the default real-valued floating-point data type. Notes ----- @@ -611,7 +611,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a Returns ------- out: array - an array of shape ``(n//2+1,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. + an array of shape ``(n//2+1,)`` containing the sample frequencies. The returned array *must* have the default real-valued floating-point data type. Notes ----- @@ -637,14 +637,14 @@ def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) - x: array input array. Should have a floating-point data type. axes: Optional[Union[int, Sequence[int]]] - axes over which to shift. If ``None``, the function must shift all axes. Default: ``None``. + axes over which to shift. If ``None``, the function *must* shift all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. Returns ------- out: array - the shifted array. The returned array must have the same data type and shape as ``x``. + the shifted array. The returned array *must* have the same data type and shape as ``x``. Notes ----- @@ -667,14 +667,14 @@ def ifftshift( x: array input array. Should have a floating-point data type. axes: Optional[Union[int, Sequence[int]]] - axes over which to perform the inverse shift. If ``None``, the function must shift all axes. Default: ``None``. + axes over which to perform the inverse shift. If ``None``, the function *must* shift all axes. Default: ``None``. If ``axes`` contains two or more entries which resolve to the same axis (i.e., resolved axes are not unique), the behavior is unspecified and thus implementation-defined. Returns ------- out: array - the shifted array. The returned array must have the same data type and shape as ``x``. + the shifted array. The returned array *must* have the same data type and shape as ``x``. Notes ----- diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py index a9b38b482..14bc45fad 100644 --- a/src/array_api_stubs/_draft/indexing_functions.py +++ b/src/array_api_stubs/_draft/indexing_functions.py @@ -15,20 +15,20 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array: x: array input array. indices: array - array indices. The array must be one-dimensional and have an integer data type. + array indices. The array *must* be one-dimensional and have an integer data type. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified. axis: Optional[int] - axis over which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension. + axis over which to select values. If ``axis`` is negative, the function *must* determine the axis along which to select values by counting from the last dimension. If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. Returns ------- out: array - an array having the same data type as ``x``. The output array must have the same rank (i.e., number of dimensions) as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` whose size must equal the number of elements in ``indices``. + an array having the same data type as ``x``. The output array *must* have the same rank (i.e., number of dimensions) as ``x`` and *must* have the same shape as ``x``, except for the axis specified by ``axis`` whose size *must* equal the number of elements in ``indices``. Notes ----- @@ -55,10 +55,10 @@ def take_along_axis(x: array, indices: array, /, *, axis: int = -1) -> array: This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified. axis: int - axis along which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension. Default: ``-1``. + axis along which to select values. If ``axis`` is negative, the function *must* determine the axis along which to select values by counting from the last dimension. Default: ``-1``. Returns ------- out: array - an array having the same data type as ``x``. Must have the same rank (i.e., number of dimensions) as ``x`` and must have a shape determined according to :ref:`broadcasting`, except for the axis (dimension) specified by ``axis`` whose size must equal the size of the corresponding axis (dimension) in ``indices``. + an array having the same data type as ``x``. Must have the same rank (i.e., number of dimensions) as ``x`` and *must* have a shape determined according to :ref:`broadcasting`, except for the axis (dimension) specified by ``axis`` whose size *must* equal the size of the corresponding axis (dimension) in ``indices``. """ diff --git a/src/array_api_stubs/_draft/info.py b/src/array_api_stubs/_draft/info.py index 6177fb12f..262eb78be 100644 --- a/src/array_api_stubs/_draft/info.py +++ b/src/array_api_stubs/_draft/info.py @@ -54,11 +54,11 @@ def capabilities() -> Capabilities: """ Returns a dictionary of array library capabilities. - The dictionary must contain the following keys: + The dictionary *must* contain the following keys: - - `"boolean indexing"`: boolean indicating whether an array library supports boolean indexing. If a conforming implementation fully supports boolean indexing in compliance with this specification (see :ref:`indexing`), the corresponding dictionary value must be ``True``; otherwise, the value must be ``False``. - - `"data-dependent shapes"`: boolean indicating whether an array library supports data-dependent output shapes. If a conforming implementation fully supports all APIs included in this specification (excluding boolean indexing) which have data-dependent output shapes, as explicitly demarcated throughout the specification, the corresponding dictionary value must be ``True``; otherwise, the value must be ``False``. - - `"max dimensions"`: maximum number of supported dimensions. If a conforming implementation supports arrays having an arbitrary number of dimensions (potentially infinite), the corresponding dictionary value must be ``None``; otherwise, the value must be a finite integer. + - `"boolean indexing"`: boolean indicating whether an array library supports boolean indexing. If a conforming implementation fully supports boolean indexing in compliance with this specification (see :ref:`indexing`), the corresponding dictionary value *must* be ``True``; otherwise, the value *must* be ``False``. + - `"data-dependent shapes"`: boolean indicating whether an array library supports data-dependent output shapes. If a conforming implementation fully supports all APIs included in this specification (excluding boolean indexing) which have data-dependent output shapes, as explicitly demarcated throughout the specification, the corresponding dictionary value *must* be ``True``; otherwise, the value *must* be ``False``. + - `"max dimensions"`: maximum number of supported dimensions. If a conforming implementation supports arrays having an arbitrary number of dimensions (potentially infinite), the corresponding dictionary value *must* be ``None``; otherwise, the value *must* be a finite integer. Returns ------- @@ -95,22 +95,22 @@ def default_dtypes( """ Returns a dictionary containing default data types. - The dictionary must have the following keys: + The dictionary *must* have the following keys: - `"real floating"`: default real floating-point data type. - `"complex floating"`: default complex floating-point data type. - `"integral"`: default integral data type. - `"indexing"`: default array index data type. - Dictionary values must be the corresponding data type object. + Dictionary values *must* be the corresponding data type object. Parameters ---------- device: Optional[device] - device for which to return default data types. If ``device`` is ``None``, the returned data types must be the default data types for the current device; otherwise, the returned data types must be default data types specific to the specified device. Default: ``None``. + device for which to return default data types. If ``device`` is ``None``, the returned data types *must* be the default data types for the current device; otherwise, the returned data types *must* be default data types specific to the specified device. Default: ``None``. .. note:: - Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context should return the default data types for the current device. For libraries without a context manager or supporting only a single device, those libraries should return the default data types for the default device. + Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context *should* return the default data types for the current device. For libraries without a context manager or supporting only a single device, those libraries *should* return the default data types for the default device. Returns ------- @@ -133,19 +133,19 @@ def dtypes( Returns a dictionary of supported *Array API* data types. .. note:: - While specification-conforming array libraries may support additional data types which are not present in this specification, data types which are not present in this specification should not be included in the returned dictionary. + While specification-conforming array libraries may support additional data types which are not present in this specification, data types which are not present in this specification *should not* be included in the returned dictionary. .. note:: - Specification-conforming array libraries must only return supported data types having expected properties as described in :ref:`data-types`. For example, if a library decides to alias ``float32`` as ``float64``, that library must not include ``float64`` in the dictionary of supported data types. + Specification-conforming array libraries must only return supported data types having expected properties as described in :ref:`data-types`. For example, if a library decides to alias ``float32`` as ``float64``, that library *must not* include ``float64`` in the dictionary of supported data types. Parameters ---------- kind: Optional[Union[str, Tuple[str, ...]]] data type kind. - - If ``kind`` is ``None``, the function must return a dictionary containing all supported Array API data types. + - If ``kind`` is ``None``, the function *must* return a dictionary containing all supported Array API data types. - - If ``kind`` is a string, the function must return a dictionary containing the data types belonging to the specified data type kind. The following data type kinds must be supported: + - If ``kind`` is a string, the function *must* return a dictionary containing the data types belonging to the specified data type kind. The following data type kinds *must* be supported: - ``'bool'``: boolean data types (e.g., ``bool``). - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). @@ -155,14 +155,14 @@ def dtypes( - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). - ``'numeric'``: numeric data types. Shorthand for ``('integral', 'real floating', 'complex floating')``. - - If ``kind`` is a tuple, the tuple specifies a union of data type kinds, and the function must return a dictionary containing the data types belonging to at least one of the specified data type kinds. + - If ``kind`` is a tuple, the tuple specifies a union of data type kinds, and the function *must* return a dictionary containing the data types belonging to at least one of the specified data type kinds. Default: ``None``. device: Optional[device] - device for which to return supported data types. If ``device`` is ``None``, the returned data types must be the supported data types for the current device; otherwise, the returned data types must be supported data types specific to the specified device. Default: ``None``. + device for which to return supported data types. If ``device`` is ``None``, the returned data types *must* be the supported data types for the current device; otherwise, the returned data types *must* be supported data types specific to the specified device. Default: ``None``. .. note:: - Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context should return the supported data types for the current device. For libraries without a context manager or supporting only a single device, those libraries should return the supported data types for the default device. + Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context *should* return the supported data types for the current device. For libraries without a context manager or supporting only a single device, those libraries *should* return the supported data types for the default device. Returns ------- @@ -170,7 +170,7 @@ def dtypes( a dictionary containing supported data types. .. note:: - Dictionary keys must only consist of canonical names as defined in :ref:`data-types`. + Dictionary keys *must* only consist of canonical names as defined in :ref:`data-types`. Notes ----- @@ -191,7 +191,7 @@ def devices() -> List[device]: Notes ----- - Each device object (see :ref:`device-support`) in the list of returned devices must be an object which can be provided as a valid keyword-argument to array creation functions. + Each device object (see :ref:`device-support`) in the list of returned devices *must* be an object which can be provided as a valid keyword-argument to array creation functions. Notes ----- diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index a1c9fe028..0d41b0470 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -49,7 +49,7 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: where :math:`U` is an upper triangular matrix. - When ``x`` is a stack of matrices, the function must compute the Cholesky decomposition for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the Cholesky decomposition for each matrix in the stack. .. note:: Whether an array library explicitly checks whether an input array is Hermitian or a symmetric positive-definite matrix (or a stack of matrices) is implementation-defined. @@ -59,12 +59,12 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: x: array input array having shape ``(..., M, M)`` and whose innermost two dimensions form square complex Hermitian or real symmetric positive-definite matrices. Should have a floating-point data type. upper: bool - If ``True``, the result must be the upper-triangular Cholesky factor :math:`U`. If ``False``, the result must be the lower-triangular Cholesky factor :math:`L`. Default: ``False``. + If ``True``, the result *must* be the upper-triangular Cholesky factor :math:`U`. If ``False``, the result *must* be the lower-triangular Cholesky factor :math:`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 floating-point data type determined by :ref:`type-promotion` and *must* have the same shape as ``x``. Notes ----- @@ -83,20 +83,20 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: Parameters ---------- x1: array - first input array. Must have a numeric data type. The size of the axis over which the cross product is to be computed must be equal to 3. + first input array. Must have a numeric data type. The size of the axis over which the cross product is to be computed *must* be equal to 3. x2: array - second input array. Must be broadcast compatible with ``x1`` along all axes other than the axis along which the cross-product is computed (see :ref:`broadcasting`). The size of the axis over which the cross product is to be computed must be equal to 3. Must have a numeric data type. + second input array. Must be broadcast compatible with ``x1`` along all axes other than the axis along which the cross-product is computed (see :ref:`broadcasting`). The size of the axis over which the cross product is to be computed *must* be equal to 3. Must have a numeric data type. .. note:: - The compute axis (dimension) must not be broadcasted. + The compute axis (dimension) *must not* be broadcasted. axis: int - the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. Should be an integer on the interval ``[-N, -1]``, where ``N`` is ``min(x1.ndim, x2.ndim)``. The function must determine the axis along which to compute the cross product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function must compute the cross product over the last axis. Default: ``-1``. + the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. Should be an integer on the interval ``[-N, -1]``, where ``N`` is ``min(x1.ndim, x2.ndim)``. The function *must* determine the axis along which to compute the cross product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function *must* compute the cross product over the last axis. Default: ``-1``. Returns ------- out: array - an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the cross products. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes @@ -129,7 +129,7 @@ def det(x: array, /) -> array: Returns ------- out: array - if ``x`` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have the same data type as ``x``. + if ``x`` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array *must* have the same data type as ``x``. Notes ----- @@ -159,7 +159,7 @@ def diagonal(x: array, /, *, offset: int = 0) -> array: Returns ------- out: array - an array containing the diagonals and whose shape is determined by removing the last two dimensions and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as ``x``. + an array containing the diagonals and whose shape is determined by removing the last two dimensions and appending a dimension equal to the size of the resulting diagonals. The returned array *must* have the same data type as ``x``. """ @@ -200,8 +200,8 @@ def eigh(x: array, /) -> Tuple[array]: out: Tuple[array] a namedtuple (``eigenvalues``, ``eigenvectors``) whose - - first element must have the field name ``eigenvalues`` (corresponding to :math:`\operatorname{diag}\Lambda` above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape ``(..., M)`` and must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then ``eigenvalues`` must be ``float64``). - - second element have have the field name ``eigenvectors`` (corresponding to :math:`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)`` and must have the same data type as ``x``. + - first element *must* have the field name ``eigenvalues`` (corresponding to :math:`\operatorname{diag}\Lambda` above) and *must* be an array consisting of computed eigenvalues. The array containing the eigenvalues *must* have shape ``(..., M)`` and *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then ``eigenvalues`` *must* be ``float64``). + - second element have have the field name ``eigenvectors`` (corresponding to :math:`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)`` and *must* have the same data type as ``x``. Notes ----- @@ -244,7 +244,7 @@ def eigvalsh(x: array, /) -> array: Returns ------- out: array - an array containing the computed eigenvalues. The returned array must have shape ``(..., M)`` and have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then must have a ``float64`` data type). + an array containing the computed eigenvalues. The returned array *must* have shape ``(..., M)`` and have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then *must* have a ``float64`` data type). Notes ----- @@ -272,7 +272,7 @@ def inv(x: array, /) -> array: The inverse matrix exists if and only if ``x`` is invertible. When ``x`` is invertible, the inverse is unique. - When ``x`` is a stack of matrices, the function must compute the inverse for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the inverse for each matrix in the stack. Parameters ---------- @@ -282,7 +282,7 @@ def inv(x: array, /) -> array: 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 floating-point data type determined by :ref:`type-promotion` and *must* have the same shape as ``x``. Notes ----- @@ -311,9 +311,9 @@ def matrix_norm( x: array input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a 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``. + 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']]] - order of the norm. The following mathematical norms must be supported: + order of the norm. The following mathematical norms *must* be supported: +------------------+---------------------------------+ | ord | description | @@ -329,7 +329,7 @@ def matrix_norm( | inf | max(sum(abs(x), axis=1)) | +------------------+---------------------------------+ - The following non-mathematical "norms" must be supported: + The following non-mathematical "norms" *must* be supported: +------------------+---------------------------------+ | ord | description | @@ -352,7 +352,7 @@ def matrix_norm( 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``. If ``x`` has a real-valued data type, the returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` has a complex-valued data type, the returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). + 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``. If ``x`` has a real-valued data type, the returned array *must* have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` has a complex-valued data type, the returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). Notes ----- @@ -376,7 +376,7 @@ def matrix_power(x: array, n: int, /) -> array: 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -390,19 +390,19 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a """ Returns the rank (i.e., number of non-zero singular values) of a matrix (or a stack of matrices). - When ``x`` is a stack of matrices, the function must compute the number of non-zero singular values for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the number of non-zero singular values for each matrix in the stack. Parameters ---------- x: array input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a 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 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``. + 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 the default integer data type 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 the default integer data type and *must* have shape ``(...)`` (i.e., *must* have a shape equal to ``shape(x)[:-2]``). Notes ----- @@ -430,7 +430,7 @@ def outer(x1: array, x2: array, /) -> array: Returns ------- out: array - a two-dimensional array containing the outer product and whose shape is ``(N, M)``. The returned array must have a data type determined by :ref:`type-promotion`. + a two-dimensional array containing the outer product and whose shape is ``(N, M)``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -458,19 +458,19 @@ def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: where :math:`U` and :math:`V^H` are orthogonal matrices, :math:`\Sigma` is a diagonal matrix consisting of :math:`A`'s singular values, and :math:`\Sigma^{+}` is then a diagonal matrix consisting of the reciprocals of :math:`A`'s singular values, leaving zeros in place. During numerical computation, only elements larger than a small tolerance are considered nonzero, and all others replaced by zeros. - When ``x`` is a stack of matrices, the function must compute the pseudo-inverse for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the pseudo-inverse for each matrix in the stack. Parameters ---------- x: array input array having shape ``(..., M, N)`` and whose innermost two dimensions form ``MxN`` matrices. Should have a 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 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``. + 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-inverse(s). 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-inverse(s). 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). Notes ----- @@ -504,7 +504,7 @@ def qr( The reduced QR decomposition equals with the complete QR decomposition when :math:`n \geq m` (wide matrix). - When ``x`` is a stack of matrices, the function must compute the QR decomposition for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the QR decomposition for each matrix in the stack. .. note:: Whether an array library explicitly checks whether an input array is a full column rank matrix (or a stack of full column rank matrices) is implementation-defined. @@ -532,10 +532,10 @@ def qr( out: Tuple[array, array] a namedtuple ``(Q, R)`` whose - - 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``. + - 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 floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -562,20 +562,20 @@ def slogdet(x: array, /) -> Tuple[array, array]: where :math:`|\det x|` is the absolute value of the determinant of ``x``. - When ``x`` is a stack of matrices, the function must compute the sign and natural logarithm of the absolute value of the determinant for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the sign and natural logarithm of the absolute value of the determinant for each matrix in the stack. **Special Cases** For real-valued floating-point operands, - - If the determinant is zero, the ``sign`` should be ``0`` and ``logabsdet`` should be ``-infinity``. + - If the determinant is zero, the ``sign`` *should* be ``0`` and ``logabsdet`` *should* be ``-infinity``. For complex floating-point operands, - - If the determinant is ``0 + 0j``, the ``sign`` should be ``0 + 0j`` and ``logabsdet`` should be ``-infinity + 0j``. + - If the determinant is ``0 + 0j``, the ``sign`` *should* be ``0 + 0j`` and ``logabsdet`` *should* be ``-infinity + 0j``. .. note:: - Depending on the underlying algorithm, when the determinant is zero, the returned result may differ from ``-infinity`` (or ``-infinity + 0j``). In all cases, the determinant should be equal to ``sign * exp(logabsdet)`` (although, again, the result may be subject to numerical precision errors). + Depending on the underlying algorithm, when the determinant is zero, the returned result may differ from ``-infinity`` (or ``-infinity + 0j``). In all cases, the determinant *should* be equal to ``sign * exp(logabsdet)`` (although, again, the result may be subject to numerical precision errors). Parameters ---------- @@ -587,10 +587,10 @@ def slogdet(x: array, /) -> Tuple[array, array]: out: Tuple[array, array] a namedtuple (``sign``, ``logabsdet``) whose - - first element must have the field name ``sign`` and must be an array containing a number representing the sign of the determinant for each square matrix. Must have the same data type as ``x``. - - second element must have the field name ``logabsdet`` and must be an array containing the natural logarithm of the absolute value of the determinant for each square matrix. If ``x`` is real-valued, the returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` is complex, the returned array must have a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, ``logabsdet`` must have a ``float32`` data type). + - first element *must* have the field name ``sign`` and *must* be an array containing a number representing the sign of the determinant for each square matrix. Must have the same data type as ``x``. + - second element *must* have the field name ``logabsdet`` and *must* be an array containing the natural logarithm of the absolute value of the determinant for each square matrix. If ``x`` is real-valued, the returned array *must* have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` is complex, the returned array *must* have a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, ``logabsdet`` *must* have a ``float32`` data type). - Each returned array must have shape ``shape(x)[:-2]``. + Each returned array *must* have shape ``shape(x)[:-2]``. Notes ----- @@ -616,19 +616,19 @@ def solve(x1: array, x2: array, /) -> array: .. note:: Whether an array library explicitly checks whether ``x1`` is invertible is implementation-defined. - When ``x1`` and/or ``x2`` is a stack of matrices, the function must compute a solution for each matrix in the stack. + When ``x1`` and/or ``x2`` is a stack of matrices, the function *must* compute a solution for each matrix in the stack. 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 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)[:-2]`` must be compatible with ``shape(x1)[:-2]`` (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)[:-2]`` *must* be compatible with ``shape(x1)[:-2]`` (see :ref:`broadcasting`). Should have a floating-point data type. Returns ------- out: array - an array containing the solution to the system ``AX = B`` for each square matrix. If ``x2`` has shape ``(M,)``, the returned array must have shape equal to ``shape(x1)[:-2] + shape(x2)[-1:]``. Otherwise, if ``x2`` has shape ``(..., M, K)```, the returned array must have shape equal to ``(..., M, K)``, where ``...`` refers to the result of broadcasting ``shape(x1)[:-2]`` and ``shape(x2)[:-2]``. The returned array 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. If ``x2`` has shape ``(M,)``, the returned array *must* have shape equal to ``shape(x1)[:-2] + shape(x2)[-1:]``. Otherwise, if ``x2`` has shape ``(..., M, K)```, the returned array *must* have shape equal to ``(..., M, K)``, where ``...`` refers to the result of broadcasting ``shape(x1)[:-2]`` and ``shape(x2)[:-2]``. The returned array *must* have a floating-point data type determined by :ref:`type-promotion`. Notes ----- @@ -662,7 +662,7 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Tuple[array, array, array This function returns the decomposition :math:`U`, :math:`S`, and :math:`V^H`, where :math:`S = \operatorname{diag}(\Sigma)`. - When ``x`` is a stack of matrices, the function must compute the singular value decomposition for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the singular value decomposition for each matrix in the stack. .. warning:: The returned arrays :math:`U` and :math:`V` are neither unique nor continuous with respect to ``x``. Because :math:`U` and :math:`V` are not unique, different hardware and software may compute different singular vectors. @@ -681,9 +681,9 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Tuple[array, array, array out: Tuple[array, array, array] a namedtuple ``(U, S, Vh)`` whose - - first element must have the field name ``U`` and must be an array whose shape depends on the value of ``full_matrices`` and contain matrices with orthonormal columns (i.e., the columns are left singular vectors). If ``full_matrices`` is ``True``, the array must have shape ``(..., M, M)``. If ``full_matrices`` is ``False``, the array must have shape ``(..., M, K)``, where ``K = min(M, N)``. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. Must have the same data type as ``x``. - - 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``. Must have a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, ``S`` must have a ``float32`` data type). - - 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``. Must have the same data type as ``x``. + - first element *must* have the field name ``U`` and *must* be an array whose shape depends on the value of ``full_matrices`` and contain matrices with orthonormal columns (i.e., the columns are left singular vectors). If ``full_matrices`` is ``True``, the array *must* have shape ``(..., M, M)``. If ``full_matrices`` is ``False``, the array *must* have shape ``(..., M, K)``, where ``K = min(M, N)``. The first ``x.ndim-2`` dimensions *must* have the same shape as those of the input ``x``. Must have the same data type as ``x``. + - 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``. Must have a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, ``S`` *must* have a ``float32`` data type). + - 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``. Must have the same data type as ``x``. Notes ----- @@ -697,7 +697,7 @@ def svdvals(x: array, /) -> array: """ Returns the singular values of a matrix (or a stack of matrices) ``x``. - When ``x`` is a stack of matrices, the function must compute the singular values for each matrix in the stack. + When ``x`` is a stack of matrices, the function *must* compute the singular values for each matrix in the stack. Parameters ---------- @@ -707,7 +707,7 @@ def svdvals(x: array, /) -> array: 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 a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array must have a ``float32`` data type). + 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 a real-valued floating-point data type having the same precision as ``x`` (e.g., if ``x`` is ``complex64``, the returned array *must* have a ``float32`` data type). Notes ----- @@ -744,12 +744,12 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr Default: ``0``. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array *must* have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - - 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). + - 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). - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array *should* be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. Returns ------- @@ -760,7 +760,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr out[i, j, k, ..., l] = trace(a[i, j, k, ..., l, :, :]) - The returned array must have a data type as described by the ``dtype`` parameter above. + The returned array *must* have a data type as described by the ``dtype`` parameter above. Notes ----- @@ -771,7 +771,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr - If ``N`` is ``0``, the sum is ``0`` (i.e., the empty sum). - For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + For both real-valued and complex floating-point operands, special cases *must* be handled as if the operation is implemented by successive application of :func:`~array_api.add`. .. versionchanged:: 2022.12 Added complex data type support. @@ -801,11 +801,11 @@ def vector_norm( x: array input array. Should have a 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``. + 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 - If ``True``, the axes (dimensions) specified by ``axis`` 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 axes (dimensions) specified by ``axis`` must not be included in the result. Default: ``False``. + If ``True``, the axes (dimensions) specified by ``axis`` 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 axes (dimensions) specified by ``axis`` *must not* be included in the result. Default: ``False``. ord: Union[int, float, Literal[inf, -inf]] - order of the norm. The following mathematical norms must be supported: + order of the norm. The following mathematical norms *must* be supported: +------------------+----------------------------+ | ord | description | @@ -819,7 +819,7 @@ def vector_norm( | (int,float >= 1) | p-norm | +------------------+----------------------------+ - The following non-mathematical "norms" must be supported: + The following non-mathematical "norms" *must* be supported: +------------------+--------------------------------+ | ord | description | @@ -840,7 +840,7 @@ def vector_norm( 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``. If ``x`` has a real-valued data type, the returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` has a complex-valued data type, the returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). + 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``. If ``x`` has a real-valued data type, the returned array *must* have a real-valued floating-point data type determined by :ref:`type-promotion`. If ``x`` has a complex-valued data type, the returned array *must* have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array *must* have a ``float64`` data type). Notes ----- diff --git a/src/array_api_stubs/_draft/linear_algebra_functions.py b/src/array_api_stubs/_draft/linear_algebra_functions.py index da4c97743..31dbd0c2d 100644 --- a/src/array_api_stubs/_draft/linear_algebra_functions.py +++ b/src/array_api_stubs/_draft/linear_algebra_functions.py @@ -9,31 +9,31 @@ def matmul(x1: array, x2: array, /) -> array: Computes the matrix product. .. note:: - The ``matmul`` function must implement the same semantics as the built-in ``@`` operator (see `PEP 465 `_). + The ``matmul`` function *must* implement the same semantics as the built-in ``@`` operator (see `PEP 465 `_). 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 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. 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 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. .. note:: - If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument must be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the matrix product. + If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument *must* be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations *should* be explicitly performed prior to computing the matrix product. Returns ------- out: array - if both ``x1`` and ``x2`` are one-dimensional arrays having shape ``(N,)``, a zero-dimensional array containing the inner product as its only element. - if ``x1`` is a two-dimensional array having shape ``(M, K)`` and ``x2`` is a two-dimensional array having shape ``(K, N)``, a two-dimensional array containing the `conventional matrix product `_ and having shape ``(M, N)``. - - if ``x1`` is a one-dimensional array having shape ``(K,)`` and ``x2`` is an array having shape ``(..., K, N)``, an array having shape ``(..., N)`` (i.e., prepended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product `_. - - if ``x1`` is an array having shape ``(..., M, K)`` and ``x2`` is a one-dimensional array having shape ``(K,)``, an array having shape ``(..., M)`` (i.e., appended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product `_. + - if ``x1`` is a one-dimensional array having shape ``(K,)`` and ``x2`` is an array having shape ``(..., K, N)``, an array having shape ``(..., N)`` (i.e., prepended dimensions during vector-to-matrix promotion *must* be removed) and containing the `conventional matrix product `_. + - if ``x1`` is an array having shape ``(..., M, K)`` and ``x2`` is a one-dimensional array having shape ``(K,)``, an array having shape ``(..., M)`` (i.e., appended dimensions during vector-to-matrix promotion *must* be removed) and containing the `conventional matrix product `_. - if ``x1`` is a two-dimensional array having shape ``(M, K)`` and ``x2`` is an array having shape ``(..., K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product `_ for each stacked matrix. - if ``x1`` is an array having shape ``(..., M, K)`` and ``x2`` is a two-dimensional array having shape ``(K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product `_ for each stacked matrix. - if either ``x1`` or ``x2`` has more than two dimensions, an array having a shape determined by :ref:`broadcasting` ``shape(x1)[:-2]`` against ``shape(x2)[:-2]`` and containing the `conventional matrix product `_ for each stacked matrix. - The returned array must have a data type determined by :ref:`type-promotion`. + The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -64,7 +64,7 @@ def matrix_transpose(x: array, /) -> array: Returns ------- out: array - an array containing the transpose for each matrix and having shape ``(..., N, M)``. The returned array must have the same data type as ``x``. + an array containing the transpose for each matrix and having shape ``(..., N, M)``. The returned array *must* have the same data type as ``x``. """ @@ -86,30 +86,30 @@ def tensordot( x1: array first input array. Should have a numeric 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 numeric data type. Corresponding contracted axes of ``x1`` and ``x2`` *must* be equal. .. note:: - Contracted axes (dimensions) must not be broadcasted. + Contracted axes (dimensions) *must not* be broadcasted. axes: Union[int, Tuple[Sequence[int], Sequence[int]]] number of axes (dimensions) to contract or explicit sequences of axis (dimension) indices for ``x1`` and ``x2``, respectively. - If ``axes`` is an ``int`` equal to ``N``, then contraction must be performed over the last ``N`` axes of ``x1`` and the first ``N`` axes of ``x2`` in order. The size of each corresponding axis (dimension) must match. Must be nonnegative. + If ``axes`` is an ``int`` equal to ``N``, then contraction *must* be performed over the last ``N`` axes of ``x1`` and the first ``N`` axes of ``x2`` in order. The size of each corresponding axis (dimension) *must* match. Must be nonnegative. - If ``N`` equals ``0``, the result is the tensor (outer) product. - If ``N`` equals ``1``, the result is the tensor dot product. - If ``N`` equals ``2``, the result is the tensor double contraction (default). - If ``axes`` is a tuple of two sequences ``(x1_axes, x2_axes)``, the first sequence must apply to ``x1`` and the second sequence to ``x2``. Both sequences must have the same length. Each axis (dimension) ``x1_axes[i]`` for ``x1`` must have the same size as the respective axis (dimension) ``x2_axes[i]`` for ``x2``. Each index referred to in a sequence must be unique. If ``x1`` has rank (i.e, number of dimensions) ``N``, a valid ``x1`` axis must reside on the half-open interval ``[-N, N)``. If ``x2`` has rank ``M``, a valid ``x2`` axis must reside on the half-open interval ``[-M, M)``. + If ``axes`` is a tuple of two sequences ``(x1_axes, x2_axes)``, the first sequence *must* apply to ``x1`` and the second sequence to ``x2``. Both sequences *must* have the same length. Each axis (dimension) ``x1_axes[i]`` for ``x1`` *must* have the same size as the respective axis (dimension) ``x2_axes[i]`` for ``x2``. Each index referred to in a sequence *must* be unique. If ``x1`` has rank (i.e, number of dimensions) ``N``, a valid ``x1`` axis *must* reside on the half-open interval ``[-N, N)``. If ``x2`` has rank ``M``, a valid ``x2`` axis *must* reside on the half-open interval ``[-M, M)``. .. note:: - If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument must be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the generalized matrix product. + If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument *must* be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations *should* be explicitly performed prior to computing the generalized matrix product. Returns ------- out: array - an array containing the tensor contraction whose shape consists of the non-contracted axes (dimensions) of the first array ``x1``, followed by the non-contracted axes (dimensions) of the second array ``x2``. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing the tensor contraction whose shape consists of the non-contracted axes (dimensions) of the first array ``x1``, followed by the non-contracted axes (dimensions) of the second array ``x2``. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- @@ -138,18 +138,18 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: x1: array first input array. Should have a floating-point data type. x2: array - second input array. Must be compatible with ``x1`` for all non-contracted axes (see :ref:`broadcasting`). The size of the axis over which to compute the dot product must be the same size as the respective axis in ``x1``. Should have a floating-point data type. + second input array. Must be compatible with ``x1`` for all non-contracted axes (see :ref:`broadcasting`). The size of the axis over which to compute the dot product *must* be the same size as the respective axis in ``x1``. Should have a floating-point data type. .. note:: - The contracted axis (dimension) must not be broadcasted. + The contracted axis (dimension) *must not* be broadcasted. axis: int - the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the dot product. Should be an integer on the interval ``[-N, -1]``, where ``N`` is ``min(x1.ndim, x2.ndim)``. 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``. + the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the dot product. Should be an integer on the interval ``[-N, -1]``, where ``N`` is ``min(x1.ndim, x2.ndim)``. 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``. Returns ------- out: array - if ``x1`` and ``x2`` are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank ``N-1``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting` along the non-contracted axes. The returned array must have a data type determined by :ref:`type-promotion`. + if ``x1`` and ``x2`` are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank ``N-1``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting` along the non-contracted axes. The returned array *must* have a data type determined by :ref:`type-promotion`. Notes ----- diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py index 131b81eb3..9405ee2f5 100644 --- a/src/array_api_stubs/_draft/manipulation_functions.py +++ b/src/array_api_stubs/_draft/manipulation_functions.py @@ -31,7 +31,7 @@ def broadcast_arrays(*arrays: array) -> List[array]: Returns ------- out: List[array] - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. + a list of broadcasted arrays. Each array *must* have the same shape. Each array *must* have the same dtype as its corresponding input array. """ @@ -44,7 +44,7 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: x: array array to broadcast. shape: Tuple[int, ...] - array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function should raise an exception. + array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function *should* raise an exception. Returns ------- @@ -62,14 +62,14 @@ def concat( Parameters ---------- arrays: Union[Tuple[array, ...], List[array]] - input arrays to join. The arrays must have the same shape, except in the dimension specified by ``axis``. + input arrays to join. The arrays *must* have the same shape, except in the dimension specified by ``axis``. axis: Optional[int] - axis along which the arrays will be joined. If ``axis`` is ``None``, arrays must be flattened before concatenation. If ``axis`` is negative, the function must determine the axis along which to join by counting from the last dimension. Default: ``0``. + axis along which the arrays will be joined. If ``axis`` is ``None``, arrays *must* be flattened before concatenation. If ``axis`` is negative, the function *must* determine the axis along which to join by counting from the last dimension. Default: ``0``. Returns ------- out: array - an output array containing the concatenated values. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + an output array containing the concatenated values. If the input arrays have different data types, normal :ref:`type-promotion` *must* apply. If the input arrays have the same data type, the output array *must* have the same data type as the input arrays. .. note:: This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. @@ -85,7 +85,7 @@ def expand_dims(x: array, /, *, axis: int = 0) -> array: x: array input array. axis: int - axis position (zero-based). If ``x`` has rank (i.e, number of dimensions) ``N``, a valid ``axis`` must reside on the closed-interval ``[-N-1, N]``. If provided a negative ``axis``, the axis position at which to insert a singleton dimension must be computed as ``N + axis + 1``. Hence, if provided ``-1``, the resolved axis position must be ``N`` (i.e., a singleton dimension must be appended to the input array ``x``). If provided ``-N-1``, the resolved axis position must be ``0`` (i.e., a singleton dimension must be prepended to the input array ``x``). + axis position (zero-based). If ``x`` has rank (i.e, number of dimensions) ``N``, a valid ``axis`` *must* reside on the closed-interval ``[-N-1, N]``. If provided a negative ``axis``, the axis position at which to insert a singleton dimension *must* be computed as ``N + axis + 1``. Hence, if provided ``-1``, the resolved axis position *must* be ``N`` (i.e., a singleton dimension *must* be appended to the input array ``x``). If provided ``-N-1``, the resolved axis position *must* be ``0`` (i.e., a singleton dimension *must* be prepended to the input array ``x``). Returns ------- @@ -95,20 +95,20 @@ def expand_dims(x: array, /, *, axis: int = 0) -> array: Raises ------ IndexError - If provided an invalid ``axis`` position, an ``IndexError`` should be raised. + If provided an invalid ``axis`` position, an ``IndexError`` *should* be raised. """ def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array: """ - Reverses the order of elements in an array along the given axis. The shape of the array must be preserved. + Reverses the order of elements in an array along the given axis. The shape of the array *must* be preserved. Parameters ---------- x: array input array. axis: Optional[Union[int, Tuple[int, ...]]] - axis (or axes) along which to flip. If ``axis`` is ``None``, the function must flip all input array axes. If ``axis`` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: ``None``. + axis (or axes) along which to flip. If ``axis`` is ``None``, the function *must* flip all input array axes. If ``axis`` is negative, the function *must* count from the last dimension. If provided more than one axis, the function *must* flip only the specified axes. Default: ``None``. Returns ------- @@ -131,14 +131,14 @@ def moveaxis( x: array input array. source: Union[int, Tuple[int, ...]] - Axes to move. Provided axes must be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis must reside on the half-open interval ``[-N, N)``. + Axes to move. Provided axes *must* be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis *must* reside on the half-open interval ``[-N, N)``. destination: Union[int, Tuple[int, ...]] - indices defining the desired positions for each respective ``source`` axis index. Provided indices must be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis must reside on the half-open interval ``[-N, N)``. + indices defining the desired positions for each respective ``source`` axis index. Provided indices *must* be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis *must* reside on the half-open interval ``[-N, N)``. Returns ------- out: array - an array containing reordered axes. The returned array must have the same data type as ``x``. + an array containing reordered axes. The returned array *must* have the same data type as ``x``. Notes ----- @@ -161,7 +161,7 @@ def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array: Returns ------- out: array - an array containing the axes permutation. The returned array must have the same data type as ``x``. + an array containing the axes permutation. The returned array *must* have the same data type as ``x``. """ @@ -178,7 +178,7 @@ def repeat( .. admonition:: Data-dependent output shape :class: important - When ``repeats`` is an array, the shape of the output array for this function depends on the data values in the ``repeats`` array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing the values in ``repeats``. Accordingly, such libraries may choose to omit support for ``repeats`` arrays; however, conforming implementations must support providing a literal ``int``. See :ref:`data-dependent-output-shapes` section for more details. + When ``repeats`` is an array, the shape of the output array for this function depends on the data values in the ``repeats`` array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing the values in ``repeats``. Accordingly, such libraries may choose to omit support for ``repeats`` arrays; however, conforming implementations *must* support providing a literal ``int``. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- @@ -189,26 +189,26 @@ def repeat( If ``axis`` is ``None``, let ``N = prod(x.shape)`` and - - if ``repeats`` is an array, ``repeats`` must be broadcast compatible with the shape ``(N,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(N,)``). - - if ``repeats`` is an integer, ``repeats`` must be broadcasted to the shape `(N,)`. + - if ``repeats`` is an array, ``repeats`` *must* be broadcast compatible with the shape ``(N,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(N,)``). + - if ``repeats`` is an integer, ``repeats`` *must* be broadcasted to the shape `(N,)`. If ``axis`` is not ``None``, let ``M = x.shape[axis]`` and - - if ``repeats`` is an array, ``repeats`` must be broadcast compatible with the shape ``(M,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(M,)``). - - if ``repeats`` is an integer, ``repeats`` must be broadcasted to the shape ``(M,)``. + - if ``repeats`` is an array, ``repeats`` *must* be broadcast compatible with the shape ``(M,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(M,)``). + - if ``repeats`` is an integer, ``repeats`` *must* be broadcasted to the shape ``(M,)``. - If ``repeats`` is an array, the array must have an integer data type. + If ``repeats`` is an array, the array *must* have an integer data type. .. note:: For specification-conforming array libraries supporting hardware acceleration, providing an array for ``repeats`` may cause device synchronization due to an unknown output shape. For those array libraries where synchronization concerns are applicable, conforming array libraries are advised to include a warning in their documentation regarding potential performance degradation when ``repeats`` is an array. axis: Optional[int] - the axis (dimension) along which to repeat elements. If ``axis`` is `None`, the function must flatten the input array ``x`` and then repeat elements of the flattened input array and return the result as a one-dimensional output array. A flattened input array must be flattened in row-major, C-style order. Default: ``None``. + the axis (dimension) along which to repeat elements. If ``axis`` is `None`, the function *must* flatten the input array ``x`` and then repeat elements of the flattened input array and return the result as a one-dimensional output array. A flattened input array *must* be flattened in row-major, C-style order. Default: ``None``. Returns ------- out: array - an output array containing repeated elements. The returned array must have the same data type as ``x``. If ``axis`` is ``None``, the returned array must be a one-dimensional array; otherwise, the returned array must have the same shape as ``x``, except for the axis (dimension) along which elements were repeated. + an output array containing repeated elements. The returned array *must* have the same data type as ``x``. If ``axis`` is ``None``, the returned array *must* be a one-dimensional array; otherwise, the returned array *must* have the same shape as ``x``, except for the axis (dimension) along which elements were repeated. Notes ----- @@ -228,7 +228,7 @@ def reshape( x: array input array to reshape. shape: Tuple[int, ...] - a new shape compatible with the original shape. One shape dimension is allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. + a new shape compatible with the original shape. One shape dimension is allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension *must* be inferred from the length of the array and the remaining dimensions. copy: Optional[bool] whether or not to copy the input array. If ``True``, the function must always copy. If ``False``, the function must never copy. If ``None``, the function must avoid copying, if possible, and may copy otherwise. Default: ``None``. @@ -241,7 +241,7 @@ def reshape( ------ ValueError If ``copy=False`` and a copy would be necessary, a ``ValueError`` - should be raised. + *should* be raised. """ @@ -260,9 +260,9 @@ def roll( x: array input array. shift: Union[int, Tuple[int, ...]] - number of places by which the elements are shifted. If ``shift`` is a tuple, then ``axis`` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in ``shift``. If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift`` must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of ``axis``. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of ``axis``. + number of places by which the elements are shifted. If ``shift`` is a tuple, then ``axis`` *must* be a tuple of the same size, and each of the given axes *must* be shifted by the corresponding element in ``shift``. If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift`` *must* be used for all specified axes. If a shift is positive, then array elements *must* be shifted positively (toward larger indices) along the dimension of ``axis``. If a shift is negative, then array elements *must* be shifted negatively (toward smaller indices) along the dimension of ``axis``. axis: Optional[Union[int, Tuple[int, ...]]] - axis (or axes) along which elements to shift. If ``axis`` is ``None``, the array must be flattened, shifted, and then restored to its original shape. Default: ``None``. + axis (or axes) along which elements to shift. If ``axis`` is ``None``, the array *must* be flattened, shifted, and then restored to its original shape. Default: ``None``. Returns ------- @@ -291,7 +291,7 @@ def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array: ------ ValueError If a specified axis has a size greater than one (i.e., it is not a - singleton dimension), a ``ValueError`` should be raised. + singleton dimension), a ``ValueError`` *should* be raised. """ @@ -302,14 +302,14 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> Parameters ---------- arrays: Union[Tuple[array, ...], List[array]] - input arrays to join. Each array must have the same shape. + input arrays to join. Each array *must* have the same shape. axis: int - axis along which the arrays will be joined. Providing an ``axis`` specifies the index of the new axis in the dimensions of the result. For example, if ``axis`` is ``0``, the new axis will be the first dimension and the output array will have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``. + axis along which the arrays will be joined. Providing an ``axis`` specifies the index of the new axis in the dimensions of the result. For example, if ``axis`` is ``0``, the new axis will be the first dimension and the output array will have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid ``axis`` *must* be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function *must* raise an exception. Default: ``0``. Returns ------- out: array - an output array having rank ``N+1``, where ``N`` is the rank (number of dimensions) of ``x``. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + an output array having rank ``N+1``, where ``N`` is the rank (number of dimensions) of ``x``. If the input arrays have different data types, normal :ref:`type-promotion` *must* apply. If the input arrays have the same data type, the output array *must* have the same data type as the input arrays. .. note:: This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. @@ -329,14 +329,14 @@ def tile(x: array, repetitions: Tuple[int, ...], /) -> array: Let ``N = len(x.shape)`` and ``M = len(repetitions)``. - If ``N > M``, the function must prepend ones until all axes (dimensions) are specified (e.g., if ``x`` has shape ``(8,6,4,2)`` and ``repetitions`` is the tuple ``(3,3)``, then ``repetitions`` must be treated as ``(1,1,3,3)``). + If ``N > M``, the function *must* prepend ones until all axes (dimensions) are specified (e.g., if ``x`` has shape ``(8,6,4,2)`` and ``repetitions`` is the tuple ``(3,3)``, then ``repetitions`` *must* be treated as ``(1,1,3,3)``). - If ``N < M``, the function must prepend singleton axes (dimensions) to ``x`` until ``x`` has as many axes (dimensions) as ``repetitions`` specifies (e.g., if ``x`` has shape ``(4,2)`` and ``repetitions`` is the tuple ``(3,3,3,3)``, then ``x`` must be treated as if it has shape ``(1,1,4,2)``). + If ``N < M``, the function *must* prepend singleton axes (dimensions) to ``x`` until ``x`` has as many axes (dimensions) as ``repetitions`` specifies (e.g., if ``x`` has shape ``(4,2)`` and ``repetitions`` is the tuple ``(3,3,3,3)``, then ``x`` *must* be treated as if it has shape ``(1,1,4,2)``). Returns ------- out: array - a tiled output array. The returned array must have the same data type as ``x`` and must have a rank (i.e., number of dimensions) equal to ``max(N, M)``. If ``S`` is the shape of the tiled array after prepending singleton dimensions (if necessary) and ``r`` is the tuple of repetitions after prepending ones (if necessary), then the number of elements along each axis (dimension) must satisfy ``S[i]*r[i]``, where ``i`` refers to the ``i`` th axis (dimension). + a tiled output array. The returned array *must* have the same data type as ``x`` and *must* have a rank (i.e., number of dimensions) equal to ``max(N, M)``. If ``S`` is the shape of the tiled array after prepending singleton dimensions (if necessary) and ``r`` is the tuple of repetitions after prepending ones (if necessary), then the number of elements along each axis (dimension) *must* satisfy ``S[i]*r[i]``, where ``i`` refers to the ``i`` th axis (dimension). Notes ----- @@ -354,7 +354,7 @@ def unstack(x: array, /, *, axis: int = 0) -> Tuple[array, ...]: x: array input array. axis: int - axis along which the array will be split. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``. + axis along which the array will be split. A valid ``axis`` *must* be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function *must* raise an exception. Default: ``0``. Returns ------- diff --git a/src/array_api_stubs/_draft/searching_functions.py b/src/array_api_stubs/_draft/searching_functions.py index 9e0053825..93a409440 100644 --- a/src/array_api_stubs/_draft/searching_functions.py +++ b/src/array_api_stubs/_draft/searching_functions.py @@ -18,14 +18,14 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - x: array 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``. + 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 - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. The returned array must have be the default array index data type. + if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. The returned array *must* have be the default array index data type. """ @@ -43,14 +43,14 @@ def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - x: array 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``. + 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 - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. The returned array must have the default array index data type. + if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. The returned array *must* have the default array index data type. """ @@ -98,12 +98,12 @@ def nonzero(x: array, /) -> Tuple[array, ...]: Parameters ---------- x: array - input array. Must have a positive rank. If ``x`` is zero-dimensional, the function must raise an exception. + input array. Must have a positive rank. If ``x`` is zero-dimensional, the function *must* raise an exception. Returns ------- out: Tuple[array, ...] - a tuple of ``k`` arrays, one for each dimension of ``x`` and each of size ``n`` (where ``n`` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. The returned array must have the default array index data type. + a tuple of ``k`` arrays, one for each dimension of ``x`` and each of size ``n`` (where ``n`` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices *must* be returned in row-major, C-style order. The returned array *must* have the default array index data type. Notes ----- @@ -130,7 +130,7 @@ def searchsorted( Parameters ---------- x1: array - input array. Must be a one-dimensional array. Should have a real-valued data type. If ``sorter`` is ``None``, must be sorted in ascending order; otherwise, ``sorter`` must be an array of indices that sort ``x1`` in ascending order. + input array. Must be a one-dimensional array. Should have a real-valued data type. If ``sorter`` is ``None``, *must* be sorted in ascending order; otherwise, ``sorter`` *must* be an array of indices that sort ``x1`` in ascending order. x2: array array containing search values. Should have a real-valued data type. side: Literal['left', 'right'] @@ -140,29 +140,29 @@ def searchsorted( If ``side == 'left'``, then - - each returned index ``i`` must satisfy the index condition ``x1[i-1] < v <= x1[i]``. - - if no index satisfies the index condition, then the returned index for that element must be ``0``. + - each returned index ``i`` *must* satisfy the index condition ``x1[i-1] < v <= x1[i]``. + - if no index satisfies the index condition, then the returned index for that element *must* be ``0``. Otherwise, if ``side == 'right'``, then - - each returned index ``i`` must satisfy the index condition ``x1[i-1] <= v < x1[i]``. - - if no index satisfies the index condition, then the returned index for that element must be ``N``, where ``N`` is the number of elements in ``x1``. + - each returned index ``i`` *must* satisfy the index condition ``x1[i-1] <= v < x1[i]``. + - if no index satisfies the index condition, then the returned index for that element *must* be ``N``, where ``N`` is the number of elements in ``x1``. Default: ``'left'``. sorter: Optional[array] - array of indices that sort ``x1`` in ascending order. The array must have the same shape as ``x1`` and have an integer data type. Default: ``None``. + array of indices that sort ``x1`` in ascending order. The array *must* have the same shape as ``x1`` and have an integer data type. Default: ``None``. Returns ------- out: array - an array of indices with the same shape as ``x2``. The returned array must have the default array index data type. + an array of indices with the same shape as ``x2``. The returned array *must* have the default array index data type. Notes ----- For real-valued floating-point arrays, the sort order of NaNs and signed zeros is unspecified and thus implementation-dependent. Accordingly, when a real-valued floating-point array contains NaNs and signed zeros, what constitutes ascending order may vary among specification-conforming array libraries. - While behavior for arrays containing NaNs and signed zeros is implementation-dependent, specification-conforming libraries should, however, ensure consistency with ``sort`` and ``argsort`` (i.e., if a value in ``x2`` is inserted into ``x1`` according to the corresponding index in the output array and ``sort`` is invoked on the resultant array, the sorted result should be an array in the same order). + While behavior for arrays containing NaNs and signed zeros is implementation-dependent, specification-conforming libraries *should*, however, ensure consistency with ``sort`` and ``argsort`` (i.e., if a value in ``x2`` is inserted into ``x1`` according to the corresponding index in the output array and ``sort`` is invoked on the resultant array, the sorted result *should* be an array in the same order). .. versionadded:: 2023.12 """ @@ -184,5 +184,5 @@ def where(condition: array, x1: array, x2: array, /) -> array: Returns ------- out: array - an array with elements from ``x1`` where ``condition`` is ``True``, and elements from ``x2`` elsewhere. The returned array must have a data type determined by :ref:`type-promotion` rules with the arrays ``x1`` and ``x2``. + an array with elements from ``x1`` where ``condition`` is ``True``, and elements from ``x2`` elsewhere. The returned array *must* have a data type determined by :ref:`type-promotion` rules with the arrays ``x1`` and ``x2``. """ diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 5b7e9a56c..008327138 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -14,30 +14,30 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + Uniqueness *should* be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``nan`` values compare as ``False``, ``nan`` values *should* be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components *should* be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros *should not* be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. - Each ``nan`` value and each complex floating-point value having a ``nan`` component should have a count of one, while the counts for signed zeros should be aggregated as a single count. + Each ``nan`` value and each complex floating-point value having a ``nan`` component *should* have a count of one, while the counts for signed zeros *should* be aggregated as a single count. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function *must* flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array, array, array] a namedtuple ``(values, indices, inverse_indices, counts)`` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name ``indices`` and must be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array must have the same shape as ``values`` and must have the default array index data type. - - third element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct ``x``. The array must have the same shape as ``x`` and must have the default array index data type. - - fourth element must have the field name ``counts`` and must be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. + - first element *must* have the field name ``values`` and *must* be a one-dimensional array containing the unique elements of ``x``. The array *must* have the same data type as ``x``. + - second element *must* have the field name ``indices`` and *must* be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array *must* have the same shape as ``values`` and *must* have the default array index data type. + - third element *must* have the field name ``inverse_indices`` and *must* be an array containing the indices of ``values`` that reconstruct ``x``. The array *must* have the same shape as ``x`` and *must* have the default array index data type. + - fourth element *must* have the field name ``counts`` and *must* be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts *must* match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array *must* have same shape as ``values`` and *must* have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -63,26 +63,26 @@ def unique_counts(x: array, /) -> Tuple[array, array]: The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + Uniqueness *should* be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``nan`` values compare as ``False``, ``nan`` values *should* be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components *should* be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros *should not* be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). - Each ``nan`` value and each complex floating-point value having a ``nan`` component should have a count of one, while the counts for signed zeros should be aggregated as a single count. + Each ``nan`` value and each complex floating-point value having a ``nan`` component *should* have a count of one, while the counts for signed zeros *should* be aggregated as a single count. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function *must* flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array] a namedtuple `(values, counts)` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name `counts` and must be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. + - first element *must* have the field name ``values`` and *must* be a one-dimensional array containing the unique elements of ``x``. The array *must* have the same data type as ``x``. + - second element *must* have the field name `counts` and *must* be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts *must* match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array *must* have same shape as ``values`` and *must* have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -108,26 +108,26 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + Uniqueness *should* be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``nan`` values compare as ``False``, ``nan`` values *should* be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components *should* be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros *should not* be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function *must* flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array] a namedtuple ``(values, inverse_indices)`` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct ``x``. The array must have the same shape as ``x`` and have the default array index data type. + - first element *must* have the field name ``values`` and *must* be a one-dimensional array containing the unique elements of ``x``. The array *must* have the same data type as ``x``. + - second element *must* have the field name ``inverse_indices`` and *must* be an array containing the indices of ``values`` that reconstruct ``x``. The array *must* have the same shape as ``x`` and have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -153,21 +153,21 @@ def unique_values(x: array, /) -> array: The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + Uniqueness *should* be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``nan`` values compare as ``False``, ``nan`` values *should* be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components *should* be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros *should not* be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function *must* flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: array - a one-dimensional array containing the set of unique elements in ``x``. The returned array must have the same data type as ``x``. + a one-dimensional array containing the set of unique elements in ``x``. The returned array *must* have the same data type as ``x``. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -179,5 +179,5 @@ def unique_values(x: array, /) -> array: Added complex data type support. .. versionchanged:: 2023.12 - Required that the output array must be one-dimensional. + Required that the output array *must* be one-dimensional. """ diff --git a/src/array_api_stubs/_draft/sorting_functions.py b/src/array_api_stubs/_draft/sorting_functions.py index 2dc4ac410..5572d9c51 100644 --- a/src/array_api_stubs/_draft/sorting_functions.py +++ b/src/array_api_stubs/_draft/sorting_functions.py @@ -18,7 +18,7 @@ def argsort( x : array input array. Should have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. + axis along which to sort. If set to ``-1``, the function *must* sort along the last axis. Default: ``-1``. descending: bool sort order. If ``True``, the returned indices sort ``x`` in descending order (by value). If ``False``, the returned indices sort ``x`` in ascending order (by value). Default: ``False``. stable: bool @@ -27,7 +27,7 @@ def argsort( Returns ------- out : array - an array of indices. The returned array must have the same shape as ``x``. The returned array must have the default array index data type. + an array of indices. The returned array *must* have the same shape as ``x``. The returned array *must* have the default array index data type. """ @@ -45,14 +45,14 @@ def sort( x: array input array. Should have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. + axis along which to sort. If set to ``-1``, the function *must* sort along the last axis. Default: ``-1``. descending: bool - sort order. If ``True``, the array must be sorted in descending order (by value). If ``False``, the array must be sorted in ascending order (by value). Default: ``False``. + sort order. If ``True``, the array *must* be sorted in descending order (by value). If ``False``, the array *must* be sorted in ascending order (by value). Default: ``False``. stable: bool sort stability. If ``True``, the returned array must maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned array may or may not maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``. Returns ------- out : array - a sorted array. The returned array must have the same data type and shape as ``x``. + a sorted array. The returned array *must* have the same data type and shape as ``x``. """ diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 92ffe60c5..f3bd49e83 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -82,30 +82,30 @@ def cumulative_sum( x: array input array. Should have one or more dimensions (axes). Should have a numeric data type. axis: Optional[int] - axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension. + axis along which a cumulative sum *must* be computed. If ``axis`` is negative, the function *must* determine the axis along which to compute a cumulative sum by counting from the last dimension. If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array *must* have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - - 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). + - 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). - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array *should* be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. include_initial: bool - boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``. + boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value *must* be the additive identity (i.e., zero). Default: ``False``. Returns ------- out: array - an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above. + an array containing the cumulative sums. The returned array *must* have a data type as described by the ``dtype`` parameter above. - Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: + Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array *must* have a shape determined according to the following rules: - - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. + - if ``include_initial`` is ``True``, the returned array *must* have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum *must* be ``N+1``. + - if ``include_initial`` is ``False``, the returned array *must* have the same shape as ``x``. Notes ----- @@ -114,7 +114,7 @@ def cumulative_sum( **Special Cases** - For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + For both real-valued and complex floating-point operands, special cases *must* be handled as if the operation is implemented by successive application of :func:`~array_api.add`. .. versionadded:: 2023.12 """ @@ -135,14 +135,14 @@ def max( x: array 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``. + 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 - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if the maximum value was computed over the entire array, a zero-dimensional array containing the maximum value; otherwise, a non-zero-dimensional array containing the maximum values. The returned array must have the same data type as ``x``. + if the maximum value was computed over the entire array, a zero-dimensional array containing the maximum value; otherwise, a non-zero-dimensional array containing the maximum values. The returned array *must* have the same data type as ``x``. Notes ----- @@ -179,17 +179,17 @@ def mean( x: array input array. Should have a 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``. + 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 - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - 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``. + 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 real-valued floating-point data type. + 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 real-valued floating-point data type. Notes ----- @@ -227,14 +227,14 @@ def min( x: array 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``. + 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 - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if the minimum value was computed over the entire array, a zero-dimensional array containing the minimum value; otherwise, a non-zero-dimensional array containing the minimum values. The returned array must have the same data type as ``x``. + if the minimum value was computed over the entire array, a zero-dimensional array containing the minimum value; otherwise, a non-zero-dimensional array containing the minimum values. The returned array *must* have the same data type as ``x``. Notes ----- @@ -272,23 +272,23 @@ def prod( x: array input array. Should have a numeric 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``. + 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] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array *must* have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - - 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). + - 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). - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array *should* be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. keepdims: bool - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. The returned array must have a data type as described by the ``dtype`` parameter above. + if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. The returned array *must* have a data type as described by the ``dtype`` parameter above. Notes ----- @@ -299,7 +299,7 @@ def prod( - If ``N`` is ``0``, the product is `1` (i.e., the empty product). - For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.multiply`. + For both real-valued and complex floating-point operands, special cases *must* be handled as if the operation is implemented by successive application of :func:`~array_api.multiply`. .. versionchanged:: 2022.12 Added complex data type support. @@ -325,19 +325,19 @@ def std( x: array 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``. + 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] degrees of freedom adjustment. Setting this parameter to a value other than ``0`` has the effect of adjusting the divisor during the calculation of the standard deviation according to ``N-c`` where ``N`` corresponds to the total number of elements over which the standard deviation is computed and ``c`` corresponds to the provided degrees of freedom adjustment. When computing the standard deviation of a population, setting this parameter to ``0`` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample standard deviation, setting this parameter to ``1`` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction). Default: ``0``. keepdims: bool - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - 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``. + 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 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. + 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. Notes ----- @@ -367,23 +367,23 @@ def sum( x: array input array. Should have a numeric 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``. + 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] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array *must* have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - - 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). + - 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). - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array *should* be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. keepdims: bool - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. The returned array must have a data type as described by the ``dtype`` parameter above. + if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. The returned array *must* have a data type as described by the ``dtype`` parameter above. Notes ----- @@ -394,7 +394,7 @@ def sum( - If ``N`` is ``0``, the sum is ``0`` (i.e., the empty sum). - For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + For both real-valued and complex floating-point operands, special cases *must* be handled as if the operation is implemented by successive application of :func:`~array_api.add`. .. versionchanged:: 2022.12 Added complex data type support. @@ -420,20 +420,20 @@ def var( x: array 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``. + 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] degrees of freedom adjustment. Setting this parameter to a value other than ``0`` has the effect of adjusting the divisor during the calculation of the variance according to ``N-c`` where ``N`` corresponds to the total number of elements over which the variance is computed and ``c`` corresponds to the provided degrees of freedom adjustment. When computing the variance of a population, setting this parameter to ``0`` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the unbiased sample variance, setting this parameter to ``1`` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction). Default: ``0``. keepdims: bool - if ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if the variance was computed over the entire array, a zero-dimensional array containing the variance; otherwise, a non-zero-dimensional array containing the variances. The returned array must have the same data type as ``x``. + if the variance was computed over the entire array, a zero-dimensional array containing the variance; otherwise, a non-zero-dimensional array containing the variances. 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 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. + 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. Notes ----- diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py index cdbe4a0f8..28858fcf3 100644 --- a/src/array_api_stubs/_draft/utility_functions.py +++ b/src/array_api_stubs/_draft/utility_functions.py @@ -15,27 +15,27 @@ def all( Tests whether all input array elements evaluate to ``True`` along a specified axis. .. note:: - Positive infinity, negative infinity, and NaN must evaluate to ``True``. + Positive infinity, negative infinity, and NaN *must* evaluate to ``True``. .. note:: - If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) must evaluate to ``True``. + If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) *must* evaluate to ``True``. .. note:: - If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result must be ``True``. + If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result *must* be ``True``. Parameters ---------- x: array input array. axis: Optional[Union[int, Tuple[int, ...]]] - axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``None``. + axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction *must* be performed over the entire array. If a tuple of integers, logical AND reductions *must* be performed over multiple axes. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function *must* raise an exception. Default: ``None``. keepdims: bool - If ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + If ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if a logical AND reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of ``bool``. + if a logical AND reduction was performed over the entire array, the returned array *must* be a zero-dimensional array containing the test result; otherwise, the returned array *must* be a non-zero-dimensional array containing the test results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -56,27 +56,27 @@ def any( Tests whether any input array element evaluates to ``True`` along a specified axis. .. note:: - Positive infinity, negative infinity, and NaN must evaluate to ``True``. + Positive infinity, negative infinity, and NaN *must* evaluate to ``True``. .. note:: - If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) must evaluate to ``True``. + If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) *must* evaluate to ``True``. .. note:: - If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result must be ``False``. + If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result *must* be ``False``. Parameters ---------- x: array input array. axis: Optional[Union[int, Tuple[int, ...]]] - axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``None``. + axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction *must* be performed over the entire array. If a tuple of integers, logical OR reductions *must* be performed over multiple axes. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function *must* raise an exception. Default: ``None``. keepdims: bool - If ``True``, the reduced 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 reduced axes (dimensions) must not be included in the result. Default: ``False``. + If ``True``, the reduced 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 reduced axes (dimensions) *must not* be included in the result. Default: ``False``. Returns ------- out: array - if a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of ``bool``. + if a logical OR reduction was performed over the entire array, the returned array *must* be a zero-dimensional array containing the test result; otherwise, the returned array *must* be a non-zero-dimensional array containing the test results. The returned array *must* have a data type of ``bool``. Notes ----- @@ -103,7 +103,7 @@ def diff( x: array input array. Should have a numeric data type. axis: int - axis along which to compute differences. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute differences by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``-1``. + axis along which to compute differences. A valid ``axis`` *must* be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function *must* determine the axis along which to compute differences by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function *must* raise an exception. Default: ``-1``. n: int number of times to recursively compute differences. Default: ``1``. prepend: Optional[array] @@ -114,15 +114,15 @@ def diff( Returns ------- out: array - an array containing the n-th differences. Should have the same data type as ``x``. Must have the same shape as ``x``, except for the axis specified by ``axis`` which must have a size determined as follows: + an array containing the n-th differences. Should have the same data type as ``x``. Must have the same shape as ``x``, except for the axis specified by ``axis`` which *must* have a size determined as follows: - Let ``M`` be the number of elements along an axis specified by ``axis``. - Let ``N1`` be the number of prepended values along an axis specified by ``axis``. - Let ``N2`` be the number of appended values along an axis specified by ``axis``. - - The final size of the axis specified by ``axis`` must be ``M + N1 + N2 - n``. + - The final size of the axis specified by ``axis`` *must* be ``M + N1 + N2 - n``. Notes ----- - - The first-order differences are given by ``out[i] = x[i+1] - x[i]`` along a specified axis. Higher-order differences must be calculated recursively (e.g., by calling ``diff(out, axis=axis, n=n-1)``). + - The first-order differences are given by ``out[i] = x[i+1] - x[i]`` along a specified axis. Higher-order differences *must* be calculated recursively (e.g., by calling ``diff(out, axis=axis, n=n-1)``). """ From 2174846a7dc27b574a8759ab3a6a5c87218b49f9 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 10 Dec 2024 18:11:18 +0200 Subject: [PATCH 3/4] repair the table --- spec/draft/API_specification/data_types.rst | 54 ++++++++++----------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index f86a70bd8..416676f51 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -9,35 +9,35 @@ A conforming implementation of the array API standard *must* provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dtype object | description | -+==============+============================================================================================================================================================================================+ -| bool | Boolean (``True`` or ``False``). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| dtype object | description | ++==============+==============================================================================================================================================================================================+ +| bool | Boolean (``True`` or ``False``). | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | complex64 | 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). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | complex128 | 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). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Data type objects *must* have the following methods (no attributes are required): From 699a1d658d79ff9fe66539a6e6733cc1440a49c8 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Thu, 12 Dec 2024 09:00:56 +0200 Subject: [PATCH 4/4] revert changes to spec/* --- spec/draft/API_specification/array_object.rst | 38 ++++----- spec/draft/API_specification/broadcasting.rst | 4 +- spec/draft/API_specification/constants.rst | 4 +- .../API_specification/creation_functions.rst | 2 +- .../API_specification/data_type_functions.rst | 2 +- spec/draft/API_specification/data_types.rst | 78 +++++++++---------- .../function_and_method_signatures.rst | 4 +- spec/draft/API_specification/index.rst | 16 ++-- spec/draft/API_specification/indexing.rst | 64 +++++++-------- .../API_specification/indexing_functions.rst | 2 +- spec/draft/API_specification/inspection.rst | 4 +- .../linear_algebra_functions.rst | 2 +- .../manipulation_functions.rst | 2 +- .../API_specification/searching_functions.rst | 2 +- .../draft/API_specification/set_functions.rst | 2 +- .../API_specification/sorting_functions.rst | 4 +- .../statistical_functions.rst | 2 +- .../API_specification/type_promotion.rst | 6 +- .../API_specification/utility_functions.rst | 2 +- spec/draft/API_specification/version.rst | 2 +- spec/draft/design_topics/C_API.rst | 2 +- spec/draft/design_topics/accuracy.rst | 4 +- spec/draft/design_topics/complex_numbers.rst | 6 +- .../copies_views_and_mutation.rst | 4 +- spec/draft/design_topics/data_interchange.rst | 12 +-- spec/draft/design_topics/device_support.rst | 2 +- spec/draft/design_topics/exceptions.rst | 6 +- spec/draft/design_topics/static_typing.rst | 4 +- .../fourier_transform_functions.rst | 6 +- spec/draft/extensions/index.rst | 8 +- .../extensions/linear_algebra_functions.rst | 20 ++--- 31 files changed, 158 insertions(+), 158 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index 7490f1a08..f8a586ade 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -5,12 +5,12 @@ Array object Array API specification for array object attributes and methods. -A conforming implementation of the array API standard *must* provide and support an array object having the following attributes and methods. +A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods. -Furthermore, a conforming implementation of the array API standard *must* support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and *must* explicitly document their maximum supported rank ``N``. +Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and must explicitly document their maximum supported rank ``N``. .. note:: - Conforming implementations *must* support zero-dimensional arrays. + Conforming implementations must support zero-dimensional arrays. Apart from array object attributes, such as ``ndim``, ``device``, and ``dtype``, all operations in this standard return arrays (or tuples of arrays), including those operations, such as ``mean``, ``var``, and ``std``, from which some common array libraries (e.g., NumPy) return scalar values. @@ -23,12 +23,12 @@ Furthermore, a conforming implementation of the array API standard *must* suppor Operators --------- -A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators. Arithmetic Operators ~~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python arithmetic operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following Python arithmetic operators. - ``+x``: :meth:`.array.__pos__` @@ -75,24 +75,24 @@ A conforming implementation of the array API standard *must* provide and support - `operator.pow(x1, x2) `_ - `operator.__pow__(x1, x2) `_ -Arithmetic operators *should* be defined for arrays having real-valued data types. +Arithmetic operators should be defined for arrays having real-valued data types. Array Operators ~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python array operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following Python array operators. - `x1 @ x2`: :meth:`.array.__matmul__` - `operator.matmul(x1, x2) `_ - `operator.__matmul__(x1, x2) `_ -The matmul ``@`` operator *should* be defined for arrays having real-valued data types. +The matmul ``@`` operator should be defined for arrays having real-valued data types. Bitwise Operators ~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python bitwise operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following Python bitwise operators. - `~x`: :meth:`.array.__invert__` @@ -126,12 +126,12 @@ A conforming implementation of the array API standard *must* provide and support - `operator.rshift(x1, x2) `_ - `operator.__rshift__(x1, x2) `_ -Bitwise operators *should* be defined for arrays having integer and boolean data types. +Bitwise operators should be defined for arrays having integer and boolean data types. Comparison Operators ~~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python comparison operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following Python comparison operators. - `x1 < x2`: :meth:`.array.__lt__` @@ -163,20 +163,20 @@ A conforming implementation of the array API standard *must* provide and support - `operator.ne(x1, x2) `_ - `operator.__ne__(x1, x2) `_ -:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators *should* be defined for arrays having any data type. +:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type. For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). In-place Operators ~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following in-place Python operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following in-place Python operators. -An in-place operation *must not* change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. +An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. -An in-place operation *must* have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` *must* always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. +An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. .. note:: - In-place operators *must* be supported as discussed in :ref:`copyview-mutability`. + In-place operators must be supported as discussed in :ref:`copyview-mutability`. Arithmetic Operators """""""""""""""""""" @@ -206,12 +206,12 @@ Bitwise Operators Reflected Operators ~~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard *must* provide and support an array object supporting the following reflected operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following reflected operators. -The results of applying reflected operators *must* match their non-reflected equivalents. +The results of applying reflected operators must match their non-reflected equivalents. .. note:: - All operators for which ``array scalar`` is implemented *must* have an equivalent reflected operator implementation. + All operators for which ``array scalar`` is implemented must have an equivalent reflected operator implementation. Arithmetic Operators """""""""""""""""""" diff --git a/spec/draft/API_specification/broadcasting.rst b/spec/draft/API_specification/broadcasting.rst index 9522f74ac..abb3ed222 100644 --- a/spec/draft/API_specification/broadcasting.rst +++ b/spec/draft/API_specification/broadcasting.rst @@ -19,7 +19,7 @@ Given an element-wise operation involving two compatible arrays, an array having If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank. -The results of the element-wise operation *must* be stored in an array having a shape determined by the following algorithm. +The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm. #. Let ``A`` and ``B`` both be arrays. @@ -112,7 +112,7 @@ The following examples demonstrate array shapes which do **not** broadcast. In-place Semantics ------------------ -As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) *must not* change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed. +As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) must not change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed. For example: diff --git a/spec/draft/API_specification/constants.rst b/spec/draft/API_specification/constants.rst index 822ffa1c4..71cb8688d 100644 --- a/spec/draft/API_specification/constants.rst +++ b/spec/draft/API_specification/constants.rst @@ -3,9 +3,9 @@ Constants Array API specification for constants. -A conforming implementation of the array API standard *must* provide and support the following constants adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the following constants adhering to the following conventions. -- Each constant *must* have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value. +- Each constant must have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value. Objects in API -------------- diff --git a/spec/draft/API_specification/creation_functions.rst b/spec/draft/API_specification/creation_functions.rst index 6a9728f45..ff5c06368 100644 --- a/spec/draft/API_specification/creation_functions.rst +++ b/spec/draft/API_specification/creation_functions.rst @@ -3,7 +3,7 @@ Creation Functions Array API specification for creating arrays. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/data_type_functions.rst b/spec/draft/API_specification/data_type_functions.rst index 1a35292dd..d42968c7b 100644 --- a/spec/draft/API_specification/data_type_functions.rst +++ b/spec/draft/API_specification/data_type_functions.rst @@ -3,7 +3,7 @@ Data Type Functions Array API specification for data type functions. -A conforming implementation of the array API standard *must* provide and support the following data type functions. +A conforming implementation of the array API standard must provide and support the following data type functions. Objects in API diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index 416676f51..5987dd322 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -5,41 +5,41 @@ Data Types Array API specification for supported data types. -A conforming implementation of the array API standard *must* provide and support +A conforming implementation of the array API standard must provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dtype object | description | -+==============+==============================================================================================================================================================================================+ -| bool | Boolean (``True`` or ``False``). | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex64 | 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). | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex128 | 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). | -+--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Data type objects *must* have the following methods (no attributes are required): ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| dtype object | description | ++==============+============================================================================================================================================================================================+ +| bool | Boolean (``True`` or ``False``). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| complex64 | 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). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| complex128 | 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). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Data type objects must have the following methods (no attributes are required): .. NOTE: please keep the functions in alphabetical order @@ -89,28 +89,28 @@ See :ref:`type-promotion` for specification guidance describing the rules govern Default Data Types ------------------ -A conforming implementation of the array API standard *must* define the following default data types. +A conforming implementation of the array API standard must define the following default data types. - 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 real-valued 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 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 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. +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. -The default array index data type may be ``int32`` on 32-bit platforms, but the default *should* be ``int64`` otherwise. +The default array index data type may be ``int32`` on 32-bit platforms, but the default should be ``int64`` otherwise. Note that it is possible that a library supports multiple devices, with not all those device types supporting the same data types. In this case, the default integer or floating-point data types may vary with device. If that is the case, -the library *should* clearly warn about this in its documentation. +the library should clearly warn about this in its documentation. .. note:: - The default data types *should* be clearly defined in a conforming library's documentation. + The default data types should be clearly defined in a conforming library's documentation. .. _data-type-categories: diff --git a/spec/draft/API_specification/function_and_method_signatures.rst b/spec/draft/API_specification/function_and_method_signatures.rst index ac4fc9acc..0eca2ac69 100644 --- a/spec/draft/API_specification/function_and_method_signatures.rst +++ b/spec/draft/API_specification/function_and_method_signatures.rst @@ -5,7 +5,7 @@ Function and method signatures Function signatures in this standard adhere to the following: -1. Positional parameters *should* be `positional-only `_ parameters. +1. Positional parameters should be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. @@ -20,7 +20,7 @@ Function signatures in this standard adhere to the following: namespace >= 3.8. Alternatively, they can add guidance to their users in the documentation to use the functions as if they were positional-only. -2. Optional parameters *should* be `keyword-only `_ arguments. +2. Optional parameters should be `keyword-only `_ arguments. *Rationale: this leads to more readable code, and it makes it easier to evolve an API over time by adding keywords without having to worry about diff --git a/spec/draft/API_specification/index.rst b/spec/draft/API_specification/index.rst index 26e60e470..ffc3d3775 100644 --- a/spec/draft/API_specification/index.rst +++ b/spec/draft/API_specification/index.rst @@ -3,16 +3,16 @@ API specification ================= -A conforming implementation of the array API standard *must* provide and support the APIs and behavior detailed in this specification while adhering to the following conventions. +A conforming implementation of the array API standard must provide and support the APIs and behavior detailed in this specification while adhering to the following conventions. -- When a function signature includes a `/`, positional parameters *must* be `positional-only `_ parameters. See :ref:`function-and-method-signatures`. -- When a function signature includes a `*`, optional parameters *must* be `keyword-only `_ arguments. See :ref:`function-and-method-signatures`. -- Broadcasting semantics *must* follow the semantics defined in :ref:`broadcasting`. -- Unless stated otherwise, functions *must* support the data types defined in :ref:`data-types`. +- When a function signature includes a `/`, positional parameters must be `positional-only `_ parameters. See :ref:`function-and-method-signatures`. +- When a function signature includes a `*`, optional parameters must be `keyword-only `_ arguments. See :ref:`function-and-method-signatures`. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. - Functions may only be required for a subset of input data types. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`. -- Unless stated otherwise, functions *must* adhere to the type promotion rules defined in :ref:`type-promotion`. -- Unless stated otherwise, floating-point operations *must* adhere to IEEE 754-2019. -- Unless stated otherwise, element-wise mathematical functions *must* satisfy the minimum accuracy requirements defined in :ref:`accuracy`. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. +- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +- Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`. .. toctree:: diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 6a60382d4..eb61c26d5 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -5,35 +5,35 @@ Indexing Array API specification for indexing arrays. -A conforming implementation of the array API standard *must* adhere to the following conventions. +A conforming implementation of the array API standard must adhere to the following conventions. Single-axis Indexing -------------------- -To index a single array axis, an array *must* support standard Python indexing rules. Let ``n`` be the axis (dimension) size. +To index a single array axis, an array must support standard Python indexing rules. Let ``n`` be the axis (dimension) size. -- An integer index *must* be an object satisfying `operator.index `_ (e.g., ``int``). +- An integer index must be an object satisfying `operator.index `_ (e.g., ``int``). -- Nonnegative indices *must* start at ``0`` (i.e., zero-based indexing). +- Nonnegative indices must start at ``0`` (i.e., zero-based indexing). -- **Valid** nonnegative indices *must* reside on the half-open interval ``[0, n)``. +- **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. -- Negative indices *must* count backward from the last array index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last array index). +- Negative indices must count backward from the last array index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last array index). .. note:: A negative index ``j`` is equivalent to ``n-j``; the former is syntactic sugar for the latter, providing a shorthand for indexing elements that would otherwise need to be specified in terms of the axis (dimension) size. -- **Valid** negative indices *must* reside on the closed interval ``[-n, -1]``. +- **Valid** negative indices must reside on the closed interval ``[-n, -1]``. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``. -- Colons ``:`` *must* be used for `slices `_: ``start:stop:step``, where ``start`` is inclusive and ``stop`` is exclusive. +- Colons ``:`` must be used for `slices `_: ``start:stop:step``, where ``start`` is inclusive and ``stop`` is exclusive. .. note:: The specification does not support returning scalar (i.e., non-array) values from operations, including indexing. In contrast to standard Python indexing rules, for any index, or combination of indices, which select a single value, the result must be a zero-dimensional array containing the selected value. @@ -62,7 +62,7 @@ The basic slice syntax is ``i:j:k`` where ``i`` is the starting index, ``j`` is .. note:: Slice syntax can be equivalently achieved using the Python built-in `slice() `_ API. From the perspective of ``A``, the behavior of ``A[i:j:k]`` and ``A[slice(i, j, k)]`` is indistinguishable (i.e., both retrieve the same set of items from ``__getitem__``). -Using a slice to index a single array axis *must* select ``m`` elements with index values +Using a slice to index a single array axis must select ``m`` elements with index values :: @@ -90,9 +90,9 @@ such that For ``i`` on the interval ``[0, n)`` (where ``n`` is the axis size), ``j`` on the interval ``(0, n]``, ``i`` less than ``j``, and positive step ``k``, a starting index ``i`` is **always** included, while the stopping index ``j`` is **always** excluded. This preserves ``x[:i]+x[i:]`` always being equal to ``x``. .. note:: - Using a slice to index into a single array axis *should* select the same elements as using a slice to index a Python list of the same size. + Using a slice to index into a single array axis should select the same elements as using a slice to index a Python list of the same size. -Slice syntax *must* have the following defaults. Let ``n`` be the axis (dimension) size. +Slice syntax must have the following defaults. Let ``n`` be the axis (dimension) size. - If ``k`` is not provided (e.g., ``0:10``), ``k`` must equal ``1``. - If ``k`` is greater than ``0`` and ``i`` is not provided (e.g., ``:10:2``), ``i`` must equal ``0``. @@ -100,16 +100,16 @@ Slice syntax *must* have the following defaults. Let ``n`` be the axis (dimensio - If ``k`` is less than ``0`` and ``i`` is not provided (e.g., ``:10:-2``), ``i`` must equal ``n-1``. - If ``k`` is less than ``0`` and ``j`` is not provided (e.g., ``0::-2``), ``j`` must equal ``-n-1``. -Using a slice to index a single array axis *must* adhere to the following rules. Let ``n`` be the axis (dimension) size. +Using a slice to index a single array axis must adhere to the following rules. Let ``n`` be the axis (dimension) size. -- If ``i`` equals ``j``, a slice *must* return an empty array, whose axis (dimension) size along the indexed axis is ``0``. +- If ``i`` equals ``j``, a slice must return an empty array, whose axis (dimension) size along the indexed axis is ``0``. -- Indexing via ``:`` and ``::`` *must* be equivalent and have defaults derived from the rules above. Both ``:`` and ``::`` indicate to select all elements along a single axis (dimension). +- Indexing via ``:`` and ``::`` must be equivalent and have defaults derived from the rules above. Both ``:`` and ``::`` indicate to select all elements along a single axis (dimension). .. note:: This specification does not require "clipping" out-of-bounds slice indices. This is in contrast to Python slice semantics where ``0:100`` and ``0:10`` are equivalent on a list of length ``10``. -The following ranges for the start and stop values of a slice *must* be supported. Let ``n`` be the axis (dimension) size being sliced. For a slice ``i:j:k``, the behavior specified above *should* be implemented for the following: +The following ranges for the start and stop values of a slice must be supported. Let ``n`` be the axis (dimension) size being sliced. For a slice ``i:j:k``, the behavior specified above should be implemented for the following: - ``i`` or ``j`` omitted (``None``). - ``-n <= i <= n``. @@ -124,34 +124,34 @@ The behavior outside of these bounds is unspecified. Multi-axis Indexing ------------------- -Multi-dimensional arrays *must* extend the concept of single-axis indexing to multiple axes by applying single-axis indexing rules along each axis (dimension) and supporting the following additional rules. Let ``N`` be the number of dimensions ("rank") of a multi-dimensional array ``A``. +Multi-dimensional arrays must extend the concept of single-axis indexing to multiple axes by applying single-axis indexing rules along each axis (dimension) and supporting the following additional rules. Let ``N`` be the number of dimensions ("rank") of a multi-dimensional array ``A``. - Each axis may be independently indexed via single-axis indexing by providing a comma-separated sequence ("selection tuple") of single-axis indexing expressions (e.g., ``A[:, 2:10, :, 5]``). .. note:: In Python, ``A[(exp1, exp2, ..., expN)]`` is equivalent to ``A[exp1, exp2, ..., expN]``; the latter is syntactic sugar for the former. - Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` *must* be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` *must* be equivalent to ``A[2:10, :]``. And so on and so forth. + Accordingly, if ``A`` has rank ``1``, then ``A[(2:10,)]`` must be equivalent to ``A[2:10]``. If ``A`` has rank ``2``, then ``A[(2:10, :)]`` must be equivalent to ``A[2:10, :]``. And so on and so forth. -- Providing a single nonnegative integer ``i`` as a single-axis index *must* index the same elements as the slice ``i:i+1``. +- Providing a single nonnegative integer ``i`` as a single-axis index must index the same elements as the slice ``i:i+1``. -- Providing a single negative integer ``i`` as a single-axis index *must* index the same elements as the slice ``n+i:n+i+1``, where ``n`` is the axis (dimension) size. +- Providing a single negative integer ``i`` as a single-axis index must index the same elements as the slice ``n+i:n+i+1``, where ``n`` is the axis (dimension) size. -- Providing a single integer as a single-axis index *must* reduce the number of array dimensions by ``1`` (i.e., the array rank *must* decrease by one; if ``A`` has rank ``2``, ``rank(A)-1 == rank(A[0, :])``). In particular, a selection tuple with the ``m``\th element an integer (and all other entries ``:``) indexes a sub-array with rank ``N-1``. +- Providing a single integer as a single-axis index must reduce the number of array dimensions by ``1`` (i.e., the array rank must decrease by one; if ``A`` has rank ``2``, ``rank(A)-1 == rank(A[0, :])``). In particular, a selection tuple with the ``m``\th element an integer (and all other entries ``:``) indexes a sub-array with rank ``N-1``. .. note:: When providing a single integer as a single-axis index to an array of rank ``1``, the result should be an array of rank ``0``, not a NumPy scalar. Note that this behavior differs from NumPy. -- Providing a slice *must* retain array dimensions (i.e., the array rank *must* remain the same; ``rank(A) == rank(A[:])``). +- Providing a slice must retain array dimensions (i.e., the array rank must remain the same; ``rank(A) == rank(A[:])``). -- Providing `ellipsis `_ *must* apply ``:`` to each dimension necessary to index all dimensions (e.g., if ``A`` has rank ``4``, ``A[1:, ..., 2:5] == A[1:, :, :, 2:5]``). Only a single ellipsis *must* be allowed. An ``IndexError`` exception *must* be raised if more than one ellipsis is provided. +- Providing `ellipsis `_ must apply ``:`` to each dimension necessary to index all dimensions (e.g., if ``A`` has rank ``4``, ``A[1:, ..., 2:5] == A[1:, :, :, 2:5]``). Only a single ellipsis must be allowed. An ``IndexError`` exception must be raised if more than one ellipsis is provided. -- Providing an empty tuple or an ellipsis to an array of rank ``0`` *must* result in an array of the same rank (i.e., if ``A`` has rank ``0``, ``A == A[()]`` and ``A == A[...]``). +- Providing an empty tuple or an ellipsis to an array of rank ``0`` must result in an array of the same rank (i.e., if ``A`` has rank ``0``, ``A == A[()]`` and ``A == A[...]``). .. note:: This behavior differs from NumPy where providing an empty tuple to an array of rank ``0`` returns a NumPy scalar. -- Each ``None`` in the selection tuple *must* expand the dimensions of the resulting selection by one dimension of size ``1``. The position of the added dimension *must* be the same as the position of ``None`` in the selection tuple. +- Each ``None`` in the selection tuple must expand the dimensions of the resulting selection by one dimension of size ``1``. The position of the added dimension must be the same as the position of ``None`` in the selection tuple. .. note:: Expanding dimensions can be equivalently achieved via repeated invocation of :func:`~array_api.expand_dims`. @@ -159,14 +159,14 @@ Multi-dimensional arrays *must* extend the concept of single-axis indexing to mu .. note:: The constant ``newaxis`` is an alias of ``None`` and can thus be used in a similar manner as ``None``. -- Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) *should* equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression *should* be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception *should* be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``. +- Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) should equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression should be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception should be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``. .. note:: Some libraries, such as SymPy, support flat indexing (i.e., providing a single-axis indexing expression to a higher-dimensional array). That practice is not supported here. To perform flat indexing, use ``reshape(x, (-1,))[integer]``. -- An ``IndexError`` exception *must* be raised if the number of provided single-axis indexing expressions (excluding ``None``) is greater than ``N``. +- An ``IndexError`` exception must be raised if the number of provided single-axis indexing expressions (excluding ``None``) is greater than ``N``. .. note:: This specification leaves unspecified the behavior of providing a slice which attempts to select elements along a particular axis, but whose starting index is out-of-bounds. @@ -181,28 +181,28 @@ Boolean Array Indexing For common boolean array use cases (e.g., using a dynamically-sized boolean array mask to filter the values of another array), the shape of the output array is data-dependent; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find boolean array indexing difficult to implement. Accordingly, such libraries may choose to omit boolean array indexing. See :ref:`data-dependent-output-shapes` section for more details. -An array *must* support indexing where the **sole index** is an ``M``-dimensional boolean array ``B`` with shape ``S1 = (s1, ..., sM)`` according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S2 = (s1, ..., sM, ..., sN)``. +An array must support indexing where the **sole index** is an ``M``-dimensional boolean array ``B`` with shape ``S1 = (s1, ..., sM)`` according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S2 = (s1, ..., sM, ..., sN)``. .. note:: The prohibition against combining boolean array indices with other single-axis indexing expressions includes the use of ``None``. To expand dimensions of the returned array, use repeated invocation of :func:`~array_api.expand_dims`. -- If ``N >= M``, then ``A[B]`` *must* replace the first ``M`` dimensions of ``A`` with a single dimension having a size equal to the number of ``True`` elements in ``B``. The values in the resulting array *must* be in row-major (C-style order); this is equivalent to ``A[nonzero(B)]``. +- If ``N >= M``, then ``A[B]`` must replace the first ``M`` dimensions of ``A`` with a single dimension having a size equal to the number of ``True`` elements in ``B``. The values in the resulting array must be in row-major (C-style order); this is equivalent to ``A[nonzero(B)]``. .. note:: For example, if ``N == M == 2``, indexing ``A`` via a boolean array ``B`` will return a one-dimensional array whose size is equal to the number of ``True`` elements in ``B``. -- If ``N < M``, then an ``IndexError`` exception *must* be raised. +- If ``N < M``, then an ``IndexError`` exception must be raised. - The size of each dimension in ``B`` must equal the size of the corresponding dimension in ``A`` or be ``0``, beginning with the first dimension in ``A``. If a dimension size does not equal the size of the corresponding dimension in ``A`` and is not ``0``, then an ``IndexError`` exception must be raised. -- The elements of a boolean index array *must* be iterated in row-major, C-style order, with the exception of zero-dimensional boolean arrays. +- The elements of a boolean index array must be iterated in row-major, C-style order, with the exception of zero-dimensional boolean arrays. -- A zero-dimensional boolean index array (equivalent to ``True`` or ``False``) *must* follow the same axis replacement rules stated above. Namely, a zero-dimensional boolean index array removes zero dimensions and adds a single dimension of length ``1`` if the index array's value is ``True`` and of length ``0`` if the index array's value is ``False``. Accordingly, for a zero-dimensional boolean index array ``B``, the result of ``A[B]`` has shape ``S = (1, s1, ..., sN)`` if the index array's value is ``True`` and has shape ``S = (0, s1, ..., sN)`` if the index array's value is ``False``. +- A zero-dimensional boolean index array (equivalent to ``True`` or ``False``) must follow the same axis replacement rules stated above. Namely, a zero-dimensional boolean index array removes zero dimensions and adds a single dimension of length ``1`` if the index array's value is ``True`` and of length ``0`` if the index array's value is ``False``. Accordingly, for a zero-dimensional boolean index array ``B``, the result of ``A[B]`` has shape ``S = (1, s1, ..., sN)`` if the index array's value is ``True`` and has shape ``S = (0, s1, ..., sN)`` if the index array's value is ``False``. Return Values ------------- -The result of an indexing operation (e.g., multi-axis indexing, boolean array indexing, etc) *must* be an array of the same data type as the indexed array. +The result of an indexing operation (e.g., multi-axis indexing, boolean array indexing, etc) must be an array of the same data type as the indexed array. .. note:: The specified return value behavior includes indexing operations which return a single value (e.g., accessing a single element within a one-dimensional array). diff --git a/spec/draft/API_specification/indexing_functions.rst b/spec/draft/API_specification/indexing_functions.rst index bae575ce9..c13e55ecf 100644 --- a/spec/draft/API_specification/indexing_functions.rst +++ b/spec/draft/API_specification/indexing_functions.rst @@ -5,7 +5,7 @@ Indexing Functions Array API specification for functions for indexing arrays. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/inspection.rst b/spec/draft/API_specification/inspection.rst index a28c7c37d..89d9c602a 100644 --- a/spec/draft/API_specification/inspection.rst +++ b/spec/draft/API_specification/inspection.rst @@ -5,7 +5,7 @@ Inspection Array API specification for namespace inspection utilities. -A conforming implementation of the array API standard *must* provide and support the following functions and associated inspection APIs. +A conforming implementation of the array API standard must provide and support the following functions and associated inspection APIs. Objects in API @@ -26,7 +26,7 @@ Objects in API Inspection APIs --------------- -In the namespace (or class) returned by ``__array_namespace_info__``, a conforming implementation of the array API standard *must* provide and support the following functions (or methods) for programmatically querying data type and device support, capabilities, and other specification-defined implementation-specific behavior, as documented in the functions described below. +In the namespace (or class) returned by ``__array_namespace_info__``, a conforming implementation of the array API standard must provide and support the following functions (or methods) for programmatically querying data type and device support, capabilities, and other specification-defined implementation-specific behavior, as documented in the functions described below. .. NOTE: please keep the functions in alphabetical order diff --git a/spec/draft/API_specification/linear_algebra_functions.rst b/spec/draft/API_specification/linear_algebra_functions.rst index 670cbdc24..04d36f50a 100644 --- a/spec/draft/API_specification/linear_algebra_functions.rst +++ b/spec/draft/API_specification/linear_algebra_functions.rst @@ -3,7 +3,7 @@ Linear Algebra Functions Array API specification for linear algebra functions. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. .. currentmodule:: array_api diff --git a/spec/draft/API_specification/manipulation_functions.rst b/spec/draft/API_specification/manipulation_functions.rst index bb7d00711..395c1c3e2 100644 --- a/spec/draft/API_specification/manipulation_functions.rst +++ b/spec/draft/API_specification/manipulation_functions.rst @@ -3,7 +3,7 @@ Manipulation Functions Array API specification for manipulating arrays. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/searching_functions.rst b/spec/draft/API_specification/searching_functions.rst index 0c5d8b696..1a584f158 100644 --- a/spec/draft/API_specification/searching_functions.rst +++ b/spec/draft/API_specification/searching_functions.rst @@ -5,7 +5,7 @@ Searching Functions Array API specification for functions for searching arrays. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/set_functions.rst b/spec/draft/API_specification/set_functions.rst index c7e027eaa..addf31e1f 100644 --- a/spec/draft/API_specification/set_functions.rst +++ b/spec/draft/API_specification/set_functions.rst @@ -3,7 +3,7 @@ Set Functions Array API specification for creating and operating on sets. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/sorting_functions.rst b/spec/draft/API_specification/sorting_functions.rst index d19527612..ad3af8857 100644 --- a/spec/draft/API_specification/sorting_functions.rst +++ b/spec/draft/API_specification/sorting_functions.rst @@ -3,7 +3,7 @@ Sorting Functions Array API specification for sorting functions. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. .. note:: @@ -12,7 +12,7 @@ A conforming implementation of the array API standard *must* provide and support Implementations may choose to sort signed zeros (``-0 < +0``) or may choose to rely solely on value equality (``==``). - Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention *should* be clearly documented in the conforming implementation's documentation. + Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention should be clearly documented in the conforming implementation's documentation. While defining a sort order for IEEE 754 floating-point numbers is recommended in order to facilitate reproducible and consistent sort results, doing so is not currently required by this specification. diff --git a/spec/draft/API_specification/statistical_functions.rst b/spec/draft/API_specification/statistical_functions.rst index 5e981251b..eb5e1a5d6 100644 --- a/spec/draft/API_specification/statistical_functions.rst +++ b/spec/draft/API_specification/statistical_functions.rst @@ -3,7 +3,7 @@ Statistical Functions Array API specification for statistical functions. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/type_promotion.rst b/spec/draft/API_specification/type_promotion.rst index 00248e473..339b90e45 100644 --- a/spec/draft/API_specification/type_promotion.rst +++ b/spec/draft/API_specification/type_promotion.rst @@ -15,7 +15,7 @@ Type promotion rules can be understood at a high level from the following diagra Rules ----- -A conforming implementation of the array API standard *must* implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation. +A conforming implementation of the array API standard must implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation. A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification. @@ -114,7 +114,7 @@ where Notes ~~~~~ -- Type promotion rules *must* apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays *must* be subject to the same type promotion rules as dimensional arrays. +- Type promotion rules must apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays must be subject to the same type promotion rules as dimensional arrays. - Type promotion of non-numerical data types to numerical data types is unspecified (e.g., ``bool`` to ``intxx`` or ``floatxx``). .. note:: @@ -123,7 +123,7 @@ Notes Mixing arrays with Python scalars ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using Python scalars (i.e., instances of ``bool``, ``int``, ``float``, ``complex``) together with arrays *must* be supported for: +Using Python scalars (i.e., instances of ``bool``, ``int``, ``float``, ``complex``) together with arrays must be supported for: - ``array scalar`` - ``scalar array`` diff --git a/spec/draft/API_specification/utility_functions.rst b/spec/draft/API_specification/utility_functions.rst index 084da845a..a09c99f79 100644 --- a/spec/draft/API_specification/utility_functions.rst +++ b/spec/draft/API_specification/utility_functions.rst @@ -3,7 +3,7 @@ Utility Functions Array API specification for utility functions. -A conforming implementation of the array API standard *must* provide and support the following functions. +A conforming implementation of the array API standard must provide and support the following functions. Objects in API diff --git a/spec/draft/API_specification/version.rst b/spec/draft/API_specification/version.rst index 289a0c216..346395d9a 100644 --- a/spec/draft/API_specification/version.rst +++ b/spec/draft/API_specification/version.rst @@ -3,7 +3,7 @@ Version Array API specification for versioning. -A conforming implementation of the array API standard *must* provide a `__array_api_version__` attribute - see :ref:`api-versioning` for details. +A conforming implementation of the array API standard must provide a `__array_api_version__` attribute - see :ref:`api-versioning` for details. Objects in API diff --git a/spec/draft/design_topics/C_API.rst b/spec/draft/design_topics/C_API.rst index 388eab5da..6a44596b0 100644 --- a/spec/draft/design_topics/C_API.rst +++ b/spec/draft/design_topics/C_API.rst @@ -19,7 +19,7 @@ to the supported array type. Often a zero-copy conversion to ``numpy.ndarray`` is possible, at least for CPU arrays. If that's the case, this may be a good way to support other array types. The main difficulty in that case will be getting the return array type right - however, - this standard does provide a Python-level API for array construction that *should* allow + this standard does provide a Python-level API for array construction that should allow doing this. A relevant question is if it's possible to know with certainty that a conversion will be zero-copy. This may indeed be possible, see :ref:`data-interchange`. diff --git a/spec/draft/design_topics/accuracy.rst b/spec/draft/design_topics/accuracy.rst index 5cc1d855a..61a2c49aa 100644 --- a/spec/draft/design_topics/accuracy.rst +++ b/spec/draft/design_topics/accuracy.rst @@ -23,7 +23,7 @@ including the corresponding element-wise array APIs defined in this standard - multiply - divide -for floating-point operands *must* return the nearest representable value according to IEEE 754-2019 and a supported rounding mode. By default, the rounding mode *should* be ``roundTiesToEven`` (i.e., round to nearest with ties rounded toward the nearest value with an even least significant bit). +for floating-point operands must return the nearest representable value according to IEEE 754-2019 and a supported rounding mode. By default, the rounding mode should be ``roundTiesToEven`` (i.e., round to nearest with ties rounded toward the nearest value with an even least significant bit). Mathematical Functions ---------------------- @@ -56,7 +56,7 @@ except to require specific results for certain argument values that represent bo .. note:: To help readers identify functions lacking precisely defined accuracy behavior, this specification uses the phrase "implementation-dependent approximation" in function descriptions. -For other argument values, these functions *should* compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. +For other argument values, these functions should compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in `FDLIBM `_, the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. diff --git a/spec/draft/design_topics/complex_numbers.rst b/spec/draft/design_topics/complex_numbers.rst index a76d12870..0eca79e91 100644 --- a/spec/draft/design_topics/complex_numbers.rst +++ b/spec/draft/design_topics/complex_numbers.rst @@ -37,7 +37,7 @@ In contrast to real-valued floating-point numbers which have well-defined behavi Complex Number Ordering ----------------------- -Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation *must* satisfy the following properties: +Given a set :math:`\{a_1, \ldots, a_n\}`, an order relation must satisfy the following properties: 1. **Reflexive**: for any :math:`a` in the set, :math:`a \leq a`. 2. **Transitive**: for any :math:`a`, :math:`b`, and :math:`c` in the set, if :math:`a \leq b` and :math:`b \leq c`, then :math:`a \leq c`. @@ -50,7 +50,7 @@ Defining an order relation for complex numbers which satisfies all six propertie In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an ordering for complex numbers (e.g., lexicographic); however, consumers of the array API standard should **not** assume that complex number ordering is consistent between implementations or even supported. -If a conforming implementation chooses to define an ordering for complex numbers, the ordering *must* be clearly documented. +If a conforming implementation chooses to define an ordering for complex numbers, the ordering must be clearly documented. Valued-based Promotion @@ -58,4 +58,4 @@ Valued-based Promotion According to the type promotion rules described in this specification (see :ref:`type-promotion`), only the data types of the input arrays participating in an operation matter, not their values. The same principle applies to situations in which one or more results of operations on real-valued arrays are mathematically defined in the complex domain, but not in their real domain. -By convention, the principal square root of :math:`-1` is :math:`j`, where :math:`j` is the imaginary unit. Despite this convention, for those operations supporting type promotion, conforming implementations *must* only consider input array data types when determining the data type of the output array. For example, if a real-valued input array is provided to :func:`~array_api.sqrt`, the output array *must* also be real-valued, even if the input array contains negative values. Accordingly, if a consumer of a conforming implementation of this specification desires for an operation's results to include the complex domain, the consumer *should* first cast the input array(s) to an appropriate complex floating-point data type before performing the operation. +By convention, the principal square root of :math:`-1` is :math:`j`, where :math:`j` is the imaginary unit. Despite this convention, for those operations supporting type promotion, conforming implementations must only consider input array data types when determining the data type of the output array. For example, if a real-valued input array is provided to :func:`~array_api.sqrt`, the output array must also be real-valued, even if the input array contains negative values. Accordingly, if a consumer of a conforming implementation of this specification desires for an operation's results to include the complex domain, the consumer should first cast the input array(s) to an appropriate complex floating-point data type before performing the operation. diff --git a/spec/draft/design_topics/copies_views_and_mutation.rst b/spec/draft/design_topics/copies_views_and_mutation.rst index 36a44fe14..1ca5a039c 100644 --- a/spec/draft/design_topics/copies_views_and_mutation.rst +++ b/spec/draft/design_topics/copies_views_and_mutation.rst @@ -61,7 +61,7 @@ standard chooses to include them. The situation with ``out=`` is slightly different - it's less heavily used, and easier to avoid. It's also not an optimal API, because it mixes an "efficiency of implementation" consideration ("you're allowed to do this -inplace") with the semantics of a function ("the output _*must*_ be placed into +inplace") with the semantics of a function ("the output _must_ be placed into this array). There are libraries that do some form of tracing or abstract interpretation over a language that does not support mutation (to make analysis easier); in those cases implementing ``out=`` with correct handling of @@ -74,4 +74,4 @@ of reusing arrays that are no longer needed as buffers. This leaves the problem of the initial example - with this API standard it remains possible to write code that will not work the same for all array -libraries. This is something that the user *must* be careful about. +libraries. This is something that the user must be careful about. diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 37a1eb0f3..3b3040672 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -9,17 +9,17 @@ As discussed in the :ref:`assumptions-dependencies ` section, *array types* implemented by another library. Instead, the array can be converted to a "native" array type. -The interchange mechanism *must* offer the following: +The interchange mechanism must offer the following: 1. Data access via a protocol that describes the memory layout of the array in an implementation-independent manner. - *Rationale: any number of libraries *must* be able to exchange data, and no - particular package *must* be needed to do so.* + *Rationale: any number of libraries must be able to exchange data, and no + particular package must be needed to do so.* 2. Support for all dtypes in this API standard (see :ref:`data-types`). -3. Device support. It *must* be possible to determine on what device the array +3. Device support. It must be possible to determine on what device the array that is to be converted lives. *Rationale: there are CPU-only, GPU-only, and multi-device array types; @@ -57,7 +57,7 @@ support libraries that already implement buffer protocol support. (Python-side only at the moment) An issue with device-specific protocols are: if two libraries both - support multiple device types, in which order *should* the protocols be + support multiple device types, in which order should the protocols be tried? A growth in the number of protocols to support each time a new device gets supported by array libraries (e.g. TPUs, AMD GPUs, emerging hardware accelerators) also seems undesirable. @@ -67,7 +67,7 @@ support libraries that already implement buffer protocol support. being a lot older and standardized as part of Python itself via PEP 3118, hardly has any support from array libraries. CPU interoperability is mostly dealt with via the NumPy-specific ``__array__`` (which, when called, - means the object it is attached to *must* return a ``numpy.ndarray`` + means the object it is attached to must return a ``numpy.ndarray`` containing the data the object holds). See the `RFC to adopt DLPack `_ diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index 2b3079a0d..593b0b9fa 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -78,7 +78,7 @@ rather than hard requirements: - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function). - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices). - Use a default for ``device=None`` which is consistent between functions within the same library. -- If a library has multiple ways of controlling device placement, the most explicit method *should* have the highest priority. For example: +- If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority. For example: 1. If ``device=`` keyword is specified, that always takes precedence diff --git a/spec/draft/design_topics/exceptions.rst b/spec/draft/design_topics/exceptions.rst index e8ecd4f2a..570fe56e3 100644 --- a/spec/draft/design_topics/exceptions.rst +++ b/spec/draft/design_topics/exceptions.rst @@ -18,11 +18,11 @@ ones. In specific cases, it may be useful to provide guidance to array library authors regarding what an appropriate exception is. That guidance will be -phrased as **should** rather than **must** (typically in a *Raises* section), +phrased as *should* rather than *must* (typically in a *Raises* section), because (a) there may be reasons for an implementer to deviate, and (b) more often than not, existing array library implementation already differ in their choices, and it may not be worth them breaking backward compatibility in order -to comply with a "*must*" in this standard. +to comply with a "must" in this standard. -In other cases, this standard will only specify that an exception *should* or +In other cases, this standard will only specify that an exception should or must be raised, but not mention what type of exception that is. diff --git a/spec/draft/design_topics/static_typing.rst b/spec/draft/design_topics/static_typing.rst index 72834a126..26a1fb901 100644 --- a/spec/draft/design_topics/static_typing.rst +++ b/spec/draft/design_topics/static_typing.rst @@ -39,12 +39,12 @@ should both be fine. There may be other variations possible. Also note that this standard does not require that input and output array types are the same (they're expected to be defined in the same library though). Given that array libraries don't have to be aware of other types of arrays defined in -other libraries (see :ref:`assumptions-dependencies`), this *should* be enough +other libraries (see :ref:`assumptions-dependencies`), this should be enough for a single array library. That said, an array-consuming library aiming to support multiple array types may need more - for example a protocol to enable structural subtyping. This API standard currently takes the position that it does not provide any -reference implementation or package that can or *should* be relied on at +reference implementation or package that can or should be relied on at runtime, hence no such protocol is defined here. This may be dealt with in a future version of this standard. diff --git a/spec/draft/extensions/fourier_transform_functions.rst b/spec/draft/extensions/fourier_transform_functions.rst index d0882bb0a..170ae390b 100644 --- a/spec/draft/extensions/fourier_transform_functions.rst +++ b/spec/draft/extensions/fourier_transform_functions.rst @@ -6,9 +6,9 @@ Fourier transform Functions Extension name and usage ------------------------ -The name of the namespace providing the extension *must* be: ``fft``. +The name of the namespace providing the extension must be: ``fft``. -If implemented, this ``fft`` extension *must* be retrievable via:: +If implemented, this ``fft`` extension must be retrievable via:: >>> xp = x.__array_namespace__() >>> if hasattr(xp, 'fft'): @@ -18,7 +18,7 @@ If implemented, this ``fft`` extension *must* be retrievable via:: Objects in API -------------- -A conforming implementation of this ``fft`` extension *must* provide and support the following functions. +A conforming implementation of this ``fft`` extension must provide and support the following functions. .. currentmodule:: array_api.fft diff --git a/spec/draft/extensions/index.rst b/spec/draft/extensions/index.rst index 377fbeb3d..3b9409954 100644 --- a/spec/draft/extensions/index.rst +++ b/spec/draft/extensions/index.rst @@ -6,13 +6,13 @@ Extensions Extensions are coherent sets of functionality that are commonly implemented across array libraries. Each array library supporting this standard may, but is not required to, implement an extension. If an extension is supported, it -*must* be accessible inside the main array API supporting namespace as a separate +must be accessible inside the main array API supporting namespace as a separate namespace. -Extension module implementors *must* aim to provide all functions and other +Extension module implementors must aim to provide all functions and other public objects in an extension. The rationale for this is that downstream usage can then check whether or not the extension is present (using ``hasattr(xp, -'extension_name')`` *should* be enough), and can then assume that functions are +'extension_name')`` should be enough), and can then assume that functions are implemented. This in turn makes it also easy for array-consuming libraries to document which array libraries they support - e.g., "all libraries implementing the array API standard and its linear algebra extension". @@ -21,7 +21,7 @@ The mechanism through which the extension namespace is made available is up to the implementer, e.g. via a regular submodule that is imported under the ``linalg`` name, or via a module-level ``__getattr__``. -The functions in an extension *must* adhere to the same conventions as those in +The functions in an extension must adhere to the same conventions as those in the array API standard. See :ref:`api-specification`. ------------------------------------------------------------------------------ diff --git a/spec/draft/extensions/linear_algebra_functions.rst b/spec/draft/extensions/linear_algebra_functions.rst index abf5a590f..938221c79 100644 --- a/spec/draft/extensions/linear_algebra_functions.rst +++ b/spec/draft/extensions/linear_algebra_functions.rst @@ -8,9 +8,9 @@ Linear Algebra Extension Extension name and usage ------------------------ -The name of the namespace providing the extension *must* be: ``linalg``. +The name of the namespace providing the extension must be: ``linalg``. -If implemented, this ``linalg`` extension *must* be retrievable via:: +If implemented, this ``linalg`` extension must be retrievable via:: >>> xp = x.__array_namespace__() >>> if hasattr(xp, 'linalg'): @@ -24,13 +24,13 @@ A principal goal of this specification is to standardize commonly implemented in Accordingly, the standardization process affords the opportunity to reduce interface complexity among linear algebra APIs by inferring and subsequently codifying common design themes, thus allowing more consistent APIs. What follows is the set of design principles governing the APIs which follow: -1. **Batching**: if an operation is explicitly defined in terms of matrices (i.e., two-dimensional arrays), then the associated interface *should* support "batching" (i.e., the ability to perform the operation over a "stack" of matrices). Example operations include: +1. **Batching**: if an operation is explicitly defined in terms of matrices (i.e., two-dimensional arrays), then the associated interface should support "batching" (i.e., the ability to perform the operation over a "stack" of matrices). Example operations include: - ``inv``: computing the multiplicative inverse of a square matrix. - ``cholesky``: performing Cholesky decomposition. - ``matmul``: performing matrix multiplication. -2. **Data types**: if an operation requires decimal operations and :ref:`type-promotion` semantics are undefined (e.g., as is the case for mixed-kind promotions), then the associated interface *should* be specified as being restricted to floating-point data types. While the specification uses the term "*SHOULD*" rather than "*MUST*", a conforming implementation of the array API standard *should* only ignore the restriction provided overly compelling reasons for doing so. Example operations which *should* be limited to floating-point data types include: +2. **Data types**: if an operation requires decimal operations and :ref:`type-promotion` semantics are undefined (e.g., as is the case for mixed-kind promotions), then the associated interface should be specified as being restricted to floating-point data types. While the specification uses the term "SHOULD" rather than "MUST", a conforming implementation of the array API standard should only ignore the restriction provided overly compelling reasons for doing so. Example operations which should be limited to floating-point data types include: - ``inv``: computing the multiplicative inverse. - ``slogdet``: computing the natural logarithm of the absolute value of the determinant. @@ -42,23 +42,23 @@ Accordingly, the standardization process affords the opportunity to reduce inter - ``trace``: computing the sum along the diagonal. - ``cross``: computing the vector cross product. - Lastly, certain operations may be performed independent of data type, and, thus, the associated interfaces *should* support all data types specified in this standard. Example operations include: + Lastly, certain operations may be performed independent of data type, and, thus, the associated interfaces should support all data types specified in this standard. Example operations include: - ``matrix_transpose``: computing the transpose. - ``diagonal``: returning the diagonal. -3. **Return values**: if an interface has more than one return value, the interface *should* return a namedtuple consisting of each value. +3. **Return values**: if an interface has more than one return value, the interface should return a namedtuple consisting of each value. In general, interfaces should avoid polymorphic return values (e.g., returning an array **or** a namedtuple, dependent on, e.g., an optional keyword argument). Dedicated interfaces for each return value type are preferred, as dedicated interfaces are easier to reason about at both the implementation level and user level. Example interfaces which could be combined into a single overloaded interface, but are not, include: - ``eigh``: computing both eigenvalues and eigenvectors. - ``eigvalsh``: computing only eigenvalues. -4. **Implementation agnosticism**: a standardized interface *should* eschew parameterization (including keyword arguments) biased toward particular implementations. +4. **Implementation agnosticism**: a standardized interface should eschew parameterization (including keyword arguments) biased toward particular implementations. - Historically, at a time when all array computing happened on CPUs, BLAS and LAPACK underpinned most numerical computing libraries and environments. Naturally, language and library abstractions catered to the parameterization of those libraries, often exposing low-level implementation details verbatim in their higher-level interfaces, even if such choices would be considered poor or ill-advised by today's standards (e.g., NumPy's use of `UPLO` in `eigh`). However, the present day is considerably different. While still important, BLAS and LAPACK no longer hold a monopoly over linear algebra operations, especially given the proliferation of devices and hardware on which such operations *must* be performed. Accordingly, interfaces *must* be conservative in the parameterization they support in order to best ensure universality. Such conservatism applies even to performance optimization parameters afforded by certain hardware. + Historically, at a time when all array computing happened on CPUs, BLAS and LAPACK underpinned most numerical computing libraries and environments. Naturally, language and library abstractions catered to the parameterization of those libraries, often exposing low-level implementation details verbatim in their higher-level interfaces, even if such choices would be considered poor or ill-advised by today's standards (e.g., NumPy's use of `UPLO` in `eigh`). However, the present day is considerably different. While still important, BLAS and LAPACK no longer hold a monopoly over linear algebra operations, especially given the proliferation of devices and hardware on which such operations must be performed. Accordingly, interfaces must be conservative in the parameterization they support in order to best ensure universality. Such conservatism applies even to performance optimization parameters afforded by certain hardware. -5. **Orthogonality**: an interface *should* have clearly defined and delineated functionality which, ideally, has no overlap with the functionality of other interfaces in the specification. Providing multiple interfaces which can all perform the same operation creates unnecessary confusion regarding interface applicability (i.e., which interface is best at which time) and decreases readability of both library and user code. Where overlap is possible, the specification *must* be parsimonious in the number of interfaces, ensuring that each interface provides a unique and compelling abstraction. Examples of related interfaces which provide distinct levels of abstraction (and generality) include: +5. **Orthogonality**: an interface should have clearly defined and delineated functionality which, ideally, has no overlap with the functionality of other interfaces in the specification. Providing multiple interfaces which can all perform the same operation creates unnecessary confusion regarding interface applicability (i.e., which interface is best at which time) and decreases readability of both library and user code. Where overlap is possible, the specification must be parsimonious in the number of interfaces, ensuring that each interface provides a unique and compelling abstraction. Examples of related interfaces which provide distinct levels of abstraction (and generality) include: - ``vecdot``: computing the dot product of two vectors. - ``matmul``: performing matrix multiplication (including between two vectors and thus the dot product). @@ -82,7 +82,7 @@ Accordingly, the standardization process affords the opportunity to reduce inter Objects in API -------------- -A conforming implementation of this ``linalg`` extension *must* provide and support the following functions. +A conforming implementation of this ``linalg`` extension must provide and support the following functions. .. NOTE: please keep the functions in alphabetical order