Manipulation#

ivy.as_strided(x, shape, strides, /)[source]#

Create a copy of the input array with the given shape and strides.

Parameters:

  • x (Union[Array, NativeArray]) – Input Array.

  • shape (Union[Shape, NativeShape, Sequence[int]]) – The shape of the new array.

  • strides (Sequence[int]) – The strides of the new array (specified in bytes).

Return type:

Array

Returns:

ret – Output Array

Examples

>>> x = ivy.array([1, 2, 3, 4, 5, 6])
>>> ivy.as_strided(x, (4, 3), (8, 8))
ivy.array([[1, 2, 3],
   [2, 3, 4],
   [3, 4, 5],
   [4, 5, 6]])
ivy.associative_scan(x, fn, /, *, reverse=False, axis=0)[source]#

Perform an associative scan over the given array.

Parameters:

  • x (Union[Array, NativeArray]) – The array to scan over.

  • fn (Callable) – The associative function to apply.

  • reverse (bool) – Whether to scan in reverse with respect to the given axis. (default: False)

  • axis (int) – The axis to scan over. (default: 0)

Return type:

Array

Returns:

ret – The result of the scan.

ivy.atleast_1d(*arys, copy=None)[source]#

Convert inputs to arrays with at least one dimension. Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters:

arys (Union[Array, NativeArray, bool, Number]) – One or more input arrays.

Return type:

List[Array]

Returns:

ret – An array, or list of arrays, each with atleast 1D. Copies are made only if necessary.

Examples

>>> ary1 = ivy.array(5)
>>> ivy.atleast_1d(ary1)
ivy.array([5])
>>> ary2 = ivy.array([[3,4]])
>>> ivy.atleast_1d(ary2)
ivy.array([[3, 4]])
>>> ivy.atleast_1d(6,7,8)
[ivy.array([6]), ivy.array([7]), ivy.array([8])]
ivy.atleast_2d(*arys, copy=None)[source]#

Convert inputs to arrays with at least two dimension. Scalar inputs are converted to 2-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters:

arys (Union[Array, NativeArray]) – One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved.

Return type:

List[Array]

Returns:

ret – An array, or list of arrays, each with atleast 2D. Copies are made only if necessary.

Examples

>>> ary1 = ivy.array(5)
>>> ivy.atleast_2d(ary1)
ivy.array([[5]])
>>> ary2 = ivy.array([[[3,4]]])
>>> ivy.atleast_2d(ary2)
ivy.array([[[3, 4]]])
>>> ivy.atleast_2d(6,7,8)
[ivy.array([[6]]), ivy.array([[7]]), ivy.array([[8]])]
ivy.atleast_3d(*arys, copy=None)[source]#

Convert inputs to arrays with at least three dimension. Scalar inputs are converted to 3-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters:

arys (Union[Array, NativeArray, bool, Number]) – One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved.

Return type:

List[Array]

Returns:

ret – An array, or list of arrays, each with a.ndim >= 3. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape (N,) becomes a view of shape (1, N, 1), and a 2-D array of shape (M, N) becomes a view of shape (M, N, 1).

Examples

>>> ary1 = ivy.array([5,6])
>>> ivy.atleast_3d(ary1)
ivy.array([[[5],
        [6]]])
>>> ary2 = ivy.array([[[3,4]]])
>>> ivy.atleast_3d(ary2)
ivy.array([[[3, 4]]])
>>> ary3 = ivy.array([[3,4],[9,10]])
>>> ivy.atleast_3d(6,7,ary3)
[ivy.array([[[6]]]), ivy.array([[[7]]]), ivy.array([[[ 3],
        [ 4]],
[[ 9],

[10]]])]

ivy.broadcast_shapes(*shapes)[source]#

Broadcasts shapes.

Parameters:

shapes (Union[List[int], List[Tuple]]) – The shapes to broadcast.

Return type:

Tuple[int]

Returns:

ret – The broadcasted shape.

Examples

>>> x = [(3, 3), (3, 1)]
>>> print(ivy.broadcast_shapes(x))
(3, 3)

>>> print(ivy.broadcast_shapes([(3, 3),(3, 1),(1, 3)]))
(3, 3)
ivy.concat_from_sequence(input_sequence, /, *, new_axis=0, axis=0, out=None)[source]#

