Creation#

ivy.blackman_window(size, *, periodic=True, dtype=None, out=None)[source]#

Generate a Blackman window. The Blackman window is a taper formed by using the first three terms of a summation of cosines. It was designed to have close to the minimal leakage possible. It is close to optimal, only slightly worse than a Kaiser window.

Parameters:

  • window_length – the window_length of the returned window.

  • periodic (bool, default: True) – If True, returns a window to be used as periodic function. If False, return a symmetric window.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The data type to produce. Must be a floating point type.

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

Return type:

Array

Returns:

ret – The array containing the window.

Examples

>>> ivy.blackman_window(4, periodic = True)
ivy.array([-1.38777878e-17,  3.40000000e-01,  1.00000000e+00,  3.40000000e-01])
>>> ivy.blackman_window(7, periodic = False)
ivy.array([-1.38777878e-17,  1.30000000e-01,  6.30000000e-01,  1.00000000e+00,
    6.30000000e-01,  1.30000000e-01, -1.38777878e-17])
ivy.eye_like(x, *, k=0, dtype=None, device=None, out=None)[source]#

Return a 2D array filled with ones on the k diagonal and zeros elsewhere. having the same shape as the first and last dim of input array x. input array x should to be 2D.

Parameters:

  • x (Union[Array, NativeArray]) – input array from which to derive the output array shape.

  • k (int, default: 0) – index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and 0 to the main diagonal. Default: 0.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

  • device (Optional[Union[Device, NativeDevice]], default: None) – the device on which to place the created array.

  • 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 shape as x and filled with ones in diagonal k and zeros elsewhere.

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 as a replacement to any of the arguments.

Examples

With ivy.Array input:

>>> x1 = ivy.array([[0, 1],[2, 3]])
>>> y1 = ivy.eye_like(x1)
>>> print(y1)
ivy.array([[1., 0.],
           [0., 1.]])

