From b71cb929559dc859596ff67b685af2f285928500 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 19 Jan 2022 13:49:06 -0500 Subject: [PATCH 1/3] Transform searching functions md to rst --- spec/API_specification/searching_functions.md | 115 ------------------ .../API_specification/searching_functions.rst | 30 +++++ .../signatures/searching_functions.py | 80 ++++++++++++ 3 files changed, 110 insertions(+), 115 deletions(-) delete mode 100644 spec/API_specification/searching_functions.md create mode 100644 spec/API_specification/searching_functions.rst create mode 100644 spec/API_specification/signatures/searching_functions.py diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md deleted file mode 100644 index 7bf3f346e..000000000 --- a/spec/API_specification/searching_functions.md +++ /dev/null @@ -1,115 +0,0 @@ -(searching-functions)= - -# Searching Functions - -> Array API specification for functions for searching arrays. - -A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. - -- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. -- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. -- Broadcasting semantics must follow the semantics defined in {ref}`broadcasting`. -- Unless stated otherwise, functions must support the data types defined in {ref}`data-types`. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`. - -## Objects in API - - - -(function-argmax)= -### argmax(x, /, *, axis=None, keepdims=False) - -Returns the indices of the maximum values along a specified axis. When the maximum value occurs multiple times, only the indices corresponding to the first occurrence are returned. - -#### Parameters - -- **x**: _<array>_ - - - input array. Should have a numeric data type. - -- **axis**: _Optional\[ int ]_ - - - axis along which to search. If `None`, the function must return the index of the maximum value of the flattened array. Default: `None`. - -- **keepdims**: _bool_ - - - If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`. - -#### Returns - -- **out**: _<array>_ - - - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. The returned array must have be the default array index data type. - -(function-argmin)= -### argmin(x, /, *, axis=None, keepdims=False) - -Returns the indices of the minimum values along a specified axis. When the minimum value occurs multiple times, only the indices corresponding to the first occurrence are returned. - -#### Parameters - -- **x**: _<array>_ - - - input array. Should have a numeric data type. - -- **axis**: _Optional\[ int ]_ - - - axis along which to search. If `None`, the function must return the index of the minimum value of the flattened array. Default: `None`. - -- **keepdims**: _bool_ - - - If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`. - -#### Returns - -- **out**: _<array>_ - - - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. The returned array must have the default array index data type. - -(function-nonzero)= -### nonzero(x, /) - -:::{admonition} Data-dependent output shape -:class: important - -The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. -::: - -Returns the indices of the array elements which are non-zero. - -#### Parameters - -- **x**: _<array>_ - - - input array. Must have a positive rank. If `x` is zero-dimensional, the function must raise an exception. - -#### Returns - -- **out**: _Tuple\[ <array>, ... ]_ - - - a tuple of `k` arrays, one for each dimension of `x` and each of size `n` (where `n` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. The returned array must have the default array index data type. - -(function-where)= -### where(condition, x1, x2, /) - -Returns elements chosen from `x1` or `x2` depending on `condition`. - -#### Parameters - -- **condition**: _<array>_ - - - when `True`, yield `x1_i`; otherwise, yield `x2_i`. Must be compatible with `x1` and `x2` (see {ref}`broadcasting`). - -- **x1**: _<array>_ - - - first input array. Must be compatible with `condition` and `x2` (see {ref}`broadcasting`). - -- **x2**: _<array>_ - - - second input array. Must be compatible with `condition` and `x1` (see {ref}`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules with the arrays `x1` and `x2`. diff --git a/spec/API_specification/searching_functions.rst b/spec/API_specification/searching_functions.rst new file mode 100644 index 000000000..18289466a --- /dev/null +++ b/spec/API_specification/searching_functions.rst @@ -0,0 +1,30 @@ +.. _searching-functions: + +Searching Functions +=================== + + Array API specification for functions for searching arrays. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be `keyword-only `_ arguments. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. + +Objects in API +-------------- + +.. currentmodule:: signatures.searching_functions + +.. + NOTE: please keep the functions in alphabetical order + +.. autosummary:: + :toctree: generated + + argmax + argmin + nonzero + where diff --git a/spec/API_specification/signatures/searching_functions.py b/spec/API_specification/signatures/searching_functions.py new file mode 100644 index 000000000..563a5e0c0 --- /dev/null +++ b/spec/API_specification/signatures/searching_functions.py @@ -0,0 +1,80 @@ +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. When the maximum value occurs multiple times, only the indices corresponding to the first occurrence are returned. + + Parameters + ---------- + x: array + input array. Should have a numeric data type. + axis: Optional[int] + axis along which to search. If ``None``, the function must return the index of the maximum value of the flattened array. Default: ``None``. + keepdims: bool + If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. + + Returns + ------- + out: array + if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. The returned array must have be the default array index data type. + """ + +def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: + """ + Returns the indices of the minimum values along a specified axis. When the minimum value occurs multiple times, only the indices corresponding to the first occurrence are returned. + + Parameters + ---------- + x: array + input array. Should have a numeric data type. + axis: Optional[int] + axis along which to search. If ``None``, the function must return the index of the minimum value of the flattened array. Default: ``None``. + keepdims: bool + If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. + + Returns + ------- + out: array + if ``axis`` is ``None``, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. The returned array must have the default array index data type. + """ + +def nonzero(x: array, /) -> Tuple[array, ...]: + """ + Returns the indices of the array elements which are non-zero. + + .. admonition:: Future extension + :class: admonition important + + The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. + + Parameters + ---------- + x: array + input array. Must have a positive rank. If ``x`` is zero-dimensional, the function must raise an exception. + + Returns + ------- + out: Typle[array, ...] + a tuple of ``k`` arrays, one for each dimension of ``x`` and each of size ``n`` (where ``n`` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. The returned array must have the default array index data type. + """ + +def where(condition: array, x1: array, x2: array, /) -> array: + """ + Returns elements chosen from ``x1`` or ``x2`` depending on ``condition``. + + Parameters + ---------- + condition: array + when ``True``, yield ``x1_i``; otherwise, yield ``x2_i``. Must be compatible with ``x1`` and ``x2`` (see :ref:`broadcasting`). + x1: array + first input array. Must be compatible with ``condition`` and ``x2`` (see :ref:`broadcasting`). + x2: array + second input array. Must be compatible with ``condition`` and ``x1`` (see :ref:`broadcasting`). + + Returns + ------- + out: array + an array with elements from ``x1`` where ``condition`` is ``True``, and elements from ``x2`` elsewhere. The returned array must have a data type determined by :ref:`type-promotion` rules with the arrays ``x1`` and ``x2``. + """ + +__all__ = ['argmax', 'argmin', 'nonzero', 'where'] From ddbc80aecbda894360195b1f1d0c9ef7b43c3030 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Tue, 25 Jan 2022 14:47:12 -0500 Subject: [PATCH 2/3] Fix typo --- spec/API_specification/signatures/searching_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/searching_functions.py b/spec/API_specification/signatures/searching_functions.py index 563a5e0c0..37908dba1 100644 --- a/spec/API_specification/signatures/searching_functions.py +++ b/spec/API_specification/signatures/searching_functions.py @@ -42,7 +42,7 @@ def nonzero(x: array, /) -> Tuple[array, ...]: """ Returns the indices of the array elements which are non-zero. - .. admonition:: Future extension + .. admonition:: Data-dependent output shape :class: admonition important The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. From ee85f11d1917f00133d99fef909bb8d6c86ba860 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 31 Jan 2022 00:55:12 -0800 Subject: [PATCH 3/3] Lowercase first sentence to ensure consistency with rest of spec This commit addresses an oversight in the specification prior to Markdown to rST conversion. --- spec/API_specification/signatures/searching_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/signatures/searching_functions.py b/spec/API_specification/signatures/searching_functions.py index 37908dba1..c2875adcc 100644 --- a/spec/API_specification/signatures/searching_functions.py +++ b/spec/API_specification/signatures/searching_functions.py @@ -11,7 +11,7 @@ def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - axis: Optional[int] axis along which to search. If ``None``, the function must return the index of the maximum value of the flattened array. Default: ``None``. keepdims: bool - If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. Returns ------- @@ -30,7 +30,7 @@ def argmin(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) - axis: Optional[int] axis along which to search. If ``None``, the function must return the index of the minimum value of the flattened array. Default: ``None``. keepdims: bool - If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. + if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. Returns -------