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, default: False) – Whether to scan in reverse with respect to the given axis.

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

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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.choose(arr, choices, /, *, out=None, mode=None)[source]#

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

Parameters:

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

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

  • out (None, default: None) – The output array.

  • mode (Optional[str], default: None) – One of: ‘wrap’, ‘clip’. Parameter controlling how out-of-bounds indices will be handled.

Return type:

Array

Returns:

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

Examples

>>> choices = ivy.array([[0, 1, 2, 3], [10, 11, 12, 13],
                    [20, 21, 22, 23], [30, 31, 32, 33]])
>>> print(choose(ivy.array([2, 3, 1, 0]), choices))
ivy.array([20, 31, 12, 3])
>>> arr = ivy.array([2, 4, 1, 0])
>>> print(choose(arr, choices, mode='clip')) # 4 goes to 3 (4-1)
ivy.array([20, 31, 12, 3])
>>> arr = ivy.array([2, 4, 1, 0])
>>> print(choose(arr, choices, mode='wrap')) # 4 goes to (4 mod 4)
ivy.array([20, 1, 12, 3])
ivy.column_stack(arrays, /, *, out=None)[source]#

Create a new array by horizontally stacking the arrays in arrays.

Equivalent to ivy.hstack(arrays), except each zero or one dimensional array x in arrays is first reshaped into a (x.size(), 1) column before being stacked horizontally.

Parameters:

  • arrays (Sequence[Union[Array, NativeArray]]) – Arrays to be stacked.

  • out (Optional[Array], default: None) – Output array.

Return type:

Array

Returns:

ret – Stacked input.

Examples

Arrays of different dtypes up to dimension 2. >>> a0 = ivy.array(True) >>> a1 = ivy.array([7]) >>> a2 = ivy.array([[11.3, 13.7]]) >>> ivy.column_stack((a0, a1, a2)) ivy.array([[ 1. , 7. , 11.30000019, 13.69999981]])

Arrays of dimension 3. >>> a = ivy.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]) >>> b = ivy.array([[[11, 12]], [[13, 14]]]) >>> ivy.column_stack((a, b)) ivy.array([[[ 1, 2],

[ 3, 4], [11, 12]],

[[ 5, 6],

[ 7, 8], [13, 14]]])

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, default: 0) – Insert and concatenate on a new axis or not, default 0 means do not insert new axis. new_axis = 0: concatenate new_axis = 1: stack

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

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

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

Return type:

Array

Returns:

ret – Output Array

ivy.fill_diagonal(a, v, /, *, wrap=False)[source]#

Fill the main diagonal of the given array of any dimensionality..

Parameters:

  • a (Union[Array, NativeArray]) – Array at least 2D.

  • v (Union[int, float, Array, NativeArray]) – Value(s) to write on the diagonal. If val is scalar, the value is written along the diagonal. If array-like, the flattened val is written along the diagonal, repeating if necessary to fill all diagonal entries.

  • wrap (bool, default: False) – The diagonal ‘wrapped’ after N columns for tall matrices.

Return type:

Union[Array, NativeArray]

Returns:

ret – Array with the diagonal filled.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

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

  • order (Optional[str], default: 'C') – Read the elements of the input container using this index order, 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], default: None) – optional output array, for writing the result to.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

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.fold(x, /, mode, shape, *, out=None)[source]#

Refolds the mode-mode unfolding into a tensor of shape shape In other words, refolds the n-mode unfolded tensor into the original tensor of the specified shape.

Parameters:

  • input – unfolded tensor of shape (shape[mode], -1)

  • mode (int) – the mode of the unfolding

  • shape (Union[Shape, NativeShape, Sequence[int]]) – shape of the original tensor before unfolding

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

Return type:

Array

Returns:

ret – folded_tensor of shape shape

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], default: None) – optional output array, for writing the result to.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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], default: None) – optional output array, for writing the result to.

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.matricize(x, /, row_modes, column_modes=None, *, out=None)[source]#

Matricizes the given tensor.

Parameters:

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

  • row_modes (Sequence[int]) – modes to use as row of the matrix (in the desired order)

  • column_modes (Optional[Sequence[int]], default: None) – modes to use as column of the matrix, in the desired order if None, the modes not in row_modes will be used in ascending order

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

  • ret –

  • ------- – ivy.Array : tensor of size (ivy.prod(x.shape[i] for i in row_modes), -1)

Return type:

Array

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

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], default: 1) –

    Used in “maximum”, “mean”, “median”, and “minimum”. Number of values at edge 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], default: 0) –

    Used in “linear_ramp”. The values used for the ending value of the linear_ramp 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'], default: 'even') – Used in “reflect”, and “symmetric”. The “even” style is the default with an 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.partial_fold(x, /, mode, shape, skip_begin=1, *, out=None)[source]#

Re-folds a partially unfolded tensor.

Parameters:

  • x (Union[Array, NativeArray]) – a partially unfolded tensor

  • mode (int) – indexing starts at 0, therefore mode is in range(0, tensor.ndim)

  • shape (Union[Shape, NativeShape, Sequence[int]]) – the shape of the original full tensor (including skipped dimensions)

  • skip_begin (Optional[int], default: 1) – number of dimensions left untouched at the beginning

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

Return type:

Array

Returns:

ret – partially re-folded tensor

ivy.partial_tensor_to_vec(x, /, skip_begin=1, skip_end=0, *, out=None)[source]#

Partial vectorization of a tensor while ignoring the specified dimension at the beginning and the end.