>>> x1 = ivy.array([[0, 1, 2],[3, 4, 5],[6, 7, 8]])
>>> y1 = ivy.eye_like(x1, k=1)
>>> print(y1)
ivy.array([[0., 1., 0.],
           [0., 0., 1.],
           [0., 0., 0.]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([[3, 8],[0, 2]]), b=ivy.array([[0, 2], [8, 5]]))
>>> y = x.eye_like()
>>> print(y)
{
    a: ivy.array([[1., 0.],
                  [0., 1.]]),
    b: ivy.array([[1., 0.],
                  [0., 1.]])
}
ivy.hamming_window(window_length, *, periodic=True, alpha=0.54, beta=0.46, dtype=None, out=None)[source]#

Compute the Hamming window with window length window_length.

Parameters:

  • window_length (int) – an int defining the length of the window.

  • periodic (bool, default: True) – If True, returns a window to be used as periodic function. If False, return a symmetric window.

  • alpha (float, default: 0.54) – The coefficient alpha in the hamming window equation

  • beta (float, default: 0.46) – The coefficient beta in the hamming window equation

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

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

Return type:

Array

Returns:

ret – The array containing the window.

Examples

>>> ivy.hamming_window(5)
ivy.array([0.0800, 0.3979, 0.9121, 0.9121, 0.3979])
>>> ivy.hamming_window(5, periodic=False)
ivy.array([0.0800, 0.5400, 1.0000, 0.5400, 0.0800])
>>> ivy.hamming_window(5, periodic=False, alpha=0.2, beta=2)
ivy.array([-1.8000,  0.2000,  2.2000,  0.2000, -1.8000])
ivy.hann_window(size, *, periodic=True, dtype=None, out=None)[source]#

Generate a Hann window. The Hanning window is a taper formed by using a weighted cosine.

Parameters:

  • size (int) – the size of the returned window.

  • periodic (bool, default: True) – If True, returns a window to be used as periodic function. If False, return a symmetric window.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The data type to produce. Must be a floating point type.

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

Return type:

Array

Returns:

ret – The array containing the window.

Examples

>>> ivy.hann_window(4, periodic = True)
ivy.array([0. , 0.5, 1. , 0.5])

>>> ivy.hann_window(7, periodic = False)
ivy.array([0.  , 0.25, 0.75, 1.  , 0.75, 0.25, 0.  ])
ivy.indices(dimensions, *, dtype='int64', sparse=False)[source]#

Return an array representing the indices of a grid.

Parameters:

  • dimensions (Sequence[int]) – The shape of the grid.

  • dtype (Union[Dtype, NativeDtype], default: 'int64') – The data type of the result.

  • sparse (bool, default: False) – Return a sparse representation of the grid instead of a dense representation.

Return type:

Union[Array, Tuple[Array, ...]]

Returns:

ret – If sparse is False, returns one grid indices array of shape (len(dimensions),) + tuple(dimensions). If sparse is True, returns a tuple of arrays each of shape (1, …, 1, dimensions[i], 1, …, 1) with dimensions[i] in the ith place.

Examples

>>> ivy.indices((3, 2))
ivy.array([[[0 0]
            [1 1]
            [2 2]]
           [[0 1]
            [0 1]
            [0 1]]])
>>> ivy.indices((3, 2), sparse=True)
(ivy.array([[0], [1], [2]]), ivy.array([[0, 1]]))
ivy.kaiser_bessel_derived_window(window_length, beta=12.0, *, dtype=None, out=None)[source]#

Compute the Kaiser bessel derived window with window length window_length and shape beta.

Parameters:

  • window_length (int) – an int defining the length of the window.

  • beta (float, default: 12.0) – a float used as shape parameter for the window.

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

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

Return type:

Array

Returns:

ret – The array containing the window.

Examples

>>> ivy.kaiser_bessel_derived_window(5)
ivy.array([0.00726415, 0.9999736 , 0.9999736 , 0.00726415])

>>> ivy.kaiser_bessel_derived_window(5, 5)
ivy.array([0.18493208, 0.9827513 , 0.9827513 , 0.18493208])
ivy.kaiser_window(window_length, periodic=True, beta=12.0, *, dtype=None, out=None)[source]#

Compute the Kaiser window with window length window_length and shape beta.

Parameters:

  • window_length (int) – an int defining the length of the window.

  • periodic (bool, default: True) – If True, returns a periodic window suitable for use in spectral analysis. If False, returns a symmetric window suitable for use in filter design.

  • beta (float, default: 12.0) – a float used as shape parameter for the window.

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

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

Return type:

Array

Returns:

ret – The array containing the window.

Examples

>>> ivy.kaiser_window(5)
ivy.array([5.2773e-05, 1.0172e-01, 7.9294e-01, 7.9294e-01, 1.0172e-01]])
>>> ivy.kaiser_window(5, True, 5)
ivy.array([0.0367, 0.4149, 0.9138, 0.9138, 0.4149])
>>> ivy.kaiser_window(5, False, 5)
ivy.array([0.0367, 0.5529, 1.0000, 0.5529, 0.0367])
ivy.mel_weight_matrix(num_mel_bins, dft_length, sample_rate, lower_edge_hertz=0.0, upper_edge_hertz=3000.0)[source]#

Generate a MelWeightMatrix that can be used to re-weight a Tensor containing a linearly sampled frequency spectra (from DFT or STFT) into num_mel_bins frequency information based on the [lower_edge_hertz, upper_edge_hertz]

range on the mel scale. This function defines the mel scale in terms of a frequency in hertz according to the following formula: mel(f) = 2595 * log10(1 + f/700)

Parameters:

  • num_mel_bins (int) – The number of bands in the mel spectrum.

  • dft_length (int) – The size of the original DFT obtained from (n_fft / 2 + 1).

  • sample_rate (int) – Samples per second of the input signal.

  • lower_edge_hertz (float, default: 0.0) – Lower bound on the frequencies to be included in the mel spectrum.

  • upper_edge_hertz (float, default: 3000.0) – The desired top edge of the highest frequency band.

