diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index f20f916fe..86873453d 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -15,4 +15,5 @@ API specification out_keyword elementwise_functions statistical_functions - linear_algebra_functions + searching_functions + linear_algebra_functions \ No newline at end of file diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md new file mode 100644 index 000000000..58a3286d6 --- /dev/null +++ b/spec/API_specification/searching_functions.md @@ -0,0 +1,110 @@ +# 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. +- The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`. +- 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`. + + + +### # argmax(x, /, *, axis=None, keepdims=False, out=None) + +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. + +- **axis**: _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`. + +- **out**: _Optional\[ <array> ]_ + + - output array. If provided, the output array must have the expected output shape. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each computation. Default: `None`. + +#### 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. + +### # argmin(x, /, *, axis=None, keepdims=False, out=None) + +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. + +- **axis**: _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`. + +- **out**: _Optional\[ <array> ]_ + + - output array. If provided, the output array must have the expected output shape. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each computation. Default: `None`. + +#### 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. + +### # nonzero(x, /) + +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. + +### # where(condition, x1, x2, /) + +Returns elements chosen from `x1` or `x2` depending on `condition`. + +#### Parameters + +- **condition**: _<array<bool>>_ + + - 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. \ No newline at end of file