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 f953f0596..cf7e3cc07 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 536317dbb..7d0d62be9 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. Should have one or more dimensions (axes). 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 ----- @@ -57,10 +57,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 a43dc8dcf..537e2d524 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 04d4fd818..5f0d1a44a 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 """ @@ -189,13 +189,13 @@ def where( 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``. Notes ----- - - At least one of ``x1`` and ``x2`` must be an array. - - If either ``x1`` or ``x2`` is a scalar value, the returned array must have a data type determined according to :ref:`mixing-scalars-and-arrays`. + - At least one of ``x1`` and ``x2`` *must* be an array. + - If either ``x1`` or ``x2`` is a scalar value, the returned array *must* have a data type determined according to :ref:`mixing-scalars-and-arrays`. .. versionchanged:: 2024.12 Added support for scalar arguments. 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)``). """