Concatenate a sequence of arrays along a new or an existing axis.

Parameters:

  • input_sequence (Union[Tuple[Union[Array, NativeArray]], List[Union[Array, NativeArray]]]) – A sequence of arrays.

  • new_axis (int) – Insert and concatenate on a new axis or not, (default: 0) default 0 means do not insert new axis. new_axis = 0: concatenate new_axis = 1: stack

  • axis (int) – axis along which the arrays will be concatenated. (default: 0)

  • out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – Output Array

ivy.dsplit(ary, indices_or_sections, /, *, copy=None)[source]#

Split an array into multiple sub-arrays along the 3rd axis.

Parameters:

  • ary (Union[Array, NativeArray]) – Array input.

  • indices_or_sections (Union[int, Sequence[int], Array, NativeArray]) – If indices_or_sections is an integer n, the array is split into n sections. If the array is divisible by n along the 3rd axis, each section will be of equal size. If input is not divisible by n, the sizes of the first int(ary.size(0) % n) sections will have size int(ary.size(0) / n) + 1, and the rest will have size int(ary.size(0) / n). If indices_or_sections is a sequence of ints or 1-D array, then input is split at each of the indices.

Return type:

List[Array]

Returns:

ret – input array split along the 3rd axis.

Examples

>>> ary = ivy.array(
    [[[ 0.,   1.,   2.,   3.],
      [ 4.,   5.,   6.,   7.]],
     [[ 8.,   9.,  10.,  11.],
      [12.,  13.,  14.,  15.]]]
    )
>>> ivy.dsplit(ary, 2)
[ivy.array([[[ 0.,  1.], [ 4.,  5.]], [[ 8.,  9.], [12., 13.]]]),
 ivy.array([[[ 2.,  3.], [ 6.,  7.]], [[10., 11.], [14., 15.]]])]
ivy.dstack(arrays, /, *, out=None)[source]#

Stack arrays in sequence depth wise (along third axis).

Parameters:

arrays (Sequence[Array]) – Sequence of arrays to be stacked.

Return type:

Array

Returns:

ret – The array formed by stacking the given arrays.

Examples

>>> x = ivy.array([1, 2, 3])
>>> y = ivy.array([2, 3, 4])
>>> ivy.dstack((x, y))
ivy.array([[[1, 2],
            [2, 3],
            [3, 4]]])
>>> x = ivy.array([[1], [2], [3]])
>>> y = ivy.array([[2], [3], [4]])
>>> ivy.dstack((x, y))
ivy.array([[[1, 2]],
           [[2, 3]],
           [[3, 4]]])
ivy.expand(x, shape, /, *, copy=None, out=None)[source]#

Broadcast the input Array following the given shape and the broadcast rule.

Parameters:

  • x (Union[Array, NativeArray]) – Array input.

  • shape (Union[Shape, NativeShape]) – A 1-D Array indicates the shape you want to expand to, following the broadcast rule

  • out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – Output Array

ivy.flatten(x, /, *, copy=None, start_dim=0, end_dim=-1, order='C', out=None)[source]#

Flattens input by reshaping it into a one-dimensional tensor. If start_dim or end_dim are passed, only dimensions starting with start_dim and ending with end_dim are flattened. The order of elements in input is unchanged.

Parameters:

  • x (Union[Array, NativeArray]) – input array to flatten.

  • start_dim (Optional[int]) – first dim to flatten. If not set, defaults to 0. (default: 0)

  • end_dim (Optional[int]) – last dim to flatten. If not set, defaults to -1. (default: -1)

  • order (Optional[str]) – Read the elements of the input container using this index order, (default: 'C') and place the elements into the reshaped array using this index order. ‘C’ means to read / write the elements using C-like index order, with the last axis index changing fastest, back to the first axis index changing slowest. ‘F’ means to read / write the elements using Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array, and only refer to the order of indexing. Default order is ‘C’

  • out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – the flattened array over the specified dimensions.

Examples

With ivy.Array input:

>>> x = ivy.array([[1,2], [3,4]])
>>> ivy.flatten(x)
ivy.array([1, 2, 3, 4])

>>> x = ivy.array([[1,2], [3,4]])
>>> ivy.flatten(x, order='F')
ivy.array([1, 3, 2, 4])

