Merge branch 'main' into feat/searchsorted

Author: kgryte

spec/draft/API_specification/array_object.rst

@@ -7,7 +7,7 @@ Array object
 
 A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods.
 
-Furthermore, a conforming implementation of the array API standard must support array objects of arbitrary rank ``N`` (i.e., number of dimensions), where ``N`` is greater than or equal to zero.
+Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and must explicitly document their maximum supported rank ``N``.
 
 .. note::
     Conforming implementations must support zero-dimensional arrays.

spec/draft/API_specification/elementwise_functions.rst

@@ -34,6 +34,7 @@ Objects in API
    bitwise_xor
    ceil
    conj
+   copysign
    cos
    cosh
    divide

spec/draft/API_specification/indexing.rst

@@ -156,6 +156,9 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult
   .. note::
     Expanding dimensions can be equivalently achieved via repeated invocation of :func:`~array_api.expand_dims`.
 
+  .. note::
+    The constant ``newaxis`` is an alias of ``None`` and can thus be used in a similar manner as ``None``.
+
 - Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) should equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression should be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception should be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``.
 
   .. note::

spec/draft/API_specification/manipulation_functions.rst

@@ -29,4 +29,5 @@ Objects in API
    roll
    squeeze
    stack
+   tile
    unstack

spec/draft/design_topics/index.rst

@@ -7,6 +7,7 @@ Design topics & constraints
 
    copies_views_and_mutation
    data_dependent_output_shapes
+   lazy_eager
    data_interchange
    device_support
    static_typing

spec/draft/design_topics/lazy_eager.rst

@@ -0,0 +1,43 @@
+.. _lazy-eager:
+
+Lazy vs. eager execution
+========================
+
+While the execution model for implementations is out of scope of this standard,
+there are a few aspects of lazy (or graph-based) execution as contrasted to
+eager execution that may have an impact on the prescribed semantics of
+individual APIs, and will therefore show up in the API specification.
+
+One important difference is data-dependent or value-dependent behavior, as
+described in :ref:`data-dependent-output-shapes`. Because such behavior is hard
+to implement, implementers may choose to omit such APIs from their library.
+
+Another difference is when the Python language itself prescribes that a
+specific type *must* be returned. For those cases, it is not possible to return
+a lazy/delayed kind of object to avoid computing a value. This is the case for
+five dunder methods: `__bool__`, `__int__`, `__float__`, `__complex__` and
+`__index__`. Each implementation has only two choices when one of these methods
+is called:
+
+1. Compute a value of the required type (a Python scalar of type `bool`, `int`,
+   `float` or `complex`), or
+2. Raise an exception.
+
+When an implementation is 100% lazy, for example when it serializes a
+computation graph, computing the value is not possible and hence such an
+implementation has no choice but to raise an exception. For a "mostly lazy"
+implementation, it may make sense to trigger execution instead - but it is not
+required to, both choices are valid.
+
+A common code construct where this happens is conditional logic, e.g.::
+
+    vals = compute_something()
+    if all(vals):
+        # The if-statement will make Python call the __bool__ method
+        # on the result of `all(vals)`.
+        do_something_else()
+
+Note that the API does not contain control flow constructs, as of now, that
+would allow avoiding the implicit `__bool__` call in the example above. The
+only control flow-like function is `where`, but there's no function like `cond`
+to replace an `if`-statement.

src/array_api_stubs/_2021_12/array_object.py

@@ -453,7 +453,12 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
     def __getitem__(
         self: array,
         key: Union[
-            int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array
+            int,
+            slice,
+            ellipsis,
+            None,
+            Tuple[Union[int, slice, ellipsis, None], ...],
+            array,
         ],
         /,
     ) -> array:
@@ -464,7 +469,7 @@ def __getitem__(
         ----------
         self: array
             array instance.
-        key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array]
+        key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, None], ...], array]
             index key.
 
         Returns

src/array_api_stubs/_2022_12/array_object.py

@@ -477,7 +477,12 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
     def __getitem__(
         self: array,
         key: Union[
-            int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array
+            int,
+            slice,
+            ellipsis,
+            None,
+            Tuple[Union[int, slice, ellipsis, None], ...],
+            array,
         ],
         /,
     ) -> array:
@@ -488,7 +493,7 @@ def __getitem__(
         ----------
         self: array
             array instance.
-        key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array]
+        key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, None], ...], array]
             index key.
 
         Returns

src/array_api_stubs/_2022_12/elementwise_functions.py

@@ -727,7 +727,7 @@ def conj(x: array, /) -> array:
     Parameters
     ----------
     x: array
-        input array. Should have a complex-floating point data type.
+        input array. Should have a complex floating-point data type.
 
     Returns
     -------

src/array_api_stubs/_draft/array_object.py

@@ -241,6 +241,10 @@ def __bool__(self: array, /) -> bool:
 
         For complex floating-point operands, special cases must be handled as if the operation is implemented as the logical AND of ``bool(real(self))`` and ``bool(imag(self))``.
 
+        **Lazy implementations**
+
+        The Python language requires the return value to be of type ``bool``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
+
         .. versionchanged:: 2022.12
             Added boolean and complex data type support.
         """
@@ -276,6 +280,10 @@ def __complex__(self: array, /) -> complex:
         - If ``self`` is ``-infinity``, the result is ``-infinity + 0j``.
         - If ``self`` is a finite number, the result is ``self + 0j``.
 
+        **Lazy implementations**
+
+        The Python language requires the return value to be of type ``complex``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
+
         .. versionadded:: 2022.12
         """
 
