From 162034b12711dad54589c5dc9e75942695a7957f Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 14 Dec 2022 22:59:49 +0100 Subject: [PATCH 1/3] Run `black` on the `.py` files for the API specification --- spec/API_specification/array_api/_types.py | 59 +++++-- .../array_api/array_object.py | 65 ++++++-- spec/API_specification/array_api/constants.py | 6 +- .../array_api/creation_functions.py | 151 +++++++++++++++--- .../array_api/data_type_functions.py | 15 +- .../API_specification/array_api/data_types.py | 4 +- .../array_api/elementwise_functions.py | 151 ++++++++++++++++-- spec/API_specification/array_api/fft.py | 107 +++++++++++-- .../array_api/indexing_functions.py | 4 +- spec/API_specification/array_api/linalg.py | 79 ++++++++- .../array_api/linear_algebra_functions.py | 21 ++- .../array_api/manipulation_functions.py | 40 ++++- .../array_api/searching_functions.py | 7 +- .../array_api/set_functions.py | 7 +- .../array_api/sorting_functions.py | 13 +- .../array_api/statistical_functions.py | 70 +++++++- .../array_api/utility_functions.py | 21 ++- 17 files changed, 705 insertions(+), 115 deletions(-) diff --git a/spec/API_specification/array_api/_types.py b/spec/API_specification/array_api/_types.py index b55e8fb25..be81b40ae 100644 --- a/spec/API_specification/array_api/_types.py +++ b/spec/API_specification/array_api/_types.py @@ -7,18 +7,29 @@ from __future__ import annotations from dataclasses import dataclass -from typing import Any, List, Literal, Optional, Sequence, Tuple, TypeVar, Union, Protocol +from typing import ( + Any, + List, + Literal, + Optional, + Sequence, + Tuple, + TypeVar, + Union, + Protocol, +) from enum import Enum -array = TypeVar('array') -device = TypeVar('device') -dtype = TypeVar('dtype') -SupportsDLPack = TypeVar('SupportsDLPack') -SupportsBufferProtocol = TypeVar('SupportsBufferProtocol') -PyCapsule = TypeVar('PyCapsule') +array = TypeVar("array") +device = TypeVar("device") +dtype = TypeVar("dtype") +SupportsDLPack = TypeVar("SupportsDLPack") +SupportsBufferProtocol = TypeVar("SupportsBufferProtocol") +PyCapsule = TypeVar("PyCapsule") # ellipsis cannot actually be imported from anywhere, so include a dummy here # to keep pyflakes happy. https://github.com/python/typeshed/issues/3556 -ellipsis = TypeVar('ellipsis') +ellipsis = TypeVar("ellipsis") + @dataclass class finfo_object: @@ -28,6 +39,7 @@ class finfo_object: min: float smallest_normal: float + @dataclass class iinfo_object: bits: int @@ -37,11 +49,32 @@ class iinfo_object: _T_co = TypeVar("_T_co", covariant=True) + class NestedSequence(Protocol[_T_co]): - def __getitem__(self, key: int, /) -> Union[_T_co, NestedSequence[_T_co]]: ... - def __len__(self, /) -> int: ... + def __getitem__(self, key: int, /) -> Union[_T_co, NestedSequence[_T_co]]: + ... + + def __len__(self, /) -> int: + ... -__all__ = ['Any', 'List', 'Literal', 'NestedSequence', 'Optional', -'PyCapsule', 'SupportsBufferProtocol', 'SupportsDLPack', 'Tuple', 'Union', 'Sequence', -'array', 'device', 'dtype', 'ellipsis', 'finfo_object', 'iinfo_object', 'Enum'] +__all__ = [ + "Any", + "List", + "Literal", + "NestedSequence", + "Optional", + "PyCapsule", + "SupportsBufferProtocol", + "SupportsDLPack", + "Tuple", + "Union", + "Sequence", + "array", + "device", + "dtype", + "ellipsis", + "finfo_object", + "iinfo_object", + "Enum", +] diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index f7cb3e133..3dee8c5ab 100644 --- a/spec/API_specification/array_api/array_object.py +++ b/spec/API_specification/array_api/array_object.py @@ -1,9 +1,20 @@ from __future__ import annotations -from ._types import (array, dtype as Dtype, device as Device, Optional, Tuple, - Union, Any, PyCapsule, Enum, ellipsis) - -class _array(): +from ._types import ( + array, + dtype as Dtype, + device as Device, + Optional, + Tuple, + Union, + Any, + PyCapsule, + Enum, + ellipsis, +) + + +class _array: def __init__(self: array) -> None: """ Initialize the attributes for the array object class. @@ -246,7 +257,9 @@ def __and__(self: array, other: Union[int, bool, array], /) -> array: Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_and`. """ - def __array_namespace__(self: array, /, *, api_version: Optional[str] = None) -> Any: + def __array_namespace__( + self: array, /, *, api_version: Optional[str] = None + ) -> Any: """ Returns an object that has all the array API functions on it. @@ -298,9 +311,9 @@ def __complex__(self: array, /) -> complex: - If ``self`` is ``True``, the result is ``1+0j``. - If ``self`` is ``False``, the result is ``0+0j``. - + For real-valued floating-point operands, - + - If ``self`` is ``NaN``, the result is ``NaN + NaN j``. - If ``self`` is ``+infinity``, the result is ``+infinity + 0j``. - If ``self`` is ``-infinity``, the result is ``-infinity + 0j``. @@ -317,7 +330,9 @@ def __complex__(self: array, /) -> complex: a Python ``complex`` object representing the single element of the array instance. """ - def __dlpack__(self: array, /, *, stream: Optional[Union[int, Any]] = None) -> PyCapsule: + def __dlpack__( + self: array, /, *, stream: Optional[Union[int, Any]] = None + ) -> PyCapsule: """ Exports the array for consumption by :func:`~array_api.from_dlpack` as a DLPack capsule. @@ -559,7 +574,13 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array: Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`. """ - def __getitem__(self: array, key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array], /) -> array: + def __getitem__( + self: array, + key: Union[ + int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array + ], + /, + ) -> array: """ Returns ``self[key]``. @@ -1099,7 +1120,14 @@ def __rshift__(self: array, other: Union[int, array], /) -> array: Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_right_shift`. """ - def __setitem__(self: array, key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array], value: Union[int, float, bool, array], /) -> None: + def __setitem__( + self: array, + key: Union[ + int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array + ], + value: Union[int, float, bool, array], + /, + ) -> None: """ Sets ``self[key]`` to ``value``. @@ -1196,17 +1224,17 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array: +------------+----------------+-----------------+--------------------------+ 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 - + .. math:: \frac{a + bj}{c + dj} = \frac{(ac + bd) + (bc - ad)j}{c^2 + d^2} - + When at least one of ``a``, ``b``, ``c``, or ``d`` is ``NaN``, ``+infinity``, or ``-infinity``, - + - If ``a``, ``b``, ``c``, and ``d`` are all ``NaN``, the result is ``NaN + NaN j``. - In the remaining cases, the result is implementation dependent. - + .. 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. @@ -1248,7 +1276,9 @@ def __xor__(self: array, other: Union[int, bool, array], /) -> array: Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_xor`. """ - def to_device(self: array, device: Device, /, *, stream: Optional[Union[int, Any]] = None) -> array: + def to_device( + self: array, device: Device, /, *, stream: Optional[Union[int, Any]] = None + ) -> array: """ Copy the array from the device on which it currently resides to the specified ``device``. @@ -1271,6 +1301,7 @@ def to_device(self: array, device: Device, /, *, stream: Optional[Union[int, Any If ``stream`` is given, 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 library's documentation. """ + array = _array -__all__ = ['array'] +__all__ = ["array"] diff --git a/spec/API_specification/array_api/constants.py b/spec/API_specification/array_api/constants.py index 18c8ac761..c7aaddc5e 100644 --- a/spec/API_specification/array_api/constants.py +++ b/spec/API_specification/array_api/constants.py @@ -5,12 +5,12 @@ ``e = 2.71828182845904523536028747135266249775724709369995...`` """ -inf = float('inf') +inf = float("inf") """ IEEE 754 floating-point representation of (positive) infinity. """ -nan = float('nan') +nan = float("nan") """ IEEE 754 floating-point representation of Not a Number (``NaN``). """ @@ -27,4 +27,4 @@ ``pi = 3.1415926535897932384626433...`` """ -__all__ = ['e', 'inf', 'nan', 'newaxis', 'pi'] +__all__ = ["e", "inf", "nan", "newaxis", "pi"] diff --git a/spec/API_specification/array_api/creation_functions.py b/spec/API_specification/array_api/creation_functions.py index 593b00150..bfb89b2ba 100644 --- a/spec/API_specification/array_api/creation_functions.py +++ b/spec/API_specification/array_api/creation_functions.py @@ -1,7 +1,25 @@ -from ._types import (List, NestedSequence, Optional, SupportsBufferProtocol, Tuple, Union, array, - device, dtype) - -def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None, step: Union[int, float] = 1, *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: +from ._types import ( + List, + NestedSequence, + Optional, + SupportsBufferProtocol, + Tuple, + Union, + array, + device, + dtype, +) + + +def arange( + start: Union[int, float], + /, + stop: Optional[Union[int, float]] = None, + step: Union[int, float] = 1, + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ Returns evenly spaced values within the half-open interval ``[start, stop)`` as a one-dimensional array. @@ -28,7 +46,17 @@ def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None 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. """ -def asarray(obj: Union[array, bool, int, float, complex, NestedSequence, SupportsBufferProtocol], /, *, dtype: Optional[dtype] = None, device: Optional[device] = None, copy: Optional[bool] = None) -> array: + +def asarray( + obj: Union[ + array, bool, int, float, complex, NestedSequence, SupportsBufferProtocol + ], + /, + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, + copy: Optional[bool] = None, +) -> array: r""" Convert the input to an array. @@ -71,7 +99,13 @@ def asarray(obj: Union[array, bool, int, float, complex, NestedSequence, Support an array containing the data from ``obj``. """ -def empty(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def empty( + shape: Union[int, Tuple[int, ...]], + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ Returns an uninitialized array having a specified `shape`. @@ -90,7 +124,10 @@ def empty(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, an array containing uninitialized data. """ -def empty_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def empty_like( + x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None +) -> array: """ Returns an uninitialized array with the same ``shape`` as an input array ``x``. @@ -109,12 +146,21 @@ def empty_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[d an array having the same shape as ``x`` and containing uninitialized data. """ -def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def eye( + n_rows: int, + n_cols: Optional[int] = None, + /, + *, + k: int = 0, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ 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 ---------- @@ -135,6 +181,7 @@ def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Opti an array where all elements are equal to zero, except for the ``k``\th diagonal, whose values are equal to one. """ + def from_dlpack(x: object, /) -> array: """ Returns a new array containing the data from another (array) object with a ``__dlpack__`` method. @@ -155,7 +202,14 @@ def from_dlpack(x: object, /) -> array: The returned array may be either a copy or a view. See :ref:`data-interchange` for details. """ -def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[bool, int, float, complex], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def full( + shape: Union[int, Tuple[int, ...]], + fill_value: Union[bool, int, float, complex], + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ Returns a new array having a specified ``shape`` and filled with ``fill_value``. @@ -185,7 +239,15 @@ def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[bool, int, float, an array where every element is equal to ``fill_value``. """ -def full_like(x: array, /, fill_value: Union[bool, int, float, complex], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def full_like( + x: array, + /, + fill_value: Union[bool, int, float, complex], + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ Returns a new array filled with ``fill_value`` and having the same ``shape`` as an input array ``x``. @@ -213,7 +275,17 @@ def full_like(x: array, /, fill_value: Union[bool, int, float, complex], *, dtyp an array having the same shape as ``x`` and where every element is equal to ``fill_value``. """ -def linspace(start: Union[int, float, complex], stop: Union[int, float, complex], /, num: int, *, dtype: Optional[dtype] = None, device: Optional[device] = None, endpoint: bool = True) -> array: + +def linspace( + start: Union[int, float, complex], + stop: Union[int, float, complex], + /, + num: int, + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, + endpoint: bool = True, +) -> array: r""" Returns evenly spaced numbers over a specified interval. @@ -270,7 +342,8 @@ def linspace(start: Union[int, float, complex], stop: Union[int, float, complex] 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. """ -def meshgrid(*arrays: array, indexing: str = 'xy') -> List[array]: + +def meshgrid(*arrays: array, indexing: str = "xy") -> List[array]: """ Returns coordinate matrices from coordinate vectors. @@ -296,12 +369,18 @@ def meshgrid(*arrays: array, indexing: str = 'xy') -> List[array]: Each returned array should have the same data type as the input arrays. """ -def ones(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def ones( + shape: Union[int, Tuple[int, ...]], + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ 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 ---------- @@ -318,12 +397,15 @@ def ones(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, d an array containing ones. """ -def ones_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def ones_like( + x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None +) -> array: """ 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 ---------- @@ -340,6 +422,7 @@ def ones_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[de an array having the same shape as ``x`` and filled with ones. """ + def tril(x: array, /, *, k: int = 0) -> array: """ Returns the lower triangular part of a matrix (or a stack of matrices) ``x``. @@ -363,6 +446,7 @@ def tril(x: array, /, *, k: int = 0) -> 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``. """ + def triu(x: array, /, *, k: int = 0) -> array: """ Returns the upper triangular part of a matrix (or a stack of matrices) ``x``. @@ -386,7 +470,13 @@ def triu(x: array, /, *, k: int = 0) -> 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``. """ -def zeros(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def zeros( + shape: Union[int, Tuple[int, ...]], + *, + dtype: Optional[dtype] = None, + device: Optional[device] = None, +) -> array: """ Returns a new array having a specified ``shape`` and filled with zeros. @@ -405,7 +495,10 @@ def zeros(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, an array containing zeros. """ -def zeros_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array: + +def zeros_like( + x: array, /, *, dtype: Optional[dtype] = None, device: Optional[device] = None +) -> array: """ Returns a new array filled with zeros and having the same ``shape`` as an input array ``x``. @@ -424,4 +517,22 @@ def zeros_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[d an array having the same shape as ``x`` and filled with zeros. """ -__all__ = ['arange', 'asarray', 'empty', 'empty_like', 'eye', 'from_dlpack', 'full', 'full_like', 'linspace', 'meshgrid', 'ones', 'ones_like', 'tril', 'triu', 'zeros', 'zeros_like'] + +__all__ = [ + "arange", + "asarray", + "empty", + "empty_like", + "eye", + "from_dlpack", + "full", + "full_like", + "linspace", + "meshgrid", + "ones", + "ones_like", + "tril", + "triu", + "zeros", + "zeros_like", +] diff --git a/spec/API_specification/array_api/data_type_functions.py b/spec/API_specification/array_api/data_type_functions.py index 6b1b242ae..0f557852b 100644 --- a/spec/API_specification/array_api/data_type_functions.py +++ b/spec/API_specification/array_api/data_type_functions.py @@ -1,5 +1,6 @@ from ._types import Union, Tuple, array, dtype, finfo_object, iinfo_object + def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: """ Copies an array to a specified data type irrespective of :ref:`type-promotion` rules. @@ -37,6 +38,7 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: an array having the specified data type. The returned array must have the same shape as ``x``. """ + def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: """ Determines if one data type can be cast to another data type according :ref:`type-promotion` rules. @@ -54,6 +56,7 @@ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: ``True`` if the cast can occur according to :ref:`type-promotion` rules; otherwise, ``False``. """ + def finfo(type: Union[dtype, array], /) -> finfo_object: """ Machine limits for floating-point data types. @@ -96,6 +99,7 @@ def finfo(type: Union[dtype, array], /) -> finfo_object: real-valued floating-point data type. """ + def iinfo(type: Union[dtype, array], /) -> iinfo_object: """ Machine limits for integer data types. @@ -127,7 +131,10 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object: integer data type. """ -def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]]) -> bool: + +def isdtype( + dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] +) -> bool: """ Returns a boolean indicating whether a provided dtype is of a specified data type "kind". @@ -142,7 +149,7 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] - 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``). + - **signed integer**: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). - **unsigned integer**: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). - **integral**: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. - **real floating**: real-valued floating-point data types (e.g., ``float32``, ``float64``). @@ -162,6 +169,7 @@ def isdtype(dtype: dtype, kind: Union[dtype, str, Tuple[Union[dtype, str], ...]] boolean indicating whether a provided dtype is of a specified data type kind. """ + def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: """ Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. @@ -180,4 +188,5 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: the dtype resulting from an operation involving the input arrays and dtypes. """ -__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'isdtype', 'result_type'] + +__all__ = ["astype", "can_cast", "finfo", "iinfo", "isdtype", "result_type"] diff --git a/spec/API_specification/array_api/data_types.py b/spec/API_specification/array_api/data_types.py index a86c9ebe6..614807414 100644 --- a/spec/API_specification/array_api/data_types.py +++ b/spec/API_specification/array_api/data_types.py @@ -1,5 +1,6 @@ from ._types import dtype + def __eq__(self: dtype, other: dtype, /) -> bool: """ Computes the truth value of ``self == other`` in order to test for data type object equality. @@ -17,4 +18,5 @@ def __eq__(self: dtype, other: dtype, /) -> bool: a boolean indicating whether the data type objects are equal. """ -__all__ = ['__eq__'] + +__all__ = ["__eq__"] diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index b97c13c71..3a3743ba8 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -1,5 +1,6 @@ from ._types import array + def abs(x: array, /) -> array: r""" Calculates the absolute value for each element ``x_i`` of the input array ``x``. @@ -50,6 +51,7 @@ def abs(x: array, /) -> 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 arrayed 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). """ + def acos(x: array, /) -> array: r""" Calculates an implementation-dependent approximation of the principal value of the inverse cosine for each element ``x_i`` of the input array ``x``. @@ -81,7 +83,7 @@ def acos(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. .. note:: - The principal value of the arc cosine of a complex number :math:`z` is + The principal value of the arc cosine of a complex number :math:`z` is .. math:: \operatorname{acos}(z) = \frac{1}{2}\pi + j\ \ln(zj + \sqrt{1-z^2}) @@ -99,7 +101,7 @@ def acos(x: array, /) -> array: Accordingly, for complex arguments, the function returns the inverse cosine in the range of a strip unbounded along the imaginary axis and in the interval :math:`[0, \pi]` along the real axis. - *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). + *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). Parameters ---------- @@ -112,6 +114,7 @@ def acos(x: array, /) -> 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`. """ + def acosh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the inverse hyperbolic cosine for each element ``x_i`` of the input array ``x``. @@ -179,6 +182,7 @@ def acosh(x: array, /) -> 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`. """ + def add(x1: array, x2: array, /) -> array: """ Calculates the sum for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -240,6 +244,7 @@ def add(x1: array, x2: array, /) -> array: an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`. """ + def asin(x: array, /) -> array: r""" Calculates an implementation-dependent approximation of the principal value of the inverse sine for each element ``x_i`` of the input array ``x``. @@ -267,7 +272,7 @@ def asin(x: array, /) -> array: For any :math:`z`, .. math:: - \operatorname{asin}(z) = \operatorname{acos}(-z) - \frac{\pi}{2} + \operatorname{asin}(z) = \operatorname{acos}(-z) - \frac{\pi}{2} .. note:: For complex floating-point operands, ``asin(conj(x))`` must equal ``conj(asin(x))``. @@ -277,7 +282,7 @@ def asin(x: array, /) -> array: Accordingly, for complex arguments, the function returns the inverse sine in the range of a strip unbounded along the imaginary axis and in the interval :math:`[-\pi/2, +\pi/2]` along the real axis. - *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). + *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). Parameters ---------- @@ -290,6 +295,7 @@ def asin(x: array, /) -> 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`. """ + def asinh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the inverse hyperbolic sine for each element ``x_i`` in the input array ``x``. @@ -348,6 +354,7 @@ def asinh(x: array, /) -> 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`. """ + def atan(x: array, /) -> array: r""" Calculates an implementation-dependent approximation of the principal value of the inverse tangent for each element ``x_i`` of the input array ``x``. @@ -393,6 +400,7 @@ def atan(x: array, /) -> 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`. """ + def atan2(x1: array, x2: array, /) -> array: """ Calculates an implementation-dependent approximation of the inverse tangent of the quotient ``x1/x2``, having domain ``[-infinity, +infinity] x [-infinity, +infinity]`` (where the ``x`` notation denotes the set of ordered pairs of elements ``(x1_i, x2_i)``) and codomain ``[-π, +π]``, for each pair of elements ``(x1_i, x2_i)`` of the input arrays ``x1`` and ``x2``, respectively. Each element-wise result is expressed in radians. @@ -446,6 +454,7 @@ def atan2(x1: array, x2: array, /) -> array: """ + def atanh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the inverse hyperbolic tangent for each element ``x_i`` of the input array ``x``. @@ -508,6 +517,7 @@ def atanh(x: array, /) -> 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`. """ + def bitwise_and(x1: array, x2: array, /) -> array: """ Computes the bitwise AND of the underlying binary representation of each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -525,6 +535,7 @@ def bitwise_and(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def bitwise_left_shift(x1: array, x2: array, /) -> array: """ Shifts the bits of each element ``x1_i`` of the input array ``x1`` to the left by appending ``x2_i`` (i.e., the respective element in the input array ``x2``) zeros to the right of ``x1_i``. @@ -542,6 +553,7 @@ def bitwise_left_shift(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def bitwise_invert(x: array, /) -> array: """ Inverts (flips) each bit for each element ``x_i`` of the input array ``x``. @@ -557,6 +569,7 @@ def bitwise_invert(x: array, /) -> array: an array containing the element-wise results. The returned array must have the same data type as ``x``. """ + def bitwise_or(x1: array, x2: array, /) -> array: """ Computes the bitwise OR of the underlying binary representation of each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -574,6 +587,7 @@ def bitwise_or(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + 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``. @@ -594,6 +608,7 @@ def bitwise_right_shift(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def bitwise_xor(x1: array, x2: array, /) -> array: """ Computes the bitwise XOR of the underlying binary representation of each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -611,6 +626,7 @@ def bitwise_xor(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def ceil(x: array, /) -> array: """ Rounds each element ``x_i`` of the input array ``x`` to the smallest (i.e., closest to ``-infinity``) integer-valued number that is not less than ``x_i``. @@ -638,6 +654,7 @@ def ceil(x: array, /) -> array: an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. """ + def conj(x: array, /) -> array: """ Returns the complex conjugate for each element ``x_i`` of the input array ``x``. @@ -706,6 +723,7 @@ def cos(x: array, /) -> 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`. """ + def cosh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the hyperbolic cosine for each element ``x_i`` in the input array ``x``. @@ -762,6 +780,7 @@ def cosh(x: array, /) -> 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`. """ + def divide(x1: array, x2: array, /) -> array: r""" Calculates the division of each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -811,17 +830,17 @@ def divide(x1: array, x2: array, /) -> array: +------------+----------------+-----------------+--------------------------+ 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 - + .. math:: \frac{a + bj}{c + dj} = \frac{(ac + bd) + (bc - ad)j}{c^2 + d^2} - + When at least one of ``a``, ``b``, ``c``, or ``d`` is ``NaN``, ``+infinity``, or ``-infinity``, - + - If ``a``, ``b``, ``c``, and ``d`` are all ``NaN``, the result is ``NaN + NaN j``. - In the remaining cases, the result is implementation dependent. - + .. 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. @@ -838,6 +857,7 @@ def divide(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`. """ + def equal(x1: array, x2: array, /) -> array: r""" Computes the truth value of ``x1_i == x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -875,6 +895,7 @@ def equal(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + 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). @@ -924,6 +945,7 @@ def exp(x: array, /) -> 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`. """ + def expm1(x: array, /) -> array: """ Calculates an implementation-dependent approximation to ``exp(x)-1`` for each element ``x_i`` of the input array ``x``. @@ -976,6 +998,7 @@ def expm1(x: array, /) -> 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`. """ + def floor(x: array, /) -> array: """ Rounds each element ``x_i`` of the input array ``x`` to the greatest (i.e., closest to ``+infinity``) integer-valued number that is not greater than ``x_i``. @@ -1003,6 +1026,7 @@ def floor(x: array, /) -> array: an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. """ + def floor_divide(x1: array, x2: array, /) -> array: r""" Rounds the result of dividing each element ``x1_i`` of the input array ``x1`` by the respective element ``x2_i`` of the input array ``x2`` to the greatest (i.e., closest to `+infinity`) integer-value number that is not greater than the division result. @@ -1059,6 +1083,7 @@ def floor_divide(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def greater(x1: array, x2: array, /) -> array: """ Computes the truth value of ``x1_i > x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1079,6 +1104,7 @@ def greater(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def greater_equal(x1: array, x2: array, /) -> array: """ Computes the truth value of ``x1_i >= x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1099,6 +1125,7 @@ def greater_equal(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def imag(x: array, /) -> array: """ Returns the imaginary component of a complex number for each element ``x_i`` of the input array ``x``. @@ -1111,9 +1138,10 @@ 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``). """ + def isfinite(x: array, /) -> array: """ Tests each element ``x_i`` of the input array ``x`` to determine if finite. @@ -1144,6 +1172,7 @@ def isfinite(x: array, /) -> array: an array containing test results. The returned array must have a data type of ``bool``. """ + def isinf(x: array, /) -> array: """ Tests each element ``x_i`` of the input array ``x`` to determine if equal to positive or negative infinity. @@ -1172,6 +1201,7 @@ def isinf(x: array, /) -> array: an array containing test results. The returned array must have a data type of ``bool``. """ + def isnan(x: array, /) -> array: """ Tests each element ``x_i`` of the input array ``x`` to determine whether the element is ``NaN``. @@ -1199,6 +1229,7 @@ def isnan(x: array, /) -> array: an array containing test results. The returned array should have a data type of ``bool``. """ + def less(x1: array, x2: array, /) -> array: """ Computes the truth value of ``x1_i < x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1219,6 +1250,7 @@ def less(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def less_equal(x1: array, x2: array, /) -> array: """ Computes the truth value of ``x1_i <= x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1239,6 +1271,7 @@ def less_equal(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def log(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the natural (base ``e``) logarithm for each element ``x_i`` of the input array ``x``. @@ -1281,7 +1314,7 @@ def log(x: array, /) -> array: Accordingly, for complex arguments, the function returns the natural logarithm in the range of a strip in the interval :math:`[-\pi j, +\pi j]` along the imaginary axis and mathematically unbounded along the real axis. - *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). + *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). Parameters ---------- @@ -1294,6 +1327,7 @@ def log(x: array, /) -> 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`. """ + def log1p(x: array, /) -> array: r""" 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``. @@ -1328,7 +1362,7 @@ def log1p(x: array, /) -> array: .. note:: 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)`. @@ -1349,6 +1383,7 @@ def log1p(x: array, /) -> 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`. """ + def log2(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the base ``2`` logarithm for each element ``x_i`` of the input array ``x``. @@ -1384,6 +1419,7 @@ def log2(x: array, /) -> 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`. """ + def log10(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the base ``10`` logarithm for each element ``x_i`` of the input array ``x``. @@ -1419,6 +1455,7 @@ def log10(x: array, /) -> 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`. """ + def logaddexp(x1: array, x2: array, /) -> array: """ Calculates the logarithm of the sum of exponentiations ``log(exp(x1) + exp(x2))`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1444,6 +1481,7 @@ def logaddexp(x1: array, x2: array, /) -> 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`. """ + 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``. @@ -1464,6 +1502,7 @@ def logical_and(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of `bool`. """ + def logical_not(x: array, /) -> array: """ Computes the logical NOT for each element ``x_i`` of the input array ``x``. @@ -1482,6 +1521,7 @@ def logical_not(x: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + 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``. @@ -1502,6 +1542,7 @@ def logical_or(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + 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``. @@ -1522,6 +1563,7 @@ def logical_xor(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def multiply(x1: array, x2: array, /) -> array: r""" Calculates the product for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1583,6 +1625,7 @@ def multiply(x1: array, x2: array, /) -> array: an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`. """ + def negative(x: array, /) -> array: """ Computes the numerical negative of each element ``x_i`` (i.e., ``y_i = -x_i``) of the input array ``x``. @@ -1604,6 +1647,7 @@ def negative(x: array, /) -> 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`. """ + def not_equal(x1: array, x2: array, /) -> array: """ Computes the truth value of ``x1_i != x2_i`` for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. @@ -1639,6 +1683,7 @@ def not_equal(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type of ``bool``. """ + def positive(x: array, /) -> array: """ Computes the numerical positive of each element ``x_i`` (i.e., ``y_i = +x_i``) of the input array ``x``. @@ -1654,6 +1699,7 @@ def positive(x: array, /) -> array: an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. """ + def pow(x1: array, x2: array, /) -> array: r""" Calculates an implementation-dependent approximation of exponentiation by raising each element ``x1_i`` (the base) of the input array ``x1`` to the power of ``x2_i`` (the exponent), where ``x2_i`` is the corresponding element of the input array ``x2``. @@ -1717,6 +1763,7 @@ def pow(x1: array, x2: array, /) -> array: an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. """ + def real(x: array, /) -> array: """ Returns the real component of a complex number for each element ``x_i`` of the input array ``x``. @@ -1729,9 +1776,10 @@ 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``). """ + def remainder(x1: array, x2: array, /) -> array: """ Returns the remainder of division for each element ``x1_i`` of the input array ``x1`` and the respective element ``x2_i`` of the input array ``x2``. @@ -1783,13 +1831,14 @@ def remainder(x1: array, x2: array, /) -> 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`. """ + 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. - + 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))``). **Special cases** @@ -1819,6 +1868,7 @@ def round(x: array, /) -> array: an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. """ + def sign(x: array, /) -> array: r""" Returns an indication of the sign of a number for each element ``x_i`` of the input array ``x``. @@ -1859,6 +1909,7 @@ def sign(x: array, /) -> array: an array containing the evaluated result for each element in ``x``. The returned array must have the same data type as ``x``. """ + def sin(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the sine for each element ``x_i`` of the input array ``x``. @@ -1898,6 +1949,7 @@ def sin(x: array, /) -> 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`. """ + def sinh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the hyperbolic sine for each element ``x_i`` of the input array ``x``. @@ -1954,6 +2006,7 @@ def sinh(x: array, /) -> 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`. """ + def square(x: array, /) -> array: r""" Squares each element ``x_i`` of the input array ``x``. @@ -1978,6 +2031,7 @@ def square(x: array, /) -> 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`. """ + def sqrt(x: array, /) -> array: r""" Calculates the principal square root for each element ``x_i`` of the input array ``x``. @@ -2018,7 +2072,7 @@ def sqrt(x: array, /) -> array: Accordingly, for complex arguments, the function returns the square root in the range of the right half-plane, including the imaginary axis (i.e., the plane defined by :math:`[0, +\infty)` along the real axis and :math:`(-\infty, +\infty)` along the imaginary axis). *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). - + Parameters ---------- x: array @@ -2030,6 +2084,7 @@ def sqrt(x: array, /) -> 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`. """ + 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``. @@ -2049,6 +2104,7 @@ def subtract(x1: array, x2: array, /) -> array: an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`. """ + def tan(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the tangent for each element ``x_i`` of the input array ``x``. @@ -2088,6 +2144,7 @@ def tan(x: array, /) -> 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`. """ + def tanh(x: array, /) -> array: r""" Calculates an implementation-dependent approximation to the hyperbolic tangent for each element ``x_i`` of the input array ``x``. @@ -2148,6 +2205,7 @@ def tanh(x: array, /) -> 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`. """ + def trunc(x: array, /) -> array: """ Rounds each element ``x_i`` of the input array ``x`` to the nearest integer-valued number that is closer to zero than ``x_i``. @@ -2175,4 +2233,65 @@ def trunc(x: array, /) -> array: an array containing the rounded result for each element in ``x``. The returned array must have the same data type as ``x``. """ -__all__ = ['abs', 'acos', 'acosh', 'add', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'bitwise_and', 'bitwise_left_shift', 'bitwise_invert', 'bitwise_or', 'bitwise_right_shift', 'bitwise_xor', 'ceil', 'conj', 'cos', 'cosh', 'divide', 'equal', 'exp', 'expm1', 'floor', 'floor_divide', 'greater', 'greater_equal', 'imag', 'isfinite', 'isinf', 'isnan', 'less', 'less_equal', 'log', 'log1p', 'log2', 'log10', 'logaddexp', 'logical_and', 'logical_not', 'logical_or', 'logical_xor', 'multiply', 'negative', 'not_equal', 'positive', 'pow', 'real', 'remainder', 'round', 'sign', 'sin', 'sinh', 'square', 'sqrt', 'subtract', 'tan', 'tanh', 'trunc'] + +__all__ = [ + "abs", + "acos", + "acosh", + "add", + "asin", + "asinh", + "atan", + "atan2", + "atanh", + "bitwise_and", + "bitwise_left_shift", + "bitwise_invert", + "bitwise_or", + "bitwise_right_shift", + "bitwise_xor", + "ceil", + "conj", + "cos", + "cosh", + "divide", + "equal", + "exp", + "expm1", + "floor", + "floor_divide", + "greater", + "greater_equal", + "imag", + "isfinite", + "isinf", + "isnan", + "less", + "less_equal", + "log", + "log1p", + "log2", + "log10", + "logaddexp", + "logical_and", + "logical_not", + "logical_or", + "logical_xor", + "multiply", + "negative", + "not_equal", + "positive", + "pow", + "real", + "remainder", + "round", + "sign", + "sin", + "sinh", + "square", + "sqrt", + "subtract", + "tan", + "tanh", + "trunc", +] diff --git a/spec/API_specification/array_api/fft.py b/spec/API_specification/array_api/fft.py index ac292ceb9..2eb428b0c 100644 --- a/spec/API_specification/array_api/fft.py +++ b/spec/API_specification/array_api/fft.py @@ -1,7 +1,14 @@ from ._types import Tuple, Union, Sequence, array, Optional, Literal, device -def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def fft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional discrete Fourier transform. @@ -40,7 +47,14 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[' """ -def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def ifft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional inverse discrete Fourier transform. @@ -79,7 +93,14 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[ """ -def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def fftn( + x: array, + /, + *, + s: Sequence[int] = None, + axes: Sequence[int] = None, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the n-dimensional discrete Fourier transform. @@ -125,7 +146,14 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no """ -def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def ifftn( + x: array, + /, + *, + s: Sequence[int] = None, + axes: Sequence[int] = None, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the n-dimensional inverse discrete Fourier transform. @@ -171,7 +199,14 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n """ -def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def rfft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional discrete Fourier transform for real-valued input. @@ -210,7 +245,14 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[ """ -def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def irfft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional inverse of ``rfft`` for complex-valued input. @@ -249,7 +291,14 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal """ -def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def rfftn( + x: array, + /, + *, + s: Sequence[int] = None, + axes: Sequence[int] = None, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the n-dimensional discrete Fourier transform for real-valued input. @@ -295,7 +344,14 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n """ -def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def irfftn( + x: array, + /, + *, + s: Sequence[int] = None, + axes: Sequence[int] = None, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the n-dimensional inverse of ``rfftn`` for complex-valued input. @@ -341,7 +397,14 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, """ -def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def hfft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry. @@ -377,7 +440,14 @@ def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[ """ -def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array: +def ihfft( + x: array, + /, + *, + n: Optional[int] = None, + axis: int = -1, + norm: Literal["backward", "ortho", "forward"] = "backward", +) -> array: """ Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry. @@ -513,4 +583,19 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: """ -__all__ = ['fft','ifft','fftn','ifftn','rfft','irfft','rfftn','irfftn','hfft','ihfft','fftfreq','rfftfreq','fftshift','ifftshift'] +__all__ = [ + "fft", + "ifft", + "fftn", + "ifftn", + "rfft", + "irfft", + "rfftn", + "irfftn", + "hfft", + "ihfft", + "fftfreq", + "rfftfreq", + "fftshift", + "ifftshift", +] diff --git a/spec/API_specification/array_api/indexing_functions.py b/spec/API_specification/array_api/indexing_functions.py index 65f2c3450..e76ce7484 100644 --- a/spec/API_specification/array_api/indexing_functions.py +++ b/spec/API_specification/array_api/indexing_functions.py @@ -1,5 +1,6 @@ from ._types import Union, array + def take(x: array, indices: array, /, *, axis: int) -> array: """ Returns elements of an array along an axis. @@ -24,4 +25,5 @@ def take(x: array, indices: array, /, *, axis: int) -> 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``. """ -__all__ = ['take'] + +__all__ = ["take"] diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index faa8ba9e6..6bcd37570 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -1,6 +1,7 @@ from ._types import Literal, Optional, Tuple, Union, Sequence, array, dtype from .constants import inf + def cholesky(x: array, /, *, upper: bool = False) -> array: r""" Returns the lower (upper) Cholesky decomposition of a complex Hermitian or real symmetric positive-definite matrix ``x``. @@ -39,6 +40,7 @@ def cholesky(x: array, /, *, upper: bool = False) -> 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``. """ + def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: """ Returns the cross product of 3-element vectors. @@ -71,6 +73,7 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. """ + def det(x: array, /) -> array: """ Returns the determinant of a square matrix (or a stack of square matrices) ``x``. @@ -86,6 +89,7 @@ def det(x: array, /) -> 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``. """ + def diagonal(x: array, /, *, offset: int = 0) -> array: """ Returns the specified diagonals of a matrix (or a stack of matrices) ``x``. @@ -109,6 +113,7 @@ def diagonal(x: array, /, *, offset: int = 0) -> 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``. """ + def eigh(x: array, /) -> Tuple[array]: r""" Returns an eigenvalue decomposition of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``. @@ -154,6 +159,7 @@ def eigh(x: array, /) -> Tuple[array]: Eigenvalue sort order is left unspecified and is thus implementation-dependent. """ + def eigvalsh(x: array, /) -> array: r""" Returns the eigenvalues of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``. @@ -191,6 +197,7 @@ def eigvalsh(x: array, /) -> array: Eigenvalue sort order is left unspecified and is thus implementation-dependent. """ + def inv(x: array, /) -> array: r""" Returns the multiplicative inverse of a square matrix (or a stack of square matrices) ``x``. @@ -219,12 +226,20 @@ def inv(x: array, /) -> 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``. """ + def matmul(x1: array, x2: array, /) -> array: """ Alias for :func:`~array_api.matmul`. """ -def matrix_norm(x: array, /, *, keepdims: bool = False, ord: Optional[Union[int, float, Literal[inf, -inf, 'fro', 'nuc']]] = 'fro') -> array: + +def matrix_norm( + x: array, + /, + *, + keepdims: bool = False, + ord: Optional[Union[int, float, Literal[inf, -inf, "fro", "nuc"]]] = "fro", +) -> array: """ Computes the matrix norm of a matrix (or a stack of matrices) ``x``. @@ -277,6 +292,7 @@ def matrix_norm(x: array, /, *, keepdims: bool = False, ord: Optional[Union[int, 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). """ + def matrix_power(x: array, n: int, /) -> array: """ Raises a square matrix (or a stack of square matrices) ``x`` to an integer power ``n``. @@ -294,6 +310,7 @@ def matrix_power(x: array, n: int, /) -> 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`. """ + def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: """ Returns the rank (i.e., number of non-zero singular values) of a matrix (or a stack of matrices). @@ -313,11 +330,13 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a 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]``). """ + def matrix_transpose(x: array, /) -> array: """ Alias for :func:`~array_api.matrix_transpose`. """ + def outer(x1: array, x2: array, /) -> array: """ Returns the outer product of two vectors ``x1`` and ``x2``. @@ -335,6 +354,7 @@ def outer(x1: array, x2: array, /) -> 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`. """ + def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> array: r""" Returns the (Moore-Penrose) pseudo-inverse of a matrix (or a stack of matrices) ``x``. @@ -368,7 +388,10 @@ def pinv(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> 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). """ -def qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') -> Tuple[array, array]: + +def qr( + x: array, /, *, mode: Literal["reduced", "complete"] = "reduced" +) -> Tuple[array, array]: r""" Returns the QR decomposition of a full column rank matrix (or a stack of matrices). @@ -424,6 +447,7 @@ def qr(x: array, /, *, mode: Literal['reduced', 'complete'] = 'reduced') -> Tupl Each returned array must have a floating-point data type determined by :ref:`type-promotion`. """ + def slogdet(x: array, /) -> Tuple[array, array]: r""" Returns the sign and the natural logarithm of the absolute value of the determinant of a square matrix (or a stack of square matrices) ``x``. @@ -472,6 +496,7 @@ def slogdet(x: array, /) -> Tuple[array, array]: Each returned array must have shape ``shape(x)[:-2]``. """ + def solve(x1: array, x2: array, /) -> array: r""" Returns the solution of a square system of linear equations with a unique solution. @@ -503,6 +528,7 @@ def solve(x1: array, x2: array, /) -> 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`. """ + def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, ...]]: r""" Returns a singular value decomposition (SVD) of a matrix (or a stack of matrices) ``x``. @@ -551,6 +577,7 @@ def svd(x: array, /, *, full_matrices: bool = True) -> Union[array, Tuple[array, - 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``. """ + def svdvals(x: array, /) -> array: """ Returns the singular values of a matrix (or a stack of matrices) ``x``. @@ -568,11 +595,19 @@ def svdvals(x: array, /) -> 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). """ -def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2) -> array: + +def tensordot( + x1: array, + x2: array, + /, + *, + axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2, +) -> array: """ Alias for :func:`~array_api.tensordot`. """ + def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> array: """ Returns the sum along the specified diagonals of a matrix (or a stack of matrices) ``x``. @@ -623,12 +658,21 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr The returned array must have a data type as described by the ``dtype`` parameter above. """ + def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array: """ Alias for :func:`~array_api.vecdot`. """ -def vector_norm(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False, ord: Union[int, float, Literal[inf, -inf]] = 2) -> array: + +def vector_norm( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, + ord: Union[int, float, Literal[inf, -inf]] = 2, +) -> array: r""" Computes the vector norm of a vector (or batch of vectors) ``x``. @@ -679,4 +723,29 @@ def vector_norm(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = No 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). """ -__all__ = ['cholesky', 'cross', 'det', 'diagonal', 'eigh', 'eigvalsh', 'inv', 'matmul', 'matrix_norm', 'matrix_power', 'matrix_rank', 'matrix_transpose', 'outer', 'pinv', 'qr', 'slogdet', 'solve', 'svd', 'svdvals', 'tensordot', 'trace', 'vecdot', 'vector_norm'] + +__all__ = [ + "cholesky", + "cross", + "det", + "diagonal", + "eigh", + "eigvalsh", + "inv", + "matmul", + "matrix_norm", + "matrix_power", + "matrix_rank", + "matrix_transpose", + "outer", + "pinv", + "qr", + "slogdet", + "solve", + "svd", + "svdvals", + "tensordot", + "trace", + "vecdot", + "vector_norm", +] diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 6507c37cd..74559aca8 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -1,5 +1,6 @@ from ._types import Tuple, Union, Sequence, array + def matmul(x1: array, x2: array, /) -> array: """ Computes the matrix product. @@ -41,6 +42,7 @@ def matmul(x1: array, x2: array, /) -> array: - if ``x1`` is an array having shape ``(..., M, K)``, ``x2`` is an array having shape ``(..., L, N)``, and ``K != L``. """ + def matrix_transpose(x: array, /) -> array: """ Transposes a matrix (or a stack of matrices) ``x``. @@ -56,7 +58,14 @@ def matrix_transpose(x: array, /) -> 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``. """ -def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2) -> array: + +def tensordot( + x1: array, + x2: array, + /, + *, + axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2, +) -> array: """ Returns a tensor contraction of ``x1`` and ``x2`` over specific axes. @@ -94,15 +103,16 @@ def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], 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`. """ + def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: """ Computes the (vector) dot product of two arrays. - + Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as - + .. math:: \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} a_i\overline{b_i} - + over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{b_i}` denotes the complex conjugate if :math:`b_i` is complex and the identity if :math:`b_i` is real-valued. Parameters @@ -130,4 +140,5 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. """ -__all__ = ['matmul', 'matrix_transpose', 'tensordot', 'vecdot'] + +__all__ = ["matmul", "matrix_transpose", "tensordot", "vecdot"] diff --git a/spec/API_specification/array_api/manipulation_functions.py b/spec/API_specification/array_api/manipulation_functions.py index 9d355f9e5..314f4627e 100644 --- a/spec/API_specification/array_api/manipulation_functions.py +++ b/spec/API_specification/array_api/manipulation_functions.py @@ -1,5 +1,6 @@ from ._types import List, Optional, Tuple, Union, array + def broadcast_arrays(*arrays: array) -> List[array]: """ Broadcasts one or more arrays against one another. @@ -15,6 +16,7 @@ def broadcast_arrays(*arrays: array) -> 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. """ + def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: """ Broadcasts an array to a specified shape. @@ -32,7 +34,10 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: an array having a specified shape. Must have the same data type as ``x``. """ -def concat(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0) -> array: + +def concat( + arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0 +) -> array: """ Joins a sequence of arrays along an existing axis. @@ -52,6 +57,7 @@ def concat(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[i This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. """ + def expand_dims(x: array, /, *, axis: int = 0) -> array: """ Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by ``axis``. @@ -69,6 +75,7 @@ def expand_dims(x: array, /, *, axis: int = 0) -> array: an expanded output array having the same data type as ``x``. """ + 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. @@ -86,6 +93,7 @@ def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> an output array having the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered. """ + def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array: """ Permutes the axes (dimensions) of an array ``x``. @@ -103,7 +111,10 @@ def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array: an array containing the axes permutation. The returned array must have the same data type as ``x``. """ -def reshape(x: array, /, shape: Tuple[int, ...], *, copy: Optional[bool] = None) -> array: + +def reshape( + x: array, /, shape: Tuple[int, ...], *, copy: Optional[bool] = None +) -> array: """ Reshapes an array without changing its data. @@ -122,7 +133,14 @@ def reshape(x: array, /, shape: Tuple[int, ...], *, copy: Optional[bool] = None) an output array having the same data type and elements as ``x``. """ -def roll(x: array, /, shift: Union[int, Tuple[int, ...]], *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array: + +def roll( + x: array, + /, + shift: Union[int, Tuple[int, ...]], + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, +) -> array: """ Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position. @@ -141,6 +159,7 @@ def roll(x: array, /, shift: Union[int, Tuple[int, ...]], *, axis: Optional[Unio an output array having the same data type as ``x`` and whose elements, relative to ``x``, are shifted. """ + def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array: """ Removes singleton dimensions (axes) from ``x``. @@ -158,6 +177,7 @@ def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array: an output array having the same data type and elements as ``x``. """ + def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> array: """ Joins a sequence of arrays along a new axis. @@ -178,4 +198,16 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. """ -__all__ = [ 'broadcast_arrays', 'broadcast_to', 'concat', 'expand_dims', 'flip', 'permute_dims', 'reshape', 'roll', 'squeeze', 'stack'] \ No newline at end of file + +__all__ = [ + "broadcast_arrays", + "broadcast_to", + "concat", + "expand_dims", + "flip", + "permute_dims", + "reshape", + "roll", + "squeeze", + "stack", +] diff --git a/spec/API_specification/array_api/searching_functions.py b/spec/API_specification/array_api/searching_functions.py index 1db08f287..9393ba71e 100644 --- a/spec/API_specification/array_api/searching_functions.py +++ b/spec/API_specification/array_api/searching_functions.py @@ -1,5 +1,6 @@ from ._types import Optional, Tuple, array + def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: """ Returns the indices of the maximum values along a specified axis. @@ -24,6 +25,7 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - 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. """ + def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: """ Returns the indices of the minimum values along a specified axis. @@ -48,6 +50,7 @@ def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - 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. """ + def nonzero(x: array, /) -> Tuple[array, ...]: """ Returns the indices of the array elements which are non-zero. @@ -74,6 +77,7 @@ def nonzero(x: array, /) -> 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. """ + def where(condition: array, x1: array, x2: array, /) -> array: """ Returns elements chosen from ``x1`` or ``x2`` depending on ``condition``. @@ -93,4 +97,5 @@ def where(condition: array, x1: array, x2: array, /) -> 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``. """ -__all__ = ['argmax', 'argmin', 'nonzero', 'where'] + +__all__ = ["argmax", "argmin", "nonzero", "where"] diff --git a/spec/API_specification/array_api/set_functions.py b/spec/API_specification/array_api/set_functions.py index 34ae41848..dc95f58e8 100644 --- a/spec/API_specification/array_api/set_functions.py +++ b/spec/API_specification/array_api/set_functions.py @@ -1,5 +1,6 @@ from ._types import Tuple, array + def unique_all(x: array, /) -> Tuple[array, array, array, array]: """ Returns the unique elements of an input array ``x``, the first occurring indices for each unique element in ``x``, the indices from the set of unique elements that reconstruct ``x``, and the corresponding counts for each unique element in ``x``. @@ -39,6 +40,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: The order of unique elements is not specified and may vary between implementations. """ + def unique_counts(x: array, /) -> Tuple[array, array]: """ Returns the unique elements of an input array ``x`` and the corresponding counts for each unique element in ``x``. @@ -74,6 +76,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: The order of unique elements is not specified and may vary between implementations. """ + def unique_inverse(x: array, /) -> Tuple[array, array]: """ Returns the unique elements of an input array ``x`` and the indices from the set of unique elements that reconstruct ``x``. @@ -109,6 +112,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: The order of unique elements is not specified and may vary between implementations. """ + def unique_values(x: array, /) -> array: """ Returns the unique elements of an input array ``x``. @@ -139,4 +143,5 @@ def unique_values(x: array, /) -> array: The order of unique elements is not specified and may vary between implementations. """ -__all__ = ['unique_all', 'unique_counts', 'unique_inverse', 'unique_values'] \ No newline at end of file + +__all__ = ["unique_all", "unique_counts", "unique_inverse", "unique_values"] diff --git a/spec/API_specification/array_api/sorting_functions.py b/spec/API_specification/array_api/sorting_functions.py index 53732d535..3eb52c8ce 100644 --- a/spec/API_specification/array_api/sorting_functions.py +++ b/spec/API_specification/array_api/sorting_functions.py @@ -1,6 +1,9 @@ from ._types import array -def argsort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True) -> array: + +def argsort( + x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True +) -> array: """ Returns the indices that sort an array ``x`` along a specified axis. @@ -24,7 +27,10 @@ def argsort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bo 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. """ -def sort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True) -> array: + +def sort( + x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True +) -> array: """ Returns a sorted copy of an input array ``x``. @@ -48,4 +54,5 @@ def sort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool a sorted array. The returned array must have the same data type and shape as ``x``. """ -__all__ = ['argsort', 'sort'] \ No newline at end of file + +__all__ = ["argsort", "sort"] diff --git a/spec/API_specification/array_api/statistical_functions.py b/spec/API_specification/array_api/statistical_functions.py index a49fe4bec..24ef810af 100644 --- a/spec/API_specification/array_api/statistical_functions.py +++ b/spec/API_specification/array_api/statistical_functions.py @@ -1,6 +1,13 @@ from ._types import Optional, Tuple, Union, array, dtype -def max(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: + +def max( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, +) -> array: """ Calculates the maximum value of the input array ``x``. @@ -31,7 +38,14 @@ def max(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep 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``. """ -def mean(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: + +def mean( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, +) -> array: """ Calculates the arithmetic mean of the input array ``x``. @@ -60,7 +74,14 @@ def mean(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, kee While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ -def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: + +def min( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, +) -> array: """ Calculates the minimum value of the input array ``x``. @@ -91,7 +112,15 @@ def min(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep 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``. """ -def prod(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtype: Optional[dtype] = None, keepdims: bool = False) -> array: + +def prod( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + dtype: Optional[dtype] = None, + keepdims: bool = False, +) -> array: """ Calculates the product of input array ``x`` elements. @@ -132,7 +161,15 @@ def prod(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dty 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. """ -def std(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, correction: Union[int, float] = 0.0, keepdims: bool = False) -> array: + +def std( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + correction: Union[int, float] = 0.0, + keepdims: bool = False, +) -> array: """ Calculates the standard deviation of the input array ``x``. @@ -163,7 +200,15 @@ def std(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ -def sum(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtype: Optional[dtype] = None, keepdims: bool = False) -> array: + +def sum( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + dtype: Optional[dtype] = None, + keepdims: bool = False, +) -> array: """ Calculates the sum of the input array ``x``. @@ -204,7 +249,15 @@ def sum(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, dtyp 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. """ -def var(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, correction: Union[int, float] = 0.0, keepdims: bool = False) -> array: + +def var( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + correction: Union[int, float] = 0.0, + keepdims: bool = False, +) -> array: """ Calculates the variance of the input array ``x``. @@ -236,4 +289,5 @@ def var(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, corr While this specification recommends that this function only accept input arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to accept input arrays having an integer data type. While mixed data type promotion is implementation-defined, if the input array ``x`` has an integer data type, the returned array must have the default real-valued floating-point data type. """ -__all__ = ['max', 'mean', 'min', 'prod', 'std', 'sum', 'var'] + +__all__ = ["max", "mean", "min", "prod", "std", "sum", "var"] diff --git a/spec/API_specification/array_api/utility_functions.py b/spec/API_specification/array_api/utility_functions.py index c05cb948e..e70fe8aa6 100644 --- a/spec/API_specification/array_api/utility_functions.py +++ b/spec/API_specification/array_api/utility_functions.py @@ -1,6 +1,13 @@ from ._types import Optional, Tuple, Union, array -def all(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: + +def all( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, +) -> array: """ Tests whether all input array elements evaluate to ``True`` along a specified axis. @@ -28,7 +35,14 @@ def all(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep 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``. """ -def any(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keepdims: bool = False) -> array: + +def any( + x: array, + /, + *, + axis: Optional[Union[int, Tuple[int, ...]]] = None, + keepdims: bool = False, +) -> array: """ Tests whether any input array element evaluates to ``True`` along a specified axis. @@ -56,4 +70,5 @@ def any(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None, keep 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``. """ -__all__ = ['all', 'any'] + +__all__ = ["all", "any"] From 8e3c395a00396c99403248e6745f3d243f4fc636 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 14 Dec 2022 23:01:45 +0100 Subject: [PATCH 2/3] Add a `.git-blame-ignore-revs` file to ignore style change commits See https://black.readthedocs.io/en/stable/guides/introducing_black_to_your_project.html#avoiding-ruining-git-blame and https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view Tested that this works out of the box in the GitHub UI, and locally after running: git config blame.ignoreRevsFile .git-blame-ignore-revs --- .git-blame-ignore-revs | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .git-blame-ignore-revs diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 000000000..8fd251e32 --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,2 @@ +# Migrate code style to Black +162034b12711dad54589c5dc9e75942695a7957f From 8a162470c883aa58153ff6b287d1f42a0a7f8430 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 15 Dec 2022 13:45:42 +0100 Subject: [PATCH 3/3] Fix some style issues in docstrings, make pydocstyle check pass The check to run is: ``` pydocstyle . --ignore=D401,D212,D413,D100 --match='(?!_types.py).*\.py' ``` `_types.py` is excluded because it's a private file, and it's too fiddly and not necessary to add docstrings to the classes in that file. --- spec/API_specification/array_api/__init__.py | 2 ++ spec/API_specification/array_api/_types.py | 4 +++- spec/API_specification/array_api/array_object.py | 4 +--- .../array_api/creation_functions.py | 2 +- spec/API_specification/array_api/linalg.py | 16 ++++------------ .../array_api/linear_algebra_functions.py | 2 +- .../array_api/manipulation_functions.py | 2 +- 7 files changed, 13 insertions(+), 19 deletions(-) diff --git a/spec/API_specification/array_api/__init__.py b/spec/API_specification/array_api/__init__.py index 5368c8325..32f88750d 100644 --- a/spec/API_specification/array_api/__init__.py +++ b/spec/API_specification/array_api/__init__.py @@ -1,3 +1,5 @@ +"""Function stubs and API documentation for the array API standard.""" + from .array_object import * from .constants import * from .creation_functions import * diff --git a/spec/API_specification/array_api/_types.py b/spec/API_specification/array_api/_types.py index be81b40ae..4a60040d5 100644 --- a/spec/API_specification/array_api/_types.py +++ b/spec/API_specification/array_api/_types.py @@ -1,5 +1,5 @@ """ -This file defines the types for type annotations. +Types for type annotations used in the array API standard. 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. @@ -33,6 +33,7 @@ @dataclass class finfo_object: + """Dataclass returned by `finfo`.""" bits: int eps: float max: float @@ -42,6 +43,7 @@ class finfo_object: @dataclass class iinfo_object: + """Dataclass returned by `iinfo`.""" bits: int max: int min: int diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index 3dee8c5ab..7c92800d0 100644 --- a/spec/API_specification/array_api/array_object.py +++ b/spec/API_specification/array_api/array_object.py @@ -16,9 +16,7 @@ class _array: def __init__(self: array) -> None: - """ - Initialize the attributes for the array object class. - """ + """Initialize the attributes for the array object class.""" @property def dtype(self: array) -> Dtype: diff --git a/spec/API_specification/array_api/creation_functions.py b/spec/API_specification/array_api/creation_functions.py index bfb89b2ba..3f577b542 100644 --- a/spec/API_specification/array_api/creation_functions.py +++ b/spec/API_specification/array_api/creation_functions.py @@ -156,7 +156,7 @@ def eye( dtype: Optional[dtype] = None, device: Optional[device] = None, ) -> array: - """ + r""" Returns a two-dimensional array with ones on the ``k``\th diagonal and zeros elsewhere. .. note:: diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index 6bcd37570..65e25bc5e 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -228,9 +228,7 @@ def inv(x: array, /) -> array: def matmul(x1: array, x2: array, /) -> array: - """ - Alias for :func:`~array_api.matmul`. - """ + """Alias for :func:`~array_api.matmul`.""" def matrix_norm( @@ -332,9 +330,7 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a def matrix_transpose(x: array, /) -> array: - """ - Alias for :func:`~array_api.matrix_transpose`. - """ + """Alias for :func:`~array_api.matrix_transpose`.""" def outer(x1: array, x2: array, /) -> array: @@ -603,9 +599,7 @@ def tensordot( *, axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2, ) -> array: - """ - Alias for :func:`~array_api.tensordot`. - """ + """Alias for :func:`~array_api.tensordot`.""" def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> array: @@ -660,9 +654,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array: - """ - Alias for :func:`~array_api.vecdot`. - """ + """Alias for :func:`~array_api.vecdot`.""" def vector_norm( diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 74559aca8..c8b6e50f8 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -105,7 +105,7 @@ def tensordot( def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: - """ + r""" Computes the (vector) dot product of two arrays. Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as diff --git a/spec/API_specification/array_api/manipulation_functions.py b/spec/API_specification/array_api/manipulation_functions.py index 314f4627e..2d7179a8b 100644 --- a/spec/API_specification/array_api/manipulation_functions.py +++ b/spec/API_specification/array_api/manipulation_functions.py @@ -190,7 +190,7 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 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.