>>> x = ivy.array(
    [[[[ 5,  5,  0,  6],
     [17, 15, 11, 16],
     [ 6,  3, 13, 12]],
[[ 6, 18, 10, 4],

[ 5, 1, 17, 3], [14, 14, 18, 6]]],

[[[12, 0, 1, 13],

[ 8, 7, 0, 3], [19, 12, 6, 17]],

[[ 4, 15, 6, 15],

[ 0, 5, 17, 9], [ 9, 3, 6, 19]]],

[[[17, 13, 11, 16],

[ 4, 18, 17, 4], [10, 10, 9, 1]],

[[19, 17, 13, 10],

[ 4, 19, 16, 17], [ 2, 12, 8, 14]]]] )

>>> ivy.flatten(x, start_dim = 1, end_dim = 2)
ivy.array(
    [[[ 5,  5,  0,  6],
      [17, 15, 11, 16],
      [ 6,  3, 13, 12],
      [ 6, 18, 10,  4],
      [ 5,  1, 17,  3],
      [14, 14, 18,  6]],
[[12, 0, 1, 13],

[ 8, 7, 0, 3], [19, 12, 6, 17], [ 4, 15, 6, 15], [ 0, 5, 17, 9], [ 9, 3, 6, 19]],

[[17, 13, 11, 16],

[ 4, 18, 17, 4], [10, 10, 9, 1], [19, 17, 13, 10], [ 4, 19, 16, 17], [ 2, 12, 8, 14]]]))

ivy.fliplr(m, /, *, copy=None, out=None)[source]#

Flip array in the left/right direction. Flip the entries in each column in the left/right direction. Columns are preserved, but appear in a different order than before.

Parameters:

  • m (Union[Array, NativeArray]) – The array to be flipped. Must be at least 2-D.

  • out (Optional[Union[Array, NativeArray]]) – optional output array, for writing the result to. (default: None)

Return type:

Union[Array, NativeArray]

Returns:

ret – Array corresponding to input array with elements order reversed along axis 1.

Examples

>>> m = ivy.diag([1, 2, 3])
>>> ivy.fliplr(m)
ivy.array([[0, 0, 1],
       [0, 2, 0],
       [3, 0, 0]])
ivy.flipud(m, /, *, copy=None, out=None)[source]#

Flip array in the up/down direction. Flip the entries in each column in the up/down direction. Rows are preserved, but appear in a different order than before.

Parameters:

  • m (Union[Array, NativeArray]) – The array to be flipped.

  • out (Optional[Union[Array, NativeArray]]) – optional output array, for writing the result to. (default: None)

Return type:

Union[Array, NativeArray]

Returns:

ret – Array corresponding to input array with elements order reversed along axis 0.

Examples

>>> m = ivy.diag([1, 2, 3])
>>> ivy.flipud(m)
ivy.array([[ 0.,  0.,  3.],
    [ 0.,  2.,  0.],
    [ 1.,  0.,  0.]])
ivy.heaviside(x1, x2, /, *, out=None)[source]#

Compute the Heaviside step function for each element in x1.

Parameters:

  • x1 (Union[Array, NativeArray]) – input array.

  • x2 (Union[Array, NativeArray]) – values to use where x1 is zero.

  • out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – output array with element-wise Heaviside step function of x1. This is a scalar if both x1 and x2 are scalars.

Examples

With ivy.Array input:

>>> x1 = ivy.array([-1.5, 0, 2.0])
>>> x2 = ivy.array([0.5])
>>> ivy.heaviside(x1, x2)
ivy.array([0.0000, 0.5000, 1.0000])

>>> x1 = ivy.array([-1.5, 0, 2.0])
>>> x2 = ivy.array([1.2, -2.0, 3.5])
>>> ivy.heaviside(x1, x2)
ivy.array([0., -2., 1.])
ivy.hsplit(ary, indices_or_sections, /, *, copy=None)[source]#

Split an array into multiple sub-arrays horizontally.

Parameters:

  • ary (Union[Array, NativeArray]) – Array input.

  • indices_or_sections (Union[int, Sequence[int], Array, NativeArray]) – If indices_or_sections is an integer n, the array is split into n equal sections, provided that n must be a divisor of the split axis. If indices_or_sections is a tuple of ints, then input is split at each of the indices in the tuple.

