From bd90fb84d0bf2fa216122dd77ffa2e00065ad9b9 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 25 Jan 2023 18:49:20 -0500 Subject: [PATCH 1/5] Add version changed to functions that were modified for complex support in 2022 --- src/array_api_stubs/_draft/array_object.py | 43 ++++++- .../_draft/creation_functions.py | 24 ++++ .../_draft/data_type_functions.py | 6 + .../_draft/elementwise_functions.py | 105 ++++++++++++++++++ src/array_api_stubs/_draft/linalg.py | 57 ++++++++++ .../_draft/linear_algebra_functions.py | 9 ++ .../_draft/searching_functions.py | 3 + src/array_api_stubs/_draft/set_functions.py | 12 ++ .../_draft/statistical_functions.py | 6 + .../_draft/utility_functions.py | 6 + 10 files changed, 270 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 89e5ee1c3..6e1d282ce 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -136,9 +136,12 @@ def __abs__(self: array, /) -> array: 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). - .. note:: 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. """ def __add__(self: array, other: Union[int, float, array], /) -> array: @@ -160,6 +163,9 @@ def __add__(self: array, other: Union[int, float, array], /) -> array: .. note:: 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. """ def __and__(self: array, other: Union[int, bool, array], /) -> array: @@ -228,6 +234,9 @@ def __bool__(self: array, /) -> bool: - 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 AND of ``bool(real(self))`` and ``bool(imag(self))``. + + .. versionchanged:: 2022.12 + Added boolean and complex data type support. """ def __complex__(self: array, /) -> complex: @@ -326,6 +335,8 @@ def __dlpack__( errors are raised when export fails for other reasons (e.g., incorrect arguments passed or out of memory). + .. versionchanged:: 2022.12 + Added BufferError. """ def __dlpack_device__(self: array, /) -> Tuple[Enum, int]: @@ -401,6 +412,9 @@ def __float__(self: array, /) -> float: - If ``self`` is ``True``, the result is ``1``. - If ``self`` is ``False``, the result is ``0``. + + .. versionchanged:: 2022.12 + Added boolean and complex data type support. """ def __floordiv__(self: array, other: Union[int, float, array], /) -> array: @@ -551,6 +565,9 @@ def __int__(self: array, /) -> int: - If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``. - If ``self`` is ``NaN``, raise ``ValueError``. + + .. versionchanged:: 2022.12 + Added boolean and complex data type support. """ def __invert__(self: array, /) -> array: @@ -682,6 +699,9 @@ def __matmul__(self: array, other: array, /) -> array: - if ``self`` is a one-dimensional array having shape ``(K,)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``. - if ``self`` is an array having shape ``(..., M, K)``, ``other`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. - if ``self`` is an array having shape ``(..., M, K)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ def __mod__(self: array, other: Union[int, float, array], /) -> array: @@ -730,6 +750,9 @@ def __mul__(self: array, other: Union[int, float, array], /) -> array: .. note:: 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. """ def __ne__(self: array, other: Union[int, float, bool, array], /) -> array: @@ -751,6 +774,9 @@ def __ne__(self: array, other: Union[int, float, bool, array], /) -> array: .. note:: Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.not_equal`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ def __neg__(self: array, /) -> array: @@ -776,6 +802,9 @@ def __neg__(self: array, /) -> array: .. note:: 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. """ def __or__(self: array, other: Union[int, bool, array], /) -> array: @@ -816,6 +845,9 @@ def __pos__(self: array, /) -> array: .. note:: 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. """ def __pow__(self: array, other: Union[int, float, array], /) -> array: @@ -842,6 +874,9 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array: .. note:: 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. """ def __rshift__(self: array, other: Union[int, array], /) -> array: @@ -916,6 +951,9 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array: .. note:: 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. """ def __truediv__(self: array, other: Union[int, float, array], /) -> array: @@ -942,6 +980,9 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: .. note:: 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. """ def __xor__(self: array, other: Union[int, bool, array], /) -> array: diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 3f577b542..8949c104c 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -97,6 +97,9 @@ def asarray( ------- out: array an array containing the data from ``obj``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -179,6 +182,9 @@ def eye( ------- out: array an array where all elements are equal to zero, except for the ``k``\th diagonal, whose values are equal to one. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -237,6 +243,9 @@ def full( ------- out: array an array where every element is equal to ``fill_value``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -273,6 +282,9 @@ def full_like( ------- out: array an array having the same shape as ``x`` and where every element is equal to ``fill_value``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -340,6 +352,9 @@ def linspace( .. note:: As mixed data type promotion is implementation-defined, behavior when ``start`` or ``stop`` exceeds the maximum safe integer of an output floating-point data type is implementation-defined. An implementation may choose to overflow or raise an exception. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -367,6 +382,9 @@ def meshgrid(*arrays: array, indexing: str = "xy") -> List[array]: 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. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -395,6 +413,9 @@ def ones( ------- out: array an array containing ones. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -420,6 +441,9 @@ def ones_like( ------- out: array an array having the same shape as ``x`` and filled with ones. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 0f557852b..69ccce49b 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -36,6 +36,9 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: ------- out: array an array having the specified data type. The returned array must have the same shape as ``x``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -97,6 +100,9 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: - **dtype**: dtype real-valued floating-point data type. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 6b2a46e24..1e738795b 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -52,6 +52,9 @@ def abs(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN``. - If ``a`` is a finite number and ``b`` is ``NaN``, the result is ``NaN``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -118,6 +121,9 @@ def acos(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``NaN - infinity j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -189,6 +195,9 @@ def acosh(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``+infinity + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -254,6 +263,9 @@ def add(x1: array, x2: array, /) -> array: - Similarly, if ``b`` is ``+0`` and ``d`` is ``-0``, the imaginary component of the result is ``+0``. Hence, if ``z1 = a + bj = -0 + 0j`` and ``z2 = c + dj = -0 - 0j``, the result of ``z1 + z2`` is ``-0 + 0j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -308,6 +320,9 @@ def asin(x: array, /) -> array: - 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)``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -370,6 +385,9 @@ def asinh(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a nonzero finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``±infinity + NaN j`` (sign of the real component is unspecified). - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -419,6 +437,9 @@ def atan(x: array, /) -> array: - 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)``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -541,6 +562,9 @@ def atanh(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``±0 + πj/2`` (sign of the real component is unspecified). - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -753,6 +777,9 @@ def cos(x: array, /) -> array: - 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)``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -813,6 +840,9 @@ def cosh(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. where ``cis(v)`` is ``cos(v) + sin(v)*1j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -893,6 +923,9 @@ def divide(x1: array, x2: array, /) -> array: .. note:: For complex floating-point operands, the results of special cases may be implementation dependent depending on how an implementation chooses to model complex numbers and complex infinity (e.g., complex plane versus Riemann sphere). For those implementations following C99 and its one-infinity model, when at least one component is infinite, even if the other component is ``NaN``, the complex value is infinite, and the usual arithmetic rules do not apply to complex-complex division. In the interest of performance, other implementations may want to avoid the complex branching logic necessary to implement the one-infinity model and choose to implement all complex-complex division according to the textbook formula. Accordingly, special case behavior is unlikely to be consistent across implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -934,6 +967,9 @@ def equal(x1: array, x2: array, /) -> array: .. note:: For discussion of complex number equality, see :ref:`complex-numbers`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -987,6 +1023,9 @@ def exp(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. where ``cis(v)`` is ``cos(v) + sin(v)*1j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1043,6 +1082,9 @@ def expm1(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. where ``cis(v)`` is ``cos(v) + sin(v)*1j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1226,6 +1268,9 @@ def isfinite(x: array, /) -> array: - If ``a`` is either ``+infinity`` or ``-infinity`` and ``b`` is any value, the result is ``False``. - If ``a`` is any value and ``b`` is either ``+infinity`` or ``-infinity``, the result is ``False``. - If ``a`` is a finite number and ``b`` is a finite number, the result is ``True``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1258,6 +1303,9 @@ def isinf(x: array, /) -> array: - If ``a`` is either ``+infinity`` or ``-infinity`` and ``b`` is any value (including ``NaN``), the result is ``True``. - If ``a`` is either a finite number or ``NaN`` and ``b`` is either ``+infinity`` or ``-infinity``, the result is ``True``. - In the remaining cases, the result is ``False``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1289,6 +1337,9 @@ def isnan(x: array, /) -> array: - If ``a`` or ``b`` is ``NaN``, the result is ``True``. - In the remaining cases, the result is ``False``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1390,6 +1441,9 @@ def log(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``+infinity + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1449,6 +1503,9 @@ def log1p(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``+infinity + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1488,6 +1545,9 @@ def log2(x: array, /) -> array: \log_{2} x = \frac{\log_{e} x}{\log_{e} 2} where :math:`\log_{e}` is the natural logarithm, as implemented by :func:`~array_api.log`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1527,6 +1587,9 @@ def log10(x: array, /) -> array: \log_{10} x = \frac{\log_{e} x}{\log_{e} 10} where :math:`\log_{e}` is the natural logarithm, as implemented by :func:`~array_api.log`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1703,6 +1766,9 @@ def multiply(x1: array, x2: array, /) -> array: .. note:: For complex floating-point operands, the results of special cases may be implementation dependent depending on how an implementation chooses to model complex numbers and complex infinity (e.g., complex plane versus Riemann sphere). For those implementations following C99 and its one-infinity model, when at least one component is infinite, even if the other component is ``NaN``, the complex value is infinite, and the usual arithmetic rules do not apply to complex-complex multiplication. In the interest of performance, other implementations may want to avoid the complex branching logic necessary to implement the one-infinity model and choose to implement all complex-complex multiplication according to the textbook formula. Accordingly, special case behavior is unlikely to be consistent across implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1725,6 +1791,9 @@ def negative(x: array, /) -> array: ------- 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1764,6 +1833,9 @@ def not_equal(x1: array, x2: array, /) -> array: .. note:: For discussion of complex number equality, see :ref:`complex-numbers`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1780,6 +1852,9 @@ def positive(x: array, /) -> array: ------- out: array an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1847,6 +1922,9 @@ def pow(x1: array, x2: array, /) -> array: .. note:: Conforming implementations are allowed to treat special cases involving complex floating-point operands more carefully than as described in this specification. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -1958,6 +2036,9 @@ def round(x: array, /) -> array: - If ``x_i`` is ``-0``, the result is ``-0``. - If ``x_i`` is ``NaN``, the result is ``NaN``. - If two integers are equally close to ``x_i``, the result is the even integer closest to ``x_i``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2002,6 +2083,9 @@ 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`). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2045,6 +2129,9 @@ def sin(x: array, /) -> array: - 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)``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2105,6 +2192,9 @@ def sinh(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. where ``cis(v)`` is ``cos(v) + sin(v)*1j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2133,6 +2223,9 @@ def square(x: array, /) -> array: **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`). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2189,6 +2282,9 @@ def sqrt(x: array, /) -> array: - If ``a`` is ``+infinity`` and ``b`` is ``NaN``, the result is ``+infinity + NaN j``. - If ``a`` is ``NaN`` and ``b`` is any value, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2209,6 +2305,9 @@ def subtract(x1: array, x2: array, /) -> array: ------- out: array an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2252,6 +2351,9 @@ def tan(x: array, /) -> array: - 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)``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -2316,6 +2418,9 @@ def tanh(x: array, /) -> array: For historical reasons stemming from the C standard, array libraries may not return the expected result when ``a`` is ``+0`` and ``b`` is either ``+infinity`` or ``NaN``. The result should be ``+0 + NaN j`` in both cases; however, for libraries compiled against older C versions, the result may be ``NaN + NaN j``. Array libraries are not required to patch these older C versions, and, thus, users are advised that results may vary across array library implementations for these special cases. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index b040251dd..cc1e8477f 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -38,6 +38,9 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: ------- 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -71,6 +74,12 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: - if provided an invalid ``axis``. - if the size of the axis over which to compute the cross product is not equal to ``3``. - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. + + .. versionchanged:: 2022.12 + Added support for broadcasting. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -87,6 +96,9 @@ def det(x: array, /) -> array: ------- 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -157,6 +169,9 @@ def eigh(x: array, /) -> Tuple[array]: .. note:: Eigenvalue sort order is left unspecified and is thus implementation-dependent. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -195,6 +210,9 @@ def eigvalsh(x: array, /) -> array: .. note:: Eigenvalue sort order is left unspecified and is thus implementation-dependent. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -224,6 +242,9 @@ def inv(x: array, /) -> array: ------- 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -288,6 +309,9 @@ def matrix_norm( ------- 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). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -306,6 +330,9 @@ def matrix_power(x: array, n: int, /) -> array: ------- 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -326,6 +353,9 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a ------- 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]``). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -348,6 +378,9 @@ def outer(x1: array, x2: array, /) -> array: ------- 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -382,6 +415,9 @@ def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: ------- 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). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -441,6 +477,9 @@ def qr( - 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -490,6 +529,9 @@ def slogdet(x: array, /) -> Tuple[array, array]: - 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]``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -522,6 +564,9 @@ def solve(x1: array, x2: array, /) -> array: ------- out: array an array containing the solution to the system ``AX = B`` for each square matrix. The returned array must have the same shape as ``x2`` (i.e., the array corresponding to ``B``) and must have a floating-point data type determined by :ref:`type-promotion`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -571,6 +616,9 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, - 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -589,6 +637,9 @@ def svdvals(x: array, /) -> array: ------- 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). + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -653,6 +704,9 @@ 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -716,6 +770,9 @@ def vector_norm( ------- 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). + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/linear_algebra_functions.py b/src/array_api_stubs/_draft/linear_algebra_functions.py index c8b6e50f8..7e153dcac 100644 --- a/src/array_api_stubs/_draft/linear_algebra_functions.py +++ b/src/array_api_stubs/_draft/linear_algebra_functions.py @@ -40,6 +40,9 @@ def matmul(x1: array, x2: array, /) -> array: - if ``x1`` is a one-dimensional array having shape ``(K,)``, ``x2`` is an array having shape ``(..., L, N)``, and ``K != L``. - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is an array having shape ``(..., L, N)``, and ``K != L``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -101,6 +104,9 @@ def tensordot( ------- 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -138,6 +144,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: - if provided an invalid ``axis``. - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/searching_functions.py b/src/array_api_stubs/_draft/searching_functions.py index 9393ba71e..5ff2acf6c 100644 --- a/src/array_api_stubs/_draft/searching_functions.py +++ b/src/array_api_stubs/_draft/searching_functions.py @@ -75,6 +75,9 @@ def nonzero(x: array, /) -> Tuple[array, ...]: ------- out: Typle[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. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index dc95f58e8..07e8f5490 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -38,6 +38,9 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -74,6 +77,9 @@ def unique_counts(x: array, /) -> Tuple[array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -110,6 +116,9 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -141,6 +150,9 @@ def unique_values(x: array, /) -> array: .. note:: The order of unique elements is not specified and may vary between implementations. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 787faeeb9..93faaf31e 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -171,6 +171,9 @@ 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -265,6 +268,9 @@ 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`. + + .. versionchanged:: 2022.12 + Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py index e70fe8aa6..be0edffc1 100644 --- a/src/array_api_stubs/_draft/utility_functions.py +++ b/src/array_api_stubs/_draft/utility_functions.py @@ -33,6 +33,9 @@ def all( ------- 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ @@ -68,6 +71,9 @@ def any( ------- 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``. + + .. versionchanged:: 2022.12 + Added complex data type support. """ From 9f9683bbb01b9f1bea7abb7ad6caede007330450 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 25 Jan 2023 18:55:12 -0500 Subject: [PATCH 2/5] Add version added to functions created in 2022 --- src/array_api_stubs/_draft/__init__.py | 2 ++ src/array_api_stubs/_draft/array_object.py | 2 ++ .../_draft/data_type_functions.py | 6 ++++ .../_draft/elementwise_functions.py | 6 ++++ src/array_api_stubs/_draft/fft.py | 28 +++++++++++++++++++ .../_draft/indexing_functions.py | 2 ++ 6 files changed, 46 insertions(+) diff --git a/src/array_api_stubs/_draft/__init__.py b/src/array_api_stubs/_draft/__init__.py index 12b6d9fbb..7acf742a3 100644 --- a/src/array_api_stubs/_draft/__init__.py +++ b/src/array_api_stubs/_draft/__init__.py @@ -21,4 +21,6 @@ __array_api_version__: str = "YYYY.MM" """ String representing the version of the array API specification which the conforming implementation adheres to. + +.. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 6e1d282ce..d00e484b3 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -269,6 +269,8 @@ def __complex__(self: array, /) -> complex: - If ``self`` is ``+infinity``, the result is ``+infinity + 0j``. - If ``self`` is ``-infinity``, the result is ``-infinity + 0j``. - If ``self`` is a finite number, the result is ``self + 0j``. + + .. versionadded:: 2022.12 """ def __dlpack__( diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 69ccce49b..ff3a7c343 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -101,6 +101,8 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: real-valued floating-point data type. + .. versionadded:: 2022.12 + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -135,6 +137,8 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: - **dtype**: dtype integer data type. + + .. versionadded:: 2022.12 """ @@ -173,6 +177,8 @@ def isdtype( ------- out: bool boolean indicating whether a provided dtype is of a specified data type kind. + + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 1e738795b..8282284c8 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -733,6 +733,8 @@ def conj(x: array, /) -> array: ------- out: array an array containing the element-wise results. The returned array must have the same data type as ``x``. + + .. versionadded:: 2022.12 """ @@ -1234,6 +1236,8 @@ def imag(x: array, /) -> array: ------- 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``). + + .. versionadded:: 2022.12 """ @@ -1941,6 +1945,8 @@ def real(x: array, /) -> array: ------- 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``). + + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 2eb428b0c..ee3a5f209 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -44,6 +44,8 @@ def fft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -90,6 +92,8 @@ def ifft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -143,6 +147,8 @@ def fftn( ------- out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -196,6 +202,8 @@ def ifftn( ------- out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -242,6 +250,8 @@ def rfft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -288,6 +298,8 @@ def irfft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). + + .. versionadded:: 2022.12 """ @@ -341,6 +353,8 @@ def rfftn( ------- out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -394,6 +408,8 @@ def irfftn( ------- out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. + + .. versionadded:: 2022.12 """ @@ -437,6 +453,8 @@ def hfft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -480,6 +498,8 @@ def ihfft( ------- out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -507,6 +527,8 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar ------- out: array an array of length ``n`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -536,6 +558,8 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a ------- out: array an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + + .. versionadded:: 2022.12 """ @@ -559,6 +583,8 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ------- out: array the shifted array. The returned array must have the same data type as ``x``. + + .. versionadded:: 2022.12 """ @@ -580,6 +606,8 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ------- out: array the shifted array. The returned array must have the same data type as ``x``. + + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py index e76ce7484..f6a67c290 100644 --- a/src/array_api_stubs/_draft/indexing_functions.py +++ b/src/array_api_stubs/_draft/indexing_functions.py @@ -23,6 +23,8 @@ def take(x: array, indices: array, /, *, axis: int) -> array: ------- 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``. + + .. versionadded:: 2022.12 """ From 4b57941a8c9c4dc04971b78d6d8515a8ad4b0147 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 26 Jan 2023 11:40:00 -0500 Subject: [PATCH 3/5] Add missing notes section --- src/array_api_stubs/_draft/__init__.py | 2 - src/array_api_stubs/_draft/array_object.py | 24 +++++++++ .../_draft/data_type_functions.py | 9 ++++ .../_draft/elementwise_functions.py | 18 +++++++ src/array_api_stubs/_draft/fft.py | 42 +++++++++++++++ .../_draft/indexing_functions.py | 3 ++ src/array_api_stubs/_draft/linalg.py | 52 ++++++++++++++++++- .../_draft/linear_algebra_functions.py | 17 ++++-- .../_draft/searching_functions.py | 3 ++ src/array_api_stubs/_draft/set_functions.py | 12 +++++ .../_draft/utility_functions.py | 6 +++ 11 files changed, 181 insertions(+), 7 deletions(-) diff --git a/src/array_api_stubs/_draft/__init__.py b/src/array_api_stubs/_draft/__init__.py index 7acf742a3..12b6d9fbb 100644 --- a/src/array_api_stubs/_draft/__init__.py +++ b/src/array_api_stubs/_draft/__init__.py @@ -21,6 +21,4 @@ __array_api_version__: str = "YYYY.MM" """ String representing the version of the array API specification which the conforming implementation adheres to. - -.. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index d00e484b3..e45361710 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -139,6 +139,8 @@ def __abs__(self: array, /) -> array: .. note:: Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.abs`. + Notes + ----- .. versionchanged:: 2022.12 Added complex data type support. @@ -160,6 +162,8 @@ def __add__(self: array, other: Union[int, float, array], /) -> array: out: array 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`. @@ -337,6 +341,9 @@ def __dlpack__( errors are raised when export fails for other reasons (e.g., incorrect arguments passed or out of memory). + Notes + ----- + .. versionchanged:: 2022.12 Added BufferError. """ @@ -690,6 +697,8 @@ def __matmul__(self: array, other: array, /) -> array: - 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`. + Notes + ----- .. note:: Results must equal the results returned by the equivalent function :func:`~array_api.matmul`. @@ -749,6 +758,8 @@ def __mul__(self: array, other: Union[int, float, array], /) -> array: out: array 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`. @@ -774,6 +785,9 @@ def __ne__(self: array, other: Union[int, float, bool, array], /) -> 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 + ----- + .. note:: Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.not_equal`. @@ -801,6 +815,8 @@ def __neg__(self: array, /) -> array: 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`. + Notes + ----- .. note:: Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.negative`. @@ -844,6 +860,8 @@ def __pos__(self: array, /) -> array: out: array 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`. @@ -873,6 +891,8 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array: out: array 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`. @@ -950,6 +970,8 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array: out: array 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`. @@ -979,6 +1001,8 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: out: array 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`. diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index ff3a7c343..571871f6d 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -37,6 +37,9 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: out: array an array having the specified data type. The returned array must have the same shape as ``x``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -103,6 +106,9 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: .. versionadded:: 2022.12 + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -178,6 +184,9 @@ def isdtype( out: bool boolean indicating whether a provided dtype is of a specified data type kind. + Notes + ----- + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 8282284c8..74ef7e98d 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -734,6 +734,9 @@ def conj(x: array, /) -> array: out: array an array containing the element-wise results. The returned array must have the same data type as ``x``. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -1237,6 +1240,9 @@ def imag(x: array, /) -> array: 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``). + Notes + ----- + .. versionadded:: 2022.12 """ @@ -1796,6 +1802,9 @@ def negative(x: array, /) -> array: 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`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -1857,6 +1866,9 @@ def positive(x: array, /) -> array: out: array an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -1946,6 +1958,9 @@ def real(x: array, /) -> array: 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``). + Notes + ----- + .. versionadded:: 2022.12 """ @@ -2312,6 +2327,9 @@ def subtract(x1: array, x2: array, /) -> array: out: array an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index ee3a5f209..7979095fe 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -45,6 +45,9 @@ def fft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -93,6 +96,9 @@ def ifft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -148,6 +154,9 @@ def fftn( out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -203,6 +212,9 @@ def ifftn( out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -251,6 +263,9 @@ def rfft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -299,6 +314,9 @@ def irfft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). + Notes + ----- + .. versionadded:: 2022.12 """ @@ -354,6 +372,9 @@ def rfftn( out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -409,6 +430,9 @@ def irfftn( out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -454,6 +478,9 @@ def hfft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -499,6 +526,9 @@ def ihfft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -528,6 +558,9 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar out: array an array of length ``n`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -559,6 +592,9 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a out: array an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -584,6 +620,9 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: out: array the shifted array. The returned array must have the same data type as ``x``. + Notes + ----- + .. versionadded:: 2022.12 """ @@ -607,6 +646,9 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: out: array the shifted array. The returned array must have the same data type as ``x``. + Notes + ----- + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py index f6a67c290..d57dc91e5 100644 --- a/src/array_api_stubs/_draft/indexing_functions.py +++ b/src/array_api_stubs/_draft/indexing_functions.py @@ -24,6 +24,9 @@ def take(x: array, indices: array, /, *, axis: int) -> array: 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``. + Notes + ----- + .. versionadded:: 2022.12 """ diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index cc1e8477f..f7427dfa4 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -39,6 +39,9 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: 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``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -69,12 +72,16 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion`. - **Raises** + Raises + ------ - if provided an invalid ``axis``. - if the size of the axis over which to compute the cross product is not equal to ``3``. - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. + Notes + ----- + .. versionchanged:: 2022.12 Added support for broadcasting. @@ -97,6 +104,9 @@ def det(x: array, /) -> array: 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``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -166,6 +176,8 @@ def eigh(x: array, /) -> Tuple[array]: - 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 + ----- .. note:: Eigenvalue sort order is left unspecified and is thus implementation-dependent. @@ -207,6 +219,8 @@ def eigvalsh(x: array, /) -> array: 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). + Notes + ----- .. note:: Eigenvalue sort order is left unspecified and is thus implementation-dependent. @@ -243,6 +257,9 @@ def inv(x: array, /) -> array: 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``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -310,6 +327,9 @@ def matrix_norm( 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). + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -331,6 +351,9 @@ def matrix_power(x: array, n: int, /) -> array: 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`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -354,6 +377,9 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a 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]``). + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -379,6 +405,9 @@ def outer(x1: array, x2: array, /) -> array: 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`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -416,6 +445,9 @@ def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: 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). + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -478,6 +510,9 @@ def qr( Each returned array must have a floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -530,6 +565,9 @@ def slogdet(x: array, /) -> Tuple[array, array]: Each returned array must have shape ``shape(x)[:-2]``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -565,6 +603,9 @@ def solve(x1: array, x2: array, /) -> array: out: array an array containing the solution to the system ``AX = B`` for each square matrix. The returned array must have the same shape as ``x2`` (i.e., the array corresponding to ``B``) and must have a floating-point data type determined by :ref:`type-promotion`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -617,6 +658,9 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, - second element must have the field name ``S`` and must be an array with shape ``(..., K)`` that contains the vector(s) of singular values of length ``K``, where ``K = min(M, N)``. For each vector, the singular values must be sorted in descending order by magnitude, such that ``s[..., 0]`` is the largest value, ``s[..., 1]`` is the second largest value, et cetera. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x``. 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 + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -638,6 +682,9 @@ def svdvals(x: array, /) -> array: 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). + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -771,6 +818,9 @@ def vector_norm( 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). + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/linear_algebra_functions.py b/src/array_api_stubs/_draft/linear_algebra_functions.py index 7e153dcac..42c24c59a 100644 --- a/src/array_api_stubs/_draft/linear_algebra_functions.py +++ b/src/array_api_stubs/_draft/linear_algebra_functions.py @@ -32,8 +32,8 @@ def matmul(x1: array, x2: array, /) -> array: The returned array must have a data type determined by :ref:`type-promotion`. - - **Raises** + Raises + ------ - if either ``x1`` or ``x2`` is a zero-dimensional array. - if ``x1`` is a one-dimensional array having shape ``(K,)``, ``x2`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. @@ -41,6 +41,9 @@ def matmul(x1: array, x2: array, /) -> array: - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is an array having shape ``(..., L, N)``, and ``K != L``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -105,6 +108,9 @@ def tensordot( 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`. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -139,12 +145,15 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: 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`. - - **Raises** + Raises + ------ - if provided an invalid ``axis``. - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/searching_functions.py b/src/array_api_stubs/_draft/searching_functions.py index 5ff2acf6c..9dcc0f95c 100644 --- a/src/array_api_stubs/_draft/searching_functions.py +++ b/src/array_api_stubs/_draft/searching_functions.py @@ -76,6 +76,9 @@ def nonzero(x: array, /) -> Tuple[array, ...]: out: Typle[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. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 07e8f5490..661d3df90 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -39,6 +39,9 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -78,6 +81,9 @@ def unique_counts(x: array, /) -> Tuple[array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -117,6 +123,9 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: .. note:: The order of unique elements is not specified and may vary between implementations. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -151,6 +160,9 @@ def unique_values(x: array, /) -> array: .. note:: The order of unique elements is not specified and may vary between implementations. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py index be0edffc1..64e5de297 100644 --- a/src/array_api_stubs/_draft/utility_functions.py +++ b/src/array_api_stubs/_draft/utility_functions.py @@ -34,6 +34,9 @@ def all( 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``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -72,6 +75,9 @@ def any( 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``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ From 501e5ed4b45afbcb8359d17e8996c0ca12944c8d Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 26 Jan 2023 11:59:11 -0500 Subject: [PATCH 4/5] Fix notes section rendering for some functions --- src/array_api_stubs/_draft/array_object.py | 6 ++--- .../_draft/creation_functions.py | 23 +++++++++++++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index e45361710..cf6adcf3c 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -136,12 +136,12 @@ def __abs__(self: array, /) -> array: 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). - .. note:: - Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.abs`. - Notes ----- + .. note:: + 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. """ diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 8949c104c..8736efc29 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -98,6 +98,9 @@ def asarray( out: array an array containing the data from ``obj``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -183,6 +186,9 @@ def eye( out: array an array where all elements are equal to zero, except for the ``k``\th diagonal, whose values are equal to one. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -244,6 +250,9 @@ def full( out: array an array where every element is equal to ``fill_value``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -283,6 +292,9 @@ def full_like( out: array an array having the same shape as ``x`` and where every element is equal to ``fill_value``. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -346,6 +358,8 @@ def linspace( out: array a one-dimensional array containing evenly spaced values. + Notes + ----- .. note:: While this specification recommends that this function only return arrays having a floating-point data type, specification-compliant array libraries may choose to support output arrays having an integer data type (e.g., due to backward compatibility concerns). However, function behavior when generating integer output arrays is unspecified and, thus, is implementation-defined. Accordingly, using this function to generate integer output arrays is not portable. @@ -383,6 +397,9 @@ def meshgrid(*arrays: array, indexing: str = "xy") -> List[array]: Each returned array should have the same data type as the input arrays. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -414,6 +431,9 @@ def ones( out: array an array containing ones. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ @@ -442,6 +462,9 @@ def ones_like( out: array an array having the same shape as ``x`` and filled with ones. + Notes + ----- + .. versionchanged:: 2022.12 Added complex data type support. """ From 6d01fd0d876d98b1337e22f5aed0d27c7575f1ad Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 1 Feb 2023 09:39:21 +0000 Subject: [PATCH 5/5] Fix Raises sections which caused rendering issues --- src/array_api_stubs/_draft/linalg.py | 12 ++++------ .../_draft/linear_algebra_functions.py | 24 +++++++++---------- 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index f7427dfa4..20d1d54ff 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -72,13 +72,6 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion`. - Raises - ------ - - - if provided an invalid ``axis``. - - if the size of the axis over which to compute the cross product is not equal to ``3``. - - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. - Notes ----- @@ -87,6 +80,11 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: .. versionchanged:: 2022.12 Added complex data type support. + + **Raises** + + - if the size of the axis over which to compute the cross product is not equal to ``3``. + - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. """ diff --git a/src/array_api_stubs/_draft/linear_algebra_functions.py b/src/array_api_stubs/_draft/linear_algebra_functions.py index 42c24c59a..9d949c067 100644 --- a/src/array_api_stubs/_draft/linear_algebra_functions.py +++ b/src/array_api_stubs/_draft/linear_algebra_functions.py @@ -32,8 +32,13 @@ def matmul(x1: array, x2: array, /) -> array: The returned array must have a data type determined by :ref:`type-promotion`. - Raises - ------ + Notes + ----- + + .. versionchanged:: 2022.12 + Added complex data type support. + + **Raises** - if either ``x1`` or ``x2`` is a zero-dimensional array. - if ``x1`` is a one-dimensional array having shape ``(K,)``, ``x2`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. @@ -41,11 +46,6 @@ def matmul(x1: array, x2: array, /) -> array: - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is a one-dimensional array having shape ``(L,)``, and ``K != L``. - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is an array having shape ``(..., L, N)``, and ``K != L``. - Notes - ----- - - .. versionchanged:: 2022.12 - Added complex data type support. """ @@ -145,17 +145,15 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: 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`. - Raises - ------ - - - if provided an invalid ``axis``. - - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. - Notes ----- .. versionchanged:: 2022.12 Added complex data type support. + + **Raises** + + - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. """