Searching#

ivy.argmax(x, /, *, axis=None, keepdims=False, dtype=None, select_last_index=False, out=None)[source]#

Return 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 (Union[Array, NativeArray]) – input array. Should have a numeric data type.

  • axis (Optional[int], default: None) – 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, default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the array.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – Optional data type of the output array.

  • select_last_index (bool, default: False) – If this is set to True, the index corresponding to the last occurrence of the maximum value will be returned

  • out (Optional[Array], default: None) – If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.

Return type:

Array

Returns:

ret – 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.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> x = ivy.array([-0., 1., -1.])
>>> y = ivy.argmax(x)
>>> print(y)
ivy.array([1])
>>> x = ivy.array([-0., 1., -1.])
>>> z = ivy.zeros((1,3), dtype=ivy.int64)
>>> ivy.argmax(x, out=z)
>>> print(z)
ivy.array(1)
>>> x = ivy.array([[1., -0., -1.], [-2., 3., 2.]])
>>> y = ivy.argmax(x, axis=1)
>>> print(y)
ivy.array([0, 1])
>>> x = ivy.array([[4., 0., -1.], [2., -3., 6]])
>>> y = ivy.argmax(x, axis=1, keepdims=True)
>>> print(y)
ivy.array([[0], [2]])
>>> x = ivy.array([[4., 0., -1.], [2., -3., 6]])
>>> y = ivy.argmax(x, axis=1, dtype=ivy.int64)
>>> print(y, y.dtype)
ivy.array([0, 2]) int64
>>> x = ivy.array([[4., 0., -1.],[2., -3., 6], [2., -3., 6]])
>>> z = ivy.zeros((3,1), dtype=ivy.int64)
>>> y = ivy.argmax(x, axis=1, keepdims=True, out=z)
>>> print(z)
ivy.array([[0],[2],[2]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([0., -1., 2.]), b=ivy.array([3., 4., 5.]))
>>> y = ivy.argmax(x)
>>> print(y)
{
    a: ivy.array(2),
    b: ivy.array(2)
}
ivy.argmin(x, /, *, axis=None, keepdims=False, dtype=None, select_last_index=False, out=None)[source]#

Return 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 (Union[Array, NativeArray]) – input array. Should have a numeric data type.

  • axis (Optional[int], default: None) – 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, 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 Broadcasting). Otherwise, if False, the reduced axes (dimensions) must not be included in the result. Default = False.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – An optional output_dtype from: int32, int64. Defaults to int64.

  • select_last_index (bool, default: False) – If this is set to True, the index corresponding to the last occurrence of the maximum value will be returned.

  • out (Optional[Array], default: None) – 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.

Return type:

Array

Returns:

ret – Array containing the indices of the minimum values across the specified axis.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> x = ivy.array([0., 1., -1.])
>>> y = ivy.argmin(x)
>>> print(y)
ivy.array(2)
>>> x = ivy.array([[0., 1., -1.],[-2., 1., 2.]])
>>> y = ivy.argmin(x, axis=1)
>>> print(y)
ivy.array([2, 0])
>>> x = ivy.array([[0., 1., -1.],[-2., 1., 2.]])
>>> y = ivy.argmin(x, axis=1, keepdims=True)
>>> print(y)
ivy.array([[2],
       [0]])