@@ -424,6 +432,10 @@ def __float__(self: array, /) -> float:
         - If ``self`` is ``True``, the result is ``1``.
         - If ``self`` is ``False``, the result is ``0``.
 
+        **Lazy implementations**
+
+        The Python language requires the return value to be of type ``float``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
+
         .. versionchanged:: 2022.12
             Added boolean and complex data type support.
         """
@@ -479,7 +491,12 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
     def __getitem__(
         self: array,
         key: Union[
-            int, slice, ellipsis, Tuple[Union[int, slice, ellipsis, None], ...], array
+            int,
+            slice,
+            ellipsis,
+            None,
+            Tuple[Union[int, slice, ellipsis, None], ...],
+            array,
         ],
         /,
     ) -> array:
@@ -490,7 +507,7 @@ def __getitem__(
         ----------
         self: array
             array instance.
-        key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis, None], ...], array]
+        key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, None], ...], array]
             index key.
 
         Returns
@@ -539,6 +556,13 @@ def __index__(self: array, /) -> int:
         -------
         out: int
             a Python ``int`` object representing the single element of the array instance.
+
+        Notes
+        -----
+
+        **Lazy implementations**
+
+        The Python language requires the return value to be of type ``int``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
         """
 
     def __int__(self: array, /) -> int:
@@ -577,6 +601,13 @@ def __int__(self: array, /) -> int:
         - If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``.
         - If ``self`` is ``NaN``, raise ``ValueError``.
 
+        Notes
+        -----
+
+        **Lazy implementations**
+
+        The Python language requires the return value to be of type ``int``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
+
         .. versionchanged:: 2022.12
             Added boolean and complex data type support.
         """

src/array_api_stubs/_draft/elementwise_functions.py

@@ -16,6 +16,7 @@
     "bitwise_xor",
     "ceil",
     "conj",
+    "copysign",
     "cos",
     "cosh",
     "divide",
@@ -790,7 +791,7 @@ def conj(x: array, /) -> array:
     Parameters
     ----------
     x: array
-        input array. Should have a complex-floating point data type.
+        input array. Should have a complex floating-point data type.
 
     Returns
     -------
@@ -804,6 +805,47 @@ def conj(x: array, /) -> array:
     """
 
 
+def copysign(x1: array, x2: array, /) -> array:
+    r"""
+    Composes a floating-point value with the magnitude of ``x1_i`` and the sign of ``x2_i`` for each element of the input array ``x1``.
+
+    Parameters
+    ----------
+    x1: array
+       input array containing magnitudes. Should have a real-valued floating-point data type.
+    x2: array
+       input array whose sign bits are applied to the magnitudes of ``x1``. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued floating-point data type.
+
+    Returns
+    -------
+    out: array
+       an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
+
+    Notes
+    -----
+
+    **Special cases**
+
+    For real-valued floating-point operands, let ``|x|`` be the absolute value, and if ``x1_i`` is not ``NaN``,
+
+    - If ``x2_i`` is less than ``0``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``-0``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``+0``, the result is ``|x1_i|``.
+    - If ``x2_i`` is greater than ``0``, the result is ``|x1_i|``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``1``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``0``, the result is ``|x1_i|``.
+
+    If ``x1_i`` is ``NaN``,
+
+    - If ``x2_i`` is less than ``0``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``-0``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``+0``, the result is ``NaN`` with a sign bit of ``0``.
+    - If ``x2_i`` is greater than ``0``, the result is ``NaN`` with a sign bit of ``0``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``1``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``0``, the result is ``NaN`` with a sign bit of ``0``.
+    """
+
+
 def cos(x: array, /) -> array:
     r"""
     Calculates an implementation-dependent approximation to the cosine for each element ``x_i`` of the input array ``x``.

src/array_api_stubs/_draft/manipulation_functions.py

@@ -10,6 +10,7 @@
     "roll",
     "squeeze",
     "stack",
+    "tile",
     "unstack",
 ]
 
@@ -257,6 +258,30 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) ->
     """
 
 
+def tile(x: array, repetitions: Tuple[int, ...], /):
+    """
+    Constructs an array by tiling an input array.
+
+    Parameters
+    ----------
+    x: array
+        input array.
+    repetitions: Tuple[int, ...]
+        number of repetitions along each axis (dimension).
+
+        Let ``N = len(x.shape)`` and ``M = len(repetitions)``.
+
+        If ``N > M``, the function must prepend ones until all axes (dimensions) are specified (e.g., if ``x`` has shape ``(8,6,4,2)`` and ``repetitions`` is the tuple ``(3,3)``, then ``repetitions`` must be treated as ``(1,1,3,3)``).
+
+        If ``N < M``, the function must prepend singleton axes (dimensions) to ``x`` until ``x`` has as many axes (dimensions) as ``repetitions`` specifies (e.g., if ``x`` has shape ``(4,2)`` and ``repetitions`` is the tuple ``(3,3,3,3)``, then ``x`` must be treated as if it has shape ``(1,1,4,2)``).
+
+    Returns
+    -------
+    out: array
+        a tiled output array. The returned array must have the same data type as ``x`` and must have a rank (i.e., number of dimensions) equal to ``max(N, M)``. If ``S`` is the shape of the tiled array after prepending singleton dimensions (if necessary) and ``r`` is the tuple of repetitions after prepending ones (if necessary), then the number of elements along each axis (dimension) must satisfy ``S[i]*r[i]``, where ``i`` refers to the ``i`` th axis (dimension).
+    """
+
+
 def unstack(x: array, /, *, axis: int = 0) -> Tuple[array, ...]:
     """
     Splits an array in a sequence of arrays along the given axis.