Returns:

ret – MelWeightMatrix of shape: [frames, num_mel_bins].

Examples

>>> ivy.mel_weight_matrix(3,3,8000)
ivy.array([[0.        ,0.        , 0.],
          [0.        ,0. , 0.75694758],
          [0.        ,0. , 0.       ]])
ivy.ndenumerate(input)[source]#

Multidimensional index iterator.

Parameters:

input (Iterable) – Input array to iterate over.

Return type:

Generator

Returns:

ret – An iterator yielding pairs of array coordinates and values.

Examples

>>> a = ivy.array([[1, 2], [3, 4]])
>>> for index, x in ivy.ndenumerate(a):
>>>     print(index, x)
(0, 0) 1
(0, 1) 2
(1, 0) 3
(1, 1) 4
ivy.ndindex(shape)[source]#

Multidimensional index iterator.

Parameters:

shape (Tuple) – The shape of the array to iterate over.

Return type:

Generator

Returns:

ret – An iterator yielding array coordinates.

Examples

>>> a = ivy.array([[1, 2], [3, 4]])
>>> for index in ivy.ndindex(a):
>>>     print(index)
(0, 0)
(0, 1)
(1, 0)
(1, 1)
ivy.polyval(coeffs, x)[source]#

Evaluate and return a polynomial at specific given values.

Parameters:

  • coeffs (Union[Array, NativeArray]) – Polynomial coefficients (including zero) from highest degree to constant term.

  • x (Union[Array, NativeArray]) – The value of the indeterminate variable at which to evaluate the polynomial.

Returns:

ret – Simplified result of substituing x in the coefficients - final value of polynomial.

Examples

>>> ivy.polyval([3, 0, 1], 5)
ivy.array(76)
ivy.random_cp(shape, rank, /, *, dtype=None, full=False, orthogonal=False, seed=None, normalise_factors=True)[source]#

Generate a random CP tensor.

Parameters:

  • shape (Sequence[int]) – shape of the tensor to generate

  • rank (int) – rank of the CP decomposition

  • full (Optional[bool], default: False) – if True, a full tensor is returned otherwise, the decomposed tensor is returned

  • orthogonal (Optional[bool], default: False) – if True, creates a tensor with orthogonal components

  • seed (Optional[int], default: None) – seed for generating random numbers

Return type:

Union[CPTensor, Array]

Returns:

ivy.CPTensor

ivy.random_parafac2(shapes, rank, /, *, dtype=None, full=False, seed=None, normalise_factors=True)[source]#

Generate a random PARAFAC2 tensor.

Parameters:

  • shapes (Sequence[int]) – A shapes of the tensor to generate

  • rank (int) – rank of the Parafac2 decomposition

  • full (Optional[bool], default: False) –

    if True, a full tensor is returned otherwise,

    the decomposed tensor is returned

    seed

    seed for generating random numbers

Return type:

Union[Parafac2Tensor, Array]

Returns:

ivy.Parafac2Tensor

ivy.random_tr(shape, rank, /, *, dtype=None, full=False, seed=None)[source]#

Generate a random TR tensor.

Parameters:

  • shape (tuple) – shape of the tensor to generate

  • rank (Sequence[int]) – rank of the TR decomposition must verify rank[0] == rank[-1] (boundary conditions) and len(rank) == len(shape)+1

  • full (bool, optional, default is False) – if True, a full tensor is returned otherwise, the decomposed tensor is returned

  • seed (Optional[int], default: None) – seed for generating random numbers

  • context (dict) – context in which to create the tensor

Return type:

Union[TRTensor, Array]

Returns:

ivy.TRTensor or ivy.Array if full is True

ivy.random_tt(shape, rank, /, *, full=False, dtype=None, seed=None)[source]#

Generate a random TT/MPS tensor.

