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 at least 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 at least 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.check_scalar(x, force_integer, force_positive)[source]#
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(ivy.choose(choices, ivy.array([2, 3, 1, 0]))
ivy.array([20, 31, 12, 3])
>>> arr = ivy.array([2, 4, 1, 0])
>>> print(ivy.choose(choices, arr, mode='clip')) # 4 goes to 3 (4-1)
ivy.array([20, 31, 12, 3])
>>> arr = ivy.array([2, 4, 1, 0])
>>> print(ivy.choose(choices, arr, 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 (int, default: 0) – first dim to flatten. If not set, defaults to 0.

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

  • order (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 (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 (int, default: 1) – number of dimensions to leave untouched at the beginning

  • skip_end (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 (int, default: 0) – indexing starts at 0, therefore mode is in range(0, tensor.ndim)

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

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

  • ravel_tensors (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 (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='sum')
>>> print(arr)
ivy.array([[10, 30, 20],
          [60, 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(x, indices, /, *, axis=None, mode='fill', fill_value=None, out=None)[source]#

Return elements of an array along an axis.

Note

Conceptually, take(x, indices, axis=3) is equivalent to x[:,:,:,indices,…]; however, explicit indexing via arrays of indices is not currently supported in this specification due to concerns regarding __setitem__ and array mutation semantics.

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

  • indices (Union[int, Array, NativeArray]) – array indices. Must have an integer data type.

  • axis (Optional[int], default: None) – axis over which to select values. If axis is negative, the function must determine the axis along which to select values by counting from the last dimension. By default, the flattened input array is used.

  • mode (str, default: 'fill') – specifies how out-of-bounds indices will behave. - ‘raise’ – raise an error - ‘wrap’ – wrap around - ‘clip’ – clip to the range (all indices that are too large are replaced by the index that addresses the last element along that axis. Note that this disables indexing with negative numbers.) - ‘fill’ (default) = returns invalid values (e.g. NaN) for out-of bounds indices (see also fill_value below)

  • fill_value (Optional[Number], default: None) – fill value to return for out-of-bounds slices (Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.)

  • 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 having the same data type as x. The output array must have the same rank (i.e., number of dimensions) as x and must have the same shape as x, except for the axis specified by axis whose size must equal the number of elements in indices.

  • This function conforms to the `Array API Standard

  • <https (//data-apis.org/array-api/latest/>`_. This docstring is an extension of the)

  • `docstring <https (//data-apis.org/array-api/latest/)

  • API_specification/generated/array_api.max.html>`_

  • 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([4,5,6])
>>> indices = ivy.array([2,1,0])
>>> y = ivy.take(x, indices)
>>> print(y)
ivy.array([6, 5, 4])
>>> x = ivy.array([4.7,5.2,6.5])
>>> indices = ivy.array([[0,1]])
>>> y = ivy.zeros_like(indices, dtype=x.dtype)
>>> ivy.take(x, indices, out=y)
>>> print(y)
ivy.array([[4.7, 5.2]])
>>> x = ivy.array([False, False, True])
>>> indices = ivy.array([[4,3,2]])
>>> y = ivy.zeros_like(indices, dtype=x.dtype)
>>> ivy.take(x, indices, out=y, mode="wrap")
>>> print(y)
ivy.array([[False, False, True]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([True,False,False]),
...                     b=ivy.array([2.3,4.5,6.7]),
...                     c=ivy.array([1,2,3]))
>>> indices = ivy.array([[1,9,2]])
>>> y = ivy.take(x, indices)
>>> print(y)
{
    a: ivy.array([[False, True, False]]),
    b: ivy.array([[4.5, nan, 6.69999981]]),
    c: ivy.array([[2, -2147483648, 3]])
}
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 return 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.trim_zeros(a, /, *, trim='fb')[source]#

ivy.Container instance method variant of ivy.trim_zeros. This method simply wraps the function, and so the docstring for ivy.trim_zeros also applies to this method with minimal changes.

Parameters:
  • a (1-D array) – Input array.

  • trim (str, optional) – A string with ‘f’ representing trim from front and ‘b’ to trim from back. Default is ‘fb’, trim zeros from both front and back of the array.

Return type:

Array

Returns:

1-D array The result of trimming the input. The input data type is preserved.

Examples

>>> a = ivy.array([0, 0, 0, 0, 8, 3, 0, 0, 7, 1, 0])
>>> ivy.trim_zeros(a)
array([8, 3, 0, 0, 7, 1])
>>> ivy.trim_zeros(a, 'b')
array([0, 0, 0, 0, 8, 3, 0, 0, 7, 1])
>>> ivy.trim_zeros([0, 8, 3, 0, 0])
[8, 3]
ivy.unflatten(x, /, dim, shape, *, out=None)[source]#

Expand a dimension of the input tensor over multiple dimensions.

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

  • dim (int) – dimension to be unflattened, specified as an index into input.shape.

  • shape (Tuple[int]) – new shape of the unflattened dimension. One of its elements can be -1 in which case the corresponding output dimension is inferred. Otherwise, the product of sizes must equal input.shape[dim].

  • 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 – view of input with the specified dimension unflattened.

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

>>> ivy.unflatten(torch.randn(3, 4, 1), dim=1, shape=(2, 2)).shape
torch.Size([3, 2, 2, 1])
>>> ivy.unflatten(torch.randn(3, 4, 1), dim=1, shape=(-1, 2)).shape
torch.Size([3, 2, 2, 1])
>>> ivy.unflatten(torch.randn(5, 12, 3), dim=-2, shape=(2, 2, 3, 1, 1)).shape
torch.Size([5, 2, 2, 3, 1, 1, 3])
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 (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]])