Return type:

List[Array]

Returns:

ret – input array split horizontally.

Examples

>>> ary = ivy.array(
        [[0.,  1., 2., 3.],
         [4.,  5., 6,  7.],
         [8.,  9., 10., 11.],
         [12., 13., 14., 15.]]
        )
>>> ivy.hsplit(ary, 2)
    [ivy.array([[ 0.,  1.],
                [ 4.,  5.],
                [ 8.,  9.],
                [12., 13.]]),
     ivy.array([[ 2.,  3.],
                [ 6.,  7.],
                [10., 11.],
                [14., 15.]])]
ivy.hstack(arrays, /, *, out=None)[source]#

Stack arrays in sequence horizotally (column wise).

Parameters:

arrays (Sequence[Array]) – Sequence of arrays to be stacked.

Return type:

Array

Returns:

ret – The array formed by stacking the given arrays.

Examples

>>> x = ivy.array([1, 2, 3])
>>> y = ivy.array([2, 3, 4])
>>> ivy.hstack((x, y))
ivy.array([1, 2, 3, 2, 3, 4])
>>> x = ivy.array([1, 2, 3])
>>> y = ivy.array([0, 0, 0])
>>> ivy.hstack((x, y, x))
ivy.array([1, 2, 3, 0, 0, 0, 1, 2, 3])
>>> y = [ivy.array([[5, 6]]), ivy.array([[7, 8]])]
>>> print(ivy.hstack(y))
ivy.array([[5, 6, 7, 8]])
ivy.i0(x, /, *, out=None)[source]#

Compute the Bessel i0 function of x element-wise.

Parameters:

  • x (Union[Array, NativeArray]) – Array input.

  • out (Optional[Array]) – optional output array, for writing the result to. (default: None)

Return type:

Array

Returns:

ret – Array with the modified Bessel function evaluated at each of the elements of x.

Examples

>>> x = ivy.array([1, 2, 3])
>>> ivy.i0(x)
ivy.array([1.26606588, 2.2795853 , 4.88079259])
ivy.moveaxis(a, source, destination, /, *, copy=None, out=None)[source]#

Move axes of an array to new positions..

Parameters:

  • a (Union[Array, NativeArray]) – The array whose axes should be reordered.

  • source (Union[int, Sequence[int]]) – Original positions of the axes to move. These must be unique.

  • destination (Union[int, Sequence[int]]) – Destination positions for each of the original axes. These must also be unique.

  • out (Optional[Union[Array, NativeArray]]) – optional output array, for writing the result to. (default: None)

Return type:

Union[Array, NativeArray]

Returns:

ret – Array with moved axes. This array is a view of the input array.

Examples

With ivy.Array input: >>> x = ivy.zeros((3, 4, 5)) >>> ivy.moveaxis(x, 0, -1).shape (4, 5, 3) >>> ivy.moveaxis(x, -1, 0).shape (5, 3, 4)

ivy.pad(input, pad_width, /, *, mode='constant', stat_length=1, constant_values=0, end_values=0, reflect_type='even', **kwargs)[source]#

Pad an array.

