Sorting#

ivy.argsort(x, /, *, axis=-1, descending=False, stable=True, out=None)[source]#

Return the indices that sort an array x along a specified axis.

Parameters:

x (Union[Array, NativeArray]) – input array.
axis (int, default: -1) – axis along which to sort. If set to -1, the function must sort along the last axis. Default: -1.
descending (bool, default: False) – sort order. If True, the returned indices sort x in descending order (by value). If False, the returned indices sort x in ascending order (by value). Default: False.
stable (bool, default: True) – sort stability. If True, the returned indices must maintain the relative order of x values which compare as equal. If False, the returned indices may or may not maintain the relative order of x values which compare as equal (i.e., the relative order of x values which compare as equal is implementation-dependent). Default: True.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have the same shape as x.

Return type:

Array

Returns:

ret – an array of indices. The returned array must have the same shape as x. 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([3,1,2])
>>> y = ivy.argsort(x)
>>> print(y)
ivy.array([1,2,0])

>>> x = ivy.array([4,3,8])
>>> y = ivy.argsort(x, descending=True)
>>> print(y)
ivy.array([2,0,1])

>>> x = ivy.array([[1.5, 3.2], [2.3, 2.3]])
>>> ivy.argsort(x, axis=0, descending=True, stable=False, out=x)
>>> print(x)
ivy.array([[1, 0], [0, 1]])

>>> x = ivy.array([[[1,3], [3,2]], [[2,4], [2,0]]])
>>> y = ivy.argsort(x, axis=1, descending=False, stable=True)
>>> print(y)
ivy.array([[[0, 1], [1, 0]], [[0, 1], [1, 0]]])

With ivy.Container input:

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

>>> x = ivy.Container(a=ivy.array([[3.5, 5],[2.4, 1]]))
>>> y = ivy.argsort(x)
>>> print(y)
{
    a: ivy.array([[0,1],[1,0]])
}

>>> x = ivy.Container(a=ivy.array([4,3,6]), b=ivy.array([[4, 5], [2, 4]]))
>>> y = ivy.argsort(x, descending=True)
>>> print(y)
{
    a: ivy.array([2, 0, 1]),
    b: ivy.array([[1, 0], [1, 0]])
}

>>> x = ivy.Container(a=ivy.array([[1.5, 3.2],[2.3, 4]]),
...                   b=ivy.array([[[1,3],[3,2],[2,0]]]))
>>> y = x.argsort(axis=-1, descending=True, stable=False)
>>> print(y)
{
    a: ivy.array([[1,0],[1,0]]),
    b: ivy.array([[[1,0],[0, 1],[0, 1]]])
}

ivy.msort(a, /, *, out=None)[source]#

Return a copy of an array sorted along the first axis.

Parameters:

a (Union[Array, NativeArray, list, tuple]) – array-like input.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – sorted array of the same type and shape as a

Examples

>>> a = ivy.asarray([[8, 9, 6],[6, 2, 6]])
>>> ivy.msort(a)
ivy.array(
    [[6, 2, 6],
     [8, 9, 6]]
    )

ivy.searchsorted(x, v, /, *, side='left', sorter=None, ret_dtype='int64', out=None)[source]#

Return the indices of the inserted elements in a sorted array.

Parameters:

x (Union[Array, NativeArray]) – Input array. If sorter is None, then it must be sorted in ascending order, otherwise sorter must be an array of indices that sort it.
v (Union[Array, NativeArray]) – specific elements to insert in array x1
side (Literal['left', 'right'], default: 'left') – The specific elements’ index is at the ‘left’ side or ‘right’ side in the sorted array x1. If the side is ‘left’, the index of the first suitable location located is given. If ‘right’, return the last such index.
ret_dtype (Union[Dtype, NativeDtype], default: 'int64') – the data type for the return value, Default: ivy.int64, only integer data types is allowed.
sorter (Optional[Union[Array, NativeArray, List[int]]], default: None) – optional array of integer indices that sort array x into ascending order, typically the result of argsort.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – An array of insertion points.

Examples

With ivy.Array input:

>>> x = ivy.array([1, 2, 3])
>>> v = ivy.array([2])
>>> y  = ivy.searchsorted(x, v)
>>> print(y)
ivy.array([1])

>>> x = ivy.array([0, 1, 2, 3])
>>> v = ivy.array([3])
>>> y  = ivy.searchsorted(x, v, side='right')
>>> print(y)
ivy.array([4])

>>> x = ivy.array([0, 1, 2, 3, 4, 5])
>>> v = ivy.array([[3, 1], [10, 3], [-2, -1]])
>>> y  = ivy.searchsorted(x, v)
>>> print(y)
ivy.array([[3, 1],
   [6, 3],
   [0, 0]])

ivy.sort(x, /, *, axis=-1, descending=False, stable=True, out=None)[source]#

Return a sorted copy of an array.

Parameters:

x (Union[Array, NativeArray]) – input array
axis (int, default: -1) – axis along which to sort. If set to -1, the function must sort along the last axis. Default: -1.
descending (bool, default: False) – direction The direction in which to sort the values
stable (bool, default: True) – sort stability. If True, the returned indices must maintain the relative order of x values which compare as equal. If False, the returned indices may or may not maintain the relative order of x values which compare as equal (i.e., the relative order of x values which compare as equal is implementation-dependent). Default: True.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have the same shape as x.

Return type:

Array

Returns:

ret – An array with the same dtype and shape as x, with the elements sorted along the given axis.

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

Examples

With ivy.Array input:

>>> x = ivy.array([7, 8, 6])
>>> y = ivy.sort(x)
>>> print(y)
ivy.array([6, 7, 8])

>>> x = ivy.array([[[8.9,0], [19,5]],[[6,0.3], [19,0.5]]])
>>> y = ivy.sort(x, axis=1, descending=True, stable=False)
>>> print(y)
ivy.array([[[19. ,  5. ],[ 8.9,  0. ]],[[19. ,  0.5],[ 6. ,  0.3]]])

>>> x = ivy.array([1.5, 3.2, 0.7, 2.5])
>>> y = ivy.zeros(5)
>>> ivy.sort(x, descending=True, stable=False, out=y)
>>> print(y)
ivy.array([3.2, 2.5, 1.5, 0.7])

>>> x = ivy.array([[1.1, 2.2, 3.3],[-4.4, -5.5, -6.6]])
>>> ivy.sort(x, out=x)
>>> print(x)
ivy.array([[ 1.1,  2.2,  3.3],
    [-6.6, -5.5, -4.4]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([8, 6, 6]),b=ivy.array([[9, 0.7], [0.4, 0]]))
>>> y = ivy.sort(x, descending=True)
>>> print(y)
{
    a: ivy.array([8, 6, 6]),
    b: ivy.array([[9., 0.7], [0.4, 0.]])
}

>>> x = ivy.Container(a=ivy.array([3, 0.7, 1]),b=ivy.array([[4, 0.9], [0.6, 0.2]]))
>>> y = ivy.sort(x, descending=False, stable=False)
>>> print(y)
{
    a: ivy.array([0.7, 1., 3.]),
    b: ivy.array([[0.9, 4.], [0.2, 0.6]])
}

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