>>> x = ivy.array([[0., 1., -1.],[-2., 1., 2.],[1., -2., 0.]])
>>> y= ivy.zeros((3,1), dtype=ivy.int64)
>>> ivy.argmin(x, axis=1, keepdims=True, out=y)
>>> print(y)
ivy.array([[2],
       [0],
       [1]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([0., -1., 2.]), b=ivy.array([3., 4., 5.]))
>>> y = ivy.argmin(x)
>>> print(y)
{
    a: ivy.array(1),
    b: ivy.array(0)
}
ivy.argwhere(x, /, *, out=None)[source]#

Return the indices of all non-zero elements of the input array.

Parameters:
  • x (Union[Array, NativeArray]) – input array, for which indices are desired.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – Indices of non-zero elements.

Examples

With ivy.Array input:

>>> x = ivy.array([[1, 2], [3, 4]])
>>> res = ivy.argwhere(x)
>>> print(res)
ivy.array([[0, 0], [0, 1], [1, 0], [1, 1]])
>>> x = ivy.array([[0, 2], [3, 4]])
>>> res = ivy.argwhere(x)
>>> print(res)
ivy.array([[0, 1], [1, 0], [1, 1]])
>>> x = ivy.array([[0, 2], [3, 4]])
>>> y = ivy.zeros((3, 2), dtype=ivy.int64)
>>> res = ivy.argwhere(x, out=y)
>>> print(res)
ivy.array([[0, 1], [1, 0], [1, 1]])

With a ivy.Container input:

>>> x = ivy.Container(a=ivy.array([1, 2]), b=ivy.array([3, 4]))
>>> res = ivy.argwhere(x)
>>> print(res)
{
    a: ivy.array([[0], [1]]),
    b: ivy.array([[0], [1]])
}
>>> x = ivy.Container(a=ivy.array([1, 0]), b=ivy.array([3, 4]))
>>> res = ivy.argwhere(x)
>>> print(res)
{
    a: ivy.array([[0]]),
    b: ivy.array([[0], [1]])
}
ivy.nonzero(x, /, *, as_tuple=True, size=None, fill_value=0)[source]#

Return the indices of the array elements which are non-zero.

Note

If x has a complex floating-point data type, non-zero elements are those elements having at least one component (real or imaginary) which is non-zero.

Note

If x has a boolean data type, non-zeroelements are those elements which are equal to True.

Parameters:
  • x (Union[Array, NativeArray]) – input array. Must have a positive rank. If x is zero-dimensional, the function must raise an exception.

  • as_tuple (bool, default: True) – if True, the output is returned as a tuple of indices, one for each dimension of the input, containing the indices of the true elements in that dimension. If False, the coordinates are returned in a (N, ndim) array, where N is the number of true elements. Default = True.

  • size (Optional[int], default: None) – if specified, the function will return an array of shape (size, ndim). If the number of non-zero elements is fewer than size, the remaining elements will be filled with fill_value. Default = None.

  • fill_value (Number, default: 0) – when size is specified and there are fewer than size number of elements, the remaining elements in the output array will be filled with fill_value. Default = 0.

Return type:

Union[Tuple[Array], Array]

Returns:

ret – 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.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> x = ivy.array([0, 10, 15, 20, -50, 0])
>>> y = ivy.nonzero(x)
>>> print(y)
(ivy.array([1, 2, 3, 4]),)
>>> x = ivy.array([[1, 2], [-1, -2]])
>>> y = ivy.nonzero(x)
>>> print(y)
(ivy.array([0, 0, 1, 1]), ivy.array([0, 1, 0, 1]))
>>> x = ivy.array([[0, 2], [-1, -2]])
>>> y = ivy.nonzero(x, as_tuple=False)
>>> print(y)
ivy.array([[0, 1], [1, 0], [1, 1]])
>>> x = ivy.array([0, 1])
>>> y = ivy.nonzero(x, size=2, fill_value=4)
>>> print(y)
(ivy.array([1, 4]),)

With ivy.NativeArray input:

>>> x = ivy.native_array([[10, 20], [10, 0], [0, 0]])
>>> y = ivy.nonzero(x)
>>> print(y)
(ivy.array([0, 0, 1]), ivy.array([0, 1, 0]))
>>> x = ivy.native_array([[0], [1], [1], [0], [1]])
>>> y = ivy.nonzero(x)
>>> print(y)
(ivy.array([1, 2, 4]), ivy.array([0, 0, 0]))

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([0,1,2,3,0]), b=ivy.array([1,1, 0,0]))
>>> y = ivy.nonzero(x)
>>> print(y)
[{
    a: ivy.array([1, 2, 3]),
    b: ivy.array([0, 1])
}]

Instance Method Examples

With ivy.Array instance method:

>>> x = ivy.array([0,0,0,1,1,1])
>>> y = x.nonzero()
>>> print(y)
(ivy.array([3, 4, 5]),)

With ivy.Container instance method:

>>> x = ivy.Container(a=ivy.array([1,1,1]), b=ivy.native_array([0]))
>>> y = x.nonzero()
>>> print(y)
[{
    a: ivy.array([0, 1, 2]),
    b: ivy.array([])
}]
ivy.where(condition, x1, x2, /, *, out=None)[source]#

Return elements chosen from x or y depending on condition.

Parameters:
  • condition (Union[Array, NativeArray]) – Where True, yield x1, otherwise yield x2.

  • x1 (Union[Array, NativeArray]) – values from which to choose when condition is True.

  • x2 (Union[Array, NativeArray]) – values from which to choose when condition is False.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – An array with elements from x1 where condition is True, and elements from x2 elsewhere.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> condition = ivy.array([[True, False], [True, True]])
>>> x1 = ivy.array([[1, 2], [3, 4]])
>>> x2 = ivy.array([[5, 6], [7, 8]])
>>> res = ivy.where(condition, x1, x2)
>>> print(res)
ivy.array([[1, 6],
       [3, 4]])
>>> x1 = ivy.array([[6, 13, 22, 7, 12], [7, 11, 16, 32, 9]])
>>> x2 = ivy.array([[44, 20, 8, 35, 9], [98, 23, 43, 6, 13]])
>>> res = ivy.where(((x1 % 2 == 0) & (x2 % 2 == 1)), x1, x2)
>>> print(res)
ivy.array([[44, 20,  8, 35, 12],
       [98, 23, 16,  6, 13]])

With ivy.Container input:

>>> x1 = ivy.Container(a=ivy.array([3, 1, 5]), b=ivy.array([2, 4, 6]))
>>> x2 = ivy.Container(a=ivy.array([0, 7, 2]), b=ivy.array([3, 8, 5]))
>>> condition = x1.a > x2.a
>>> res = x1.where(condition, x2)
>>> print(res)
{
    a: ivy.array([1, 0, 1]),
    b: ivy.array([1, 0, 1])
}

This should have hopefully given you an overview of the searching submodule, if you have any questions, please feel free to reach out on our discord in the searching channel!