Parameters:

  • input (Union[Array, NativeArray]) – Input array to pad.

  • pad_width (Union[Iterable[Tuple[int]], int]) –

    Number of values padded to the edges of each axis.

    • ((before_1, after_1), … (before_N, after_N)) yields unique pad widths for each axis.

    • ((before, after),) yields same before and after pad for each axis.

    • pad (integer) is shortcut for before = after = pad width for all axes.

  • mode (Union[Literal[‘constant’, ‘dilated’, ‘edge’, ‘linear_ramp’, ‘maximum’, ‘mean’, ‘median’, ‘minimum’, ‘reflect’, ‘symmetric’, ‘wrap’, ‘empty’], Callable]) –

    (default: 'constant') One of the following string values or a user-supplied function.

    • ”constant”: Pads with a constant value.

    • ”edge”: Pads with the input’s edge values.

    • ”linear_ramp”: Pads with the linear ramp between end_value and the input’s edge value.

    • ”maximum”: Pads with the maximum value of all or part of the vector along each axis.

    • ”mean”: Pads with the mean value of all or part of the vector along each axis.

    • ”median”: Pads with the median value of all or part of the vector along each axis.

    • ”minimum”: Pads with the minimum value of all or part of the vector along each axis.

    • ”reflect”: Pads with the reflection mirrored on the first and last values of the vector along each axis.

    • ”symmetric”: Pads with the reflection of the vector mirrored along the edge of the input.

    • ”wrap”: Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning.

    • ”empty”: Pads with undefined values.

    • <function>: Pads with a user-defined padding function. The padding function should modify a rank 1 array following the signature padding_func(vector, iaxis_pad_width, iaxis, kwargs), where:

      • vector is a rank 1 array already padded with zeros. Padded values are vector[:iaxis_pad_width[0]] and vector[-iaxis_pad_width[1]:].

      • iaxis_pad_width is a 2-tuple of ints, where iaxis_pad_width[0] represents the number of values padded at the beginning of vector and iaxis_pad_width[1] represents the number of values padded at the end of vector.

      • iaxis is the axis currently being calculated.

      • kwargs is a dict of keyword arguments the function requires.

  • stat_length (Union[Iterable[Tuple[int]], int]) –

    Used in “maximum”, “mean”, “median”, and “minimum”. Number of values at edge (default: 1) of each axis used to calculate the statistic value.

    • ((before_1, after_1), … (before_N, after_N)) yields unique statistic lengths for each axis.

    • ((before, after),) yields same before and after statistic lengths for each axis.

    • stat_length (integer) is a shortcut for before = after = stat_length length for all axes.

    • None uses the entire axis.

  • constant_values (Union[Iterable[Tuple[Number]], Number]) –

    (default: 0) Used in “constant”. The values to set the padded values for each axis.

    • ((before_1, after_1), … (before_N, after_N)) yields unique pad constants for each axis.

    • ((before, after),) yields same before and after constants for each axis.

    • constant (integer) is a shortcut for before = after = constant for all axes.

  • end_values (Union[Iterable[Tuple[Number]], Number]) –

    Used in “linear_ramp”. The values used for the ending value of the linear_ramp (default: 0) and that will form the edge of the padded array.

    • ((before_1, after_1), … (before_N, after_N)) yields unique end values for each axis.

    • ((before, after),) yields same before and after end values for each axis

    • end (integer) is a shortcut for before = after = end for all axes.

  • reflect_type (Literal[‘even’, ‘odd’]) – Used in “reflect”, and “symmetric”. The “even” style is the default with an (default: 'even') unaltered reflection around the edge value. For the “odd” style, the extended part of the array is created by subtracting the reflected values from two times the edge value.

Return type:

Array

Returns:

ret – Padded array of the same rank as the input but with shape increased according to pad_width.

Both the description and the type hints above assume 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([[1, 2, 3], [4, 5, 6]])
>>> padding = ((1, 1), (2, 2))
>>> y = ivy.pad(x, padding, mode="constant", constant_values=0)
>>> print(y)
ivy.array([[0, 0, 0, 0, 0, 0, 0],
           [0, 0, 1, 2, 3, 0, 0],
           [0, 0, 4, 5, 6, 0, 0],
           [0, 0, 0, 0, 0, 0, 0]])

>>> x = ivy.array([[1, 2, 3], [4, 5, 6]])
>>> padding = ((1, 1), (2, 2))
>>> y = ivy.pad(x, padding, mode="reflect")
>>> print(y)
ivy.array([[6, 5, 4, 5, 6, 5, 4],
           [3, 2, 1, 2, 3, 2, 1],
           [6, 5, 4, 5, 6, 5, 4],
           [3, 2, 1, 2, 3, 2, 1]])

>>> x = ivy.array([[1, 2, 3], [4, 5, 6]])
>>> padding = ((1, 1), (2, 2))
>>> y = ivy.pad(x, padding, mode="symmetric")
>>> print(y)
ivy.array([[2, 1, 1, 2, 3, 3, 2],
           [2, 1, 1, 2, 3, 3, 2],
           [5, 4, 4, 5, 6, 6, 5],
           [5, 4, 4, 5, 6, 6, 5]])

With ivy.NativeArray input:

>>> x = ivy.native_array([[1, 2, 3], [4, 5, 6]])
>>> padding = ((1, 1), (2, 2))
>>> y = ivy.pad(x, padding, mode="constant", constant_values=7)
>>> print(y)
ivy.array([[7, 7, 7, 7, 7, 7, 7],
           [7, 7, 1, 2, 3, 7, 7],
           [7, 7, 4, 5, 6, 7, 7],
           [7, 7, 7, 7, 7, 7, 7]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([0, 1, 2]), b=ivy.array([4, 5, 6]))
>>> padding = (1, 1)
>>> y = ivy.pad(x, padding, mode="constant")
>>> print(y)
{
    a: ivy.array([0, 0, 1, 2, 0]),
    b: ivy.array([0, 4, 5, 6, 0])
}
ivy.rot90(m, /, *, copy=None, k=1, axes=(0, 1), out=None)[source]#

Rotate an array by 90 degrees in the plane specified by axes. Rotation direction is from the first towards the second axis.

Parameters:

  • m (Union[Array, NativeArray]) – Input array of two or more dimensions.

  • k (int) – Number of times the array is rotated by 90 degrees. (default: 1)

  • axes (Tuple[int, int]) – The array is rotated in the plane defined by the axes. Axes must be (default: (0, 1)) different.

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

Return type:

Array

Returns:

ret – A rotated view of m.

Examples

With ivy.Array input: >>> m = ivy.array([[1,2], [3,4]]) >>> ivy.rot90(m) ivy.array([[2, 4],

[1, 3]])

>>> m = ivy.array([[1,2], [3,4]])
>>> ivy.rot90(m, k=2)
ivy.array([[4, 3],
       [2, 1]])
>>> m = ivy.array([[[0, 1],                        [2, 3]],                       [[4, 5],                        [6, 7]]])
>>> ivy.rot90(m, k=2, axes=(1,2))
ivy.array([[[3, 2],
        [1, 0]],
[[7, 6],

[5, 4]]])

With ivy.NativeArray input: >>> m = ivy.native_array([[1,2], [3,4]]) >>> ivy.rot90(m) ivy.array([[2, 4],

[1, 3]])

>>> m = ivy.native_array([[1,2], [3,4]])
>>> ivy.rot90(m, k=2)
ivy.array([[4, 3],
       [2, 1]])
>>> m = ivy.native_array([[[0, 1],                               [2, 3]],                              [[4, 5],                               [6, 7]]])
>>> ivy.rot90(m, k=2, axes=(1,2))
ivy.array([[[3, 2],
        [1, 0]],
[[7, 6],

[5, 4]]])

ivy.take_along_axis(arr, indices, axis, /, *, mode='fill', out=None)[source]#

Take values from the input array by matching 1d index and data slices.

Parameters:

  • arr (Union[Array, NativeArray]) – The source array.

  • indices (Union[Array, NativeArray]) – The indices of the values to extract.

  • axis (int) – The axis over which to select values. If axis is None, arr is treated as a flattened 1D array.

  • mode (str) – One of: ‘clip’, ‘fill’, ‘drop’. Parameter controlling how out-of-bounds indices (default: 'fill') will be handled.

  • out (Optional[Array]) – The output array. (default: None)

Return type:

Array

Returns:

ret – The returned array has the same shape as indices.

Examples

>>> arr = ivy.array([[4, 3, 5], [1, 2, 1]])
>>> indices = ivy.array([[0, 1, 1], [2, 0, 0]])
>>> y = ivy.take_along_axis(arr, indices, 1)
>>> print(y)
ivy.array([[4, 3, 3], [1, 1, 1]])
ivy.top_k(x, k, /, *, axis=-1, largest=True, sorted=True, out=None)[source]#

Return the k largest elements of the given input array along a given axis.

Parameters:

  • x (Union[Array, NativeArray]) – The array to compute top_k for.

  • k (int) – Number of top elements to retun must not exceed the array size.

  • axis (int) – The axis along which we must return the top elements default value is 1. (default: -1)

  • largest (bool) – If largest is set to False we return k smallest elements of the array. (default: True)

  • sorted (bool) – If sorted is set to True we return the elements in sorted order. (default: True)

  • out (Optional[tuple]) – Optional output tuple, for writing the result to. Must have two arrays inside, (default: None) with a shape that the returned tuple broadcast to.

Return type:

Tuple[Array, NativeArray]

Returns:

ret – A named tuple with values and indices of top k elements.

Examples

With ivy.Array input:

>>> x = ivy.array([2., 1., -3., 5., 9., 0., -4])
>>> y = ivy.top_k(x, 2)
>>> print(y)
top_k(values=ivy.array([9., 5.]), indices=ivy.array([4, 3]))

>>> x = ivy.array([[-2., 3., 4., 0.], [-8., 0., -1., 2.]])
>>> y = ivy.top_k(x, 2, axis=1, largest=False)
>>> print(y)
top_k(values=ivy.array([[-2.,  0.],[-8., -1.]]),
...   indices=ivy.array([[0, 3],[0, 2]]))

With ivy.NativeArray input:

>>> x = ivy.native_array([2., 1., -3., 5., 9., 0., -4])
>>> y = ivy.top_k(x, 3)
>>> print(y)
top_k(values=ivy.array([9., 5., 2.]), indices=ivy.array([4, 3, 0]))

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([-1, 2, -4]), b=ivy.array([4., 5., 0.]))
>>> y = ivy.top_k(2)
>>> print(y)
{
    a: [
        values = ivy.array([ 2, -1]),
        indices = ivy.array([1, 0])
    ],
    b: [
        values = ivy.array([5., 4.]),
        indices = ivy.array([1, 0])
    ]
}
ivy.unique_consecutive(x, /, *, axis=None)[source]#