Parameters:

  • x (Union[Array, NativeArray]) – tensor to partially vectorise

  • skip_begin (Optional[int], default: 1) – number of dimensions to leave untouched at the beginning

  • skip_end (Optional[int], default: 0) – number of dimensions to leave untouched at the end

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

Return type:

Array

Returns:

ret – partially vectorised tensor with the skip_begin first and skip_end last dimensions untouched

ivy.partial_unfold(x, /, mode=0, skip_begin=1, skip_end=0, ravel_tensors=False, *, out=None)[source]#

Partial unfolding of a tensor while ignoring the specified number of dimensions at the beginning and the end. For instance, if the first dimension of the tensor is the number of samples, to unfold each sample, set skip_begin=1. This would, for each i in range(tensor.shape[0]), unfold tensor[i, ...].

Parameters:

  • x (Union[Array, NativeArray]) – tensor of shape n_samples x n_1 x n_2 x … x n_i

  • mode (Optional[int], default: 0) – indexing starts at 0, therefore mode is in range(0, tensor.ndim)

  • skip_begin (Optional[int], default: 1) – number of dimensions to leave untouched at the beginning

  • skip_end (Optional[int], default: 0) – number of dimensions to leave untouched at the end

  • ravel_tensors (Optional[bool], default: False) – if True, the unfolded tensors are also flattened

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

Return type:

Array

Returns:

ret – partially unfolded tensor

ivy.partial_vec_to_tensor(x, /, shape, skip_begin=1, *, out=None)[source]#

Refolds a partially vectorised tensor into a full one.

Parameters:

  • x (Union[Array, NativeArray]) – a partially vectorised tensor

  • shape (Union[Shape, NativeShape, Sequence[int]]) – the shape of the original full tensor (including skipped dimensions)

  • skip_begin (Optional[int], default: 1) – number of dimensions to leave untouched at the beginning

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

Return type:

Array

Returns:

ret – full tensor

ivy.put_along_axis(arr, indices, values, axis, /, *, mode='replace', out=None)[source]#

Put values into the input array by matching 1d index and data slices along a specified axis.

Parameters:

  • arr (array_like) – The input array to modify.

  • indices (array_like) – The indices of the values to put into arr.

  • values (array_like) – The values to put into arr.

  • axis (int) – The axis over which to put the values.

  • mode ({'sum', 'min', 'max', 'mul', 'replace'}) – The reduction operation to apply.

  • out (ndarray, optional) – Output array in which to place the result. If not specified, a new array is created.

Note

In case indices contains duplicates, the updates get accumulated in each place.

Return type:

None

Returns:

None

Examples

>>> arr = ivy.array([[4, 3, 5], [1, 2, 1]])
>>> indices = ivy.array([[0, 1, 1], [2, 0, 0]])
>>> values = ivy.array([[9, 8, 7], [6, 5, 4]])
>>> ivy.put_along_axis(arr, indices, values, 1, mode='replace')
>>> print(arr)
ivy.array([[9, 7, 5],
           [4, 2, 6]])

>>> arr = ivy.array([[10, 30, 20], [60, 40, 50]])
>>> axis = 1
>>> indices = ivy.argmax(arr, axis=axis, keepdims=True)
>>> value = 100
>>> ivy.put_along_axis(arr, indices, value, axis, mode='add')
>>> print(arr)
ivy.array([[ 10, 130, 20],
           [ 160, 40, 50]])
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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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

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

  • out (Optional[Array], default: None) – optional output container, for writing the result to. It must have a shape 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.soft_thresholding(x, /, threshold, *, out=None)[source]#

Soft-thresholding operator.

sign(tensor) * max[abs(tensor) - threshold, 0]

Parameters:

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

  • threshold (Union[float, Array, NativeArray]) – float or array with shape tensor.shape * If float the threshold is applied to the whole tensor * If array, one threshold is applied per elements, 0 values are ignored

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

Return type:

Array

Returns:

ivy.Array – thresholded tensor on which the operator has been applied

Examples

Basic shrinkage

>>> x = ivy.array([[1, -2, 1.5], [-4, 3, -0.5]])
>>> soft_thresholding(x, 1.1)
array([[ 0. , -0.9,  0.4],
       [-2.9,  1.9,  0. ]])

Example with missing values

>>> mask = ivy.array([[0, 0, 1], [1, 0, 1]])
>>> soft_thresholding(x, mask*1.1)
array([[ 1. , -2. ,  0.4],
       [-2.9,  3. ,  0. ]])
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, default: 'fill') – One of: ‘clip’, ‘fill’, ‘drop’. Parameter controlling how out-of-bounds indices will be handled.

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

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, default: -1) – The axis along which we must return the top elements default value is 1.

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

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

  • out (Optional[tuple], default: None) – Optional output tuple, for writing the result to. Must have two arrays inside, 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 = x.top_k(2)
>>> print(y)
[{
    a: ivy.array([2, -1]),
    b: ivy.array([5., 4.])
}, {
    a: ivy.array([1, 0]),
    b: ivy.array([1, 0])
}]
ivy.unfold(x, /, mode=0, *, out=None)[source]#

Return the mode-mode unfolding of tensor with modes starting at 0.

Parameters:

  • x (Union[Array, NativeArray]) – input tensor to be unfolded

  • mode (Optional[int], default: 0) – indexing starts at 0, therefore mode is in range(0, tensor.ndim)

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

Return type:

Array

Returns:

ret – unfolded_tensor of shape (tensor.shape[mode], -1)

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], default: None) – the axis to apply unique on. If None, unique is applied on flattened x.

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.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

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]])