searching_functions.md

(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

(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.