Eliminates all but the first element from every consecutive group of equivalent elements in x.

Parameters:

  • x (Union[Array, NativeArray]) – input array.

  • axis (Optional[int]) – the axis to apply unique on. If None, unique is applied on flattened x. (default: None)

Return type:

Tuple[Union[Array, NativeArray], Union[Array, NativeArray], Union[Array, NativeArray]]

Returns:

ret – a namedtuple (output, inverse_indices, counts) whose - first element has the field name output and is an array

containing x with its equivalent consecutive elements eliminated.

  • second element has the field name inverse_indices and is an array containing the indices of output that reconstruct x.

  • third element has the field name counts and is an array containing the number of occurrences for each unique value or array in x.

Examples

With ivy.Array input: >>> x = ivy.array([1, 1, 2, 2, 3, 1, 1, 2]) >>> ivy..unique_consecutive(x) Results(values=ivy.array([1, 2, 3, 1, 2]),

inverse_indices=ivy.array([0, 0, 1, 1, 2, 3, 3, 4]), counts=ivy.array([2, 2, 1, 2, 1]))

ivy.vsplit(ary, indices_or_sections, /, *, copy=None)[source]#

Split an array vertically into multiple sub-arrays.

Parameters:

  • ary (Union[Array, NativeArray]) – Array input.

  • indices_or_sections (Union[int, Sequence[int], Array, NativeArray]) – If indices_or_sections is an integer n, the array is split into n equal sections, provided that n must be a divisor of the split axis. If indices_or_sections is a sequence of ints or 1-D array, then input is split at each of the indices.

Return type:

List[Array]

Returns:

ret – input array split vertically.

Examples

>>> ary = ivy.array(
    [[[0.,  1.],
      [2.,  3.]],
     [[4.,  5.],
      [6.,  7.]]]
    )
>>> ivy.vsplit(ary, 2)
[ivy.array([[[0., 1.], [2., 3.]]]), ivy.array([[[4., 5.], [6., 7.]]])])
ivy.vstack(arrays, /, *, out=None)[source]#

Stack arrays in sequence vertically (row wise).

Parameters:

arrays (Sequence[Array]) – Sequence of arrays to be stacked.

Return type:

Array

Returns:

ret – The array formed by stacking the given arrays.

Examples

>>> x = ivy.array([1, 2, 3])
>>> y = ivy.array([2, 3, 4])
>>> ivy.vstack((x, y))
ivy.array([[1, 2, 3],
       [2, 3, 4]])
>>> ivy.vstack((x, y, x, y))
ivy.array([[1, 2, 3],
           [2, 3, 4],
           [1, 2, 3],
           [2, 3, 4]])

>>> y = [ivy.array([[5, 6]]), ivy.array([[7, 8]])]
>>> print(ivy.vstack(y))
ivy.array([[5, 6],
           [7, 8]])