Parameters:

  • shape (Sequence[int]) – shape of the tensor to generate

  • rank (Union[Sequence[int], int]) – rank of the TT decomposition must verify rank[0] == rank[-1] ==1 (boundary conditions) and len(rank) == len(shape)+1

  • full (Optional[bool], default: False) – if True, a full tensor is returned otherwise, the decomposed tensor is returned

  • seed (Optional[int], default: None) – seed for generating random numbers

Return type:

Union[TTTensor, Array]

Returns:

ivy.TTTensor

ivy.random_tucker(shape, rank, /, *, dtype=None, full=False, orthogonal=False, seed=None, non_negative=False)[source]#

Generate a random Tucker tensor.

Parameters:

  • shape (Sequence[int]) – shape of the tensor to generate

  • rank (Sequence[int]) – rank of the Tucker decomposition if int, the same rank is used for each mode otherwise, dimension of each mode

  • full (Optional[bool], default: False) – if True, a full tensor is returned otherwise, the decomposed tensor is returned

  • orthogonal (Optional[bool], default: False) – if True, creates a tensor with orthogonal components

  • seed (Optional[int], default: None) – seed for generating random numbers

  • non_negative (Optional[bool], default: False) –

Return type:

Union[TuckerTensor, Array]

Returns:

ivy.TuckerTensor

ivy.tril_indices(n_rows, n_cols=None, k=0, *, device=None)[source]#

Return the indices of the lower triangular part of a row by col matrix in a 2-by-N shape (tuple of two N dimensional arrays), where the first row contains row coordinates of all indices and the second row contains column coordinates. Indices are ordered based on rows and then columns. The lower triangular part of the matrix is defined as the elements on and below the diagonal. The argument k controls which diagonal to consider. If k = 0, all elements on and below the main diagonal are retained. A positive value excludes just as many diagonals below the main diagonal, and similarly a negative value includes just as many diagonals above the main diagonal. The main diagonal are the set of indices {(i,i)} for i∈[0,min{n_rows, n_cols}−1].

Notes

Primary purpose of this function is to slice an array of shape (n,m). See https://numpy.org/doc/stable/reference/generated/numpy.tril_indices.html for examples

Tensorflow does not support slicing 2-D tensor with tuple of tensor of indices

Parameters:

  • n_rows (int) – number of rows in the 2-d matrix.

  • n_cols (Optional[int], default: None) – number of columns in the 2-d matrix. If None n_cols will be the same as n_rows

  • k (int, default: 0) – number of shifts from the main diagonal. k = 0 includes main diagonal, k > 0 moves downward and k < 0 moves upward

  • device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.

Return type:

Tuple[Array, ...]

Returns:

  • ret – an 2xN shape, tuple of two N dimensional, where first subarray (i.e. ret[0]) contains row coordinates of all indices and the second subarray (i.e ret[1]) contains columns indices.

  • Function is nestable, and therefore also accepts ivy.Container

  • instances in place of any of the arguments.

Examples

>>> x = ivy.tril_indices(4,4,0)
>>> print(x)
(ivy.array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]),
ivy.array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3]))

>>> x = ivy.tril_indices(4,4,1)
>>> print(x)
(ivy.array([0, 0, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3]),
ivy.array([0, 1, 0, 1, 2, 0, 1, 2, 3, 0, 1, 2, 3]))

>>> x = ivy.tril_indices(4,4,-2)
>>> print(x)
(ivy.array([2, 3, 3]), ivy.array([0, 0, 1]))

>>> x = ivy.tril_indices(4,2,0)
>>> print(x)
(ivy.array([0, 1, 1, 2, 2, 3, 3]),
ivy.array([0, 0, 1, 0, 1, 0, 1]))

>>> x = ivy.tril_indices(2,4,0)
>>> print(x)
(ivy.array([0, 1, 1]), ivy.array([0, 0, 1]))

>>> x = ivy.tril_indices(4,-4,0)
>>> print(x)
(ivy.array([]), ivy.array([]))

>>> x = ivy.tril_indices(4,4,100)
>>> print(x)
(ivy.array([0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3]),
ivy.array([0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3]))

>>> x = ivy.tril_indices(2,4,-100)
>>> print(x)
(ivy.array([]), ivy.array([]))
ivy.trilu(x, /, *, k=0, upper=True, out=None)[source]#

Return the upper or lower triangular part of a matrix (or a stack of matrices) x.

note::

The upper triangular part of the matrix is defined as the elements on and above the specified diagonal k. The lower triangular part of the matrix is defined as the elements on and below the specified diagonal k.

Parameters:

  • x (Union[Array, NativeArray]) – input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices. *,

  • k (int, default: 0) – diagonal below or above which to zero elements. If k = 0, the diagonal is the main diagonal. If k < 0, the diagonal is below the main diagonal. If k > 0, the diagonal is above the main diagonal. Default: 0.

  • upper (bool, default: True) – indicates whether upper or lower part of matrix is retained. Default: True.

  • 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 containing the upper or lower triangular part(s). The returned array must have the same shape and data type as x. All elements below or above the specified diagonal k must be zeroed. The returned array should be allocated on the same device as x.

  • 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.

ivy.unsorted_segment_mean(data, segment_ids, num_segments)[source]#

Compute the mean of elements along segments of an array. Segments are defined by an integer array of segment IDs.

Parameters:

  • data (Union[ivy.Array, ivy.NativeArray]) – The array from which to gather values.

  • segment_ids (Union[ivy.Array, ivy.NativeArray]) – Must be in the same size with the first dimension of data. Has to be of integer data type. The index-th element of segment_ids array is the segment identifier for the index-th element of data.

  • num_segments (Union[int, ivy.Array, ivy.NativeArray]) – An integer or array representing the total number of distinct segment IDs.

Return type:

Array

Returns:

ivy.Array – The output array, representing the result of a segmented mean operation. For each segment, it computes the mean value in data where segment_ids equals to segment ID.

ivy.unsorted_segment_min(data, segment_ids, num_segments)[source]#

Compute the minimum along segments of an array. Segments are defined by an integer array of segment IDs.

Note

If the given segment ID i is negative, then the corresponding value is dropped, and will not be included in the result.

Parameters:

  • data (Union[Array, NativeArray]) – The array from which to gather values.

  • segment_ids (Union[Array, NativeArray]) – Must be in the same size with the first dimension of data. Has to be of integer data type. The index-th element of segment_ids array is the segment identifier for the index-th element of data.

  • num_segments (Union[int, Array, NativeArray]) – An integer or array representing the total number of distinct segment IDs.

Return type:

Array

Returns:

ret – The output array, representing the result of a segmented min operation. For each segment, it computes the min value in data where segment_ids equals to segment ID.

ivy.unsorted_segment_sum(data, segment_ids, num_segments)[source]#

Compute the sum of elements along segments of an array. Segments are defined by an integer array of segment IDs.

Parameters:

  • data (Union[Array, NativeArray]) – The array from which to gather values.

  • segment_ids (Union[Array, NativeArray]) – Must be in the same size with the first dimension of data. Has to be of integer data type. The index-th element of segment_ids array is the segment identifier for the index-th element of data.

  • num_segments (Union[int, Array, NativeArray]) – An integer or array representing the total number of distinct segment IDs.

Return type:

Array

Returns:

ret – The output array, representing the result of a segmented sum operation. For each segment, it computes the sum of values in data where segment_ids equals to segment ID.

ivy.vorbis_window(window_length, *, dtype=None, out=None)[source]#

Return an array that contains a vorbis power complementary window of size window_length.

Parameters:

  • window_length (Union[Array, NativeArray]) – the length of the vorbis window.

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

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

Return type:

Array

Returns:

ret – Input array with the vorbis window.

Examples

>>> ivy.vorbis_window(3)
ivy.array([0.38268346, 1. , 0.38268352])

>>> ivy.vorbis_window(5)
ivy.array([0.14943586, 0.8563191 , 1. , 0.8563191, 0.14943568])