Ctrl+K

Linear algebra#

ivy.adjoint(x, /, *, out=None)[source]#

Compute the complex conjugate transpose of x.

Parameters:

  • x (Union[Array, NativeArray]) – An array with more than one dimension.

  • 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 – the complex conjugate transpose of the input.

Examples

>>> x = np.array([[1.-1.j, 2.+2.j],
                  [3.+3.j, 4.-4.j]])
>>> x = ivy.array(x)
>>> ivy.adjoint(x)
ivy.array([[1.+1.j, 3.-3.j],
           [2.-2.j, 4.+4.j]])
ivy.batched_outer(tensors, /, *, out=None)[source]#

Return a generalized outer product of the tensors.

Parameters:

tensors (Sequence[Union[Array, NativeArray]]) – list of tensors of shape (n_samples, J1, …, JN) , (n_samples, K1, …, KM) …

Return type:

Array

Returns:

outer product of tensors – of shape (n_samples, J1, …, JN, K1, …, KM, …)

Examples

>>> a = ivy.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
>>> b = ivy.array([[[.1, .2], [.3, .4]], [[.5, .6], [.7, .8]]])
>>> result = ivy.batched_outer([a, b])
>>> print(result)
ivy.array([[[[[0.1, 0.2],
      [0.30000001, 0.40000001]],
     [[0.2       , 0.40000001],
      [0.60000002, 0.80000001]]],
    [[[0.3       , 0.60000001],
      [0.90000004, 1.20000002]],
     [[0.40000001, 0.80000001],
      [1.20000005, 1.60000002]]]],
   [[[[2.5       , 3.00000012],
      [3.49999994, 4.00000006]],
     [[3.        , 3.60000014],
      [4.19999993, 4.80000007]]],
    [[[3.5       , 4.20000017],
      [4.89999992, 5.60000008]],
     [[4.        , 4.80000019],
      [5.5999999 , 6.4000001 ]]]]])
ivy.cond(x, /, *, p=None, out=None)[source]#

Compute the condition number of x.

Parameters:

  • x (Union[Array, NativeArray]) – An array with more than one dimension.

  • p (Optional[Union[int, float, str]], default: None) – The order of the norm of the matrix (see ivy.norm() for details).

  • 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 – the condition number of the input.

Examples

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

>>> x = ivy.array([[1., 2.],
...                     [3., 4.]])
>>> ivy.cond(x, p=ivy.inf)
    ivy.array(21.0)
ivy.diagflat(x, /, *, offset=0, padding_value=0, align='RIGHT_LEFT', num_rows=-1, num_cols=-1, out=None)[source]#

Return a two-dimensional array with the flattened input as a diagonal.

Parameters:

  • x (Union[Array, NativeArray]) – Input data, which is flattened and set as the k-th diagonal of the output.

  • k – Diagonal to set. Positive value means superdiagonal, 0 refers to the main diagonal, and negative value means subdiagonal.

  • out (Optional[Union[Array, NativeArray]], 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 – The 2-D output array.

Examples

With ivy.Array inputs:

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

>>> x = ivy.array([1,2])
>>> ivy.diagflat(x, k=1)
ivy.array([[0, 1, 0],
           [0, 0, 2],
           [0, 0, 0]])
ivy.dot(a, b, /, *, out=None)[source]#

Compute the dot product between two arrays a and b using the current backend’s implementation. The dot product is defined as the sum of the element-wise product of the input arrays.

Parameters:

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

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

  • out (Optional[Array], default: None) – Optional output array. If provided, the output array to store the result.

Return type:

Array

Returns:

ret – The dot product of the input arrays.

Examples

With ivy.Array inputs:

>>> a = ivy.array([1, 2, 3])
>>> b = ivy.array([4, 5, 6])
>>> result = ivy.dot(a, b)
>>> print(result)
ivy.array(32)

>>> a = ivy.array([[1, 2], [3, 4]])
>>> b = ivy.array([[5, 6], [7, 8]])
>>> c = ivy.empty_like(a)
>>> ivy.dot(a, b, out=c)
>>> print(c)
ivy.array([[19, 22],
       [43, 50]])

>>> a = ivy.array([[1.1, 2.3, -3.6]])
>>> b = ivy.array([[-4.8], [5.2], [6.1]])
>>> c = ivy.zeros((1, 1))
>>> ivy.dot(a, b, out=c)
>>> print(c)
ivy.array([[-15.28]])
ivy.eig(x, /, *, out=None)[source]#

Return an eigendecomposition x = QLQᵀ of a symmetric matrix (or a stack of symmetric matrices) x, where Q is an orthogonal matrix (or a stack of matrices) and L is a vector (or a stack of vectors).

Note

The function eig currently behaves like eigh, as it requires complex number support, once complex numbers are supported, x does not need to be a complex Hermitian or real symmetric matrix.

Parameters:

x (Union[Array, NativeArray]) – input array having shape (..., M, M) and whose innermost two dimensions form square matrices. Must have a floating-point data type.

Return type:

Tuple[Union[Array, NativeArray]]

Returns:

  • ret – a namedtuple (eigenvalues, eigenvectors) whose

    • first element must have the field name eigenvalues (corresponding to L above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape (..., M).

    • second element have have the field name eigenvectors (corresponding to Q above) and must be an array where the columns of the inner most matrices contain the computed eigenvectors. These matrices must be orthogonal. The array containing the eigenvectors must have shape (..., M, M).

    • Each returned array must have the same floating-point data type as x.

  • .. note:: – Eigenvalue sort order is left unspecified and is thus implementation-dependent.

ivy.eigh_tridiagonal(alpha, beta, /, *, eigvals_only=True, select='a', select_range=None, tol=None)[source]#

Compute the eigenvalues and eigenvectors of a Hermitian tridiagonal matrix.

Parameters:

  • alpha (Union[Array, NativeArray]) – A real or complex array of shape (n), the diagonal elements of the matrix. If alpha is complex, the imaginary part is ignored (assumed zero) to satisfy the requirement that the matrix be Hermitian.

  • beta (Union[Array, NativeArray]) – A real or complex array of shape (n-1), containing the elements of the first super-diagonal of the matrix. If beta is complex, the first sub-diagonal of the matrix is assumed to be the conjugate of beta to satisfy the requirement that the matrix be Hermitian.

  • eigvals_only (bool, default: True) – If False, both eigenvalues and corresponding eigenvectors are computed. If True, only eigenvalues are computed. Default is True.

  • select (str, default: 'a') – Optional string with values in {‘a’, ‘v’, ‘i’} (default is ‘a’) that determines which eigenvalues to calculate: ‘a’: all eigenvalues. ‘v’: eigenvalues in the interval (min, max] given by select_range. ‘i’: eigenvalues with indices min <= i <= max.

  • select_range (Optional[Union[Tuple[int, int], List[int], Array, NativeArray]], default: None) – Size 2 tuple or list or array specifying the range of eigenvalues to compute together with select. If select is ‘a’, select_range is ignored.

  • tol (Optional[float], default: None) – Optional scalar. Ignored when backend is not Tensorflow. The absolute tolerance to which each eigenvalue is required. An eigenvalue (or cluster) is considered to have converged if it lies in an interval of this width. If tol is None (default), the value eps*|T|_2 is used where eps is the machine precision, and |T|_2 is the 2-norm of the matrix T.

Return type:

Union[Array, Tuple[Array, Array]]

Returns:

  • eig_vals – The eigenvalues of the matrix in non-decreasing order.

  • eig_vectors – If eigvals_only is False the eigenvectors are returned in the second output argument.

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

>>> alpha = ivy.array([0., 1., 2.])
>>> beta = ivy.array([0., 1.])
>>> y = ivy.eigh_tridiagonal(alpha, beta)
>>> print(y)
ivy.array([0., 0.38196602, 2.61803389])

>>> alpha = ivy.array([0., 1., 2.])
>>> beta = ivy.array([0., 1.])
>>> y = ivy.eigh_tridiagonal(alpha,
...     beta, select='v',
...     select_range=[0.2,3.0])
>>> print(y)
ivy.array([0.38196602, 2.61803389])

>>> alpha = ivy.array([0., 1., 2., 3.])
>>> beta = ivy.array([2., 1., 2.])
>>> y = ivy.eigh_tridiagonal(alpha,
...     beta,
...     eigvals_only=False,
...     select='i',
...     select_range=[1,2],
...     tol=1.)
>>> print(y)
(ivy.array([0.38196602, 2.61803389]), ivy.array([[ 0.35048741, -0.56710052],
       [ 0.06693714, -0.74234426],
       [-0.74234426, -0.06693714],
       [ 0.56710052,  0.35048741]]))

With ivy.Container input:

>>> alpha = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([2., 2., 2.]))
>>> beta = ivy.array([0.,2.])
>>> y = ivy.eigh_tridiagonal(alpha, beta)
>>> print(y)
{
    a: ivy.array([-0.56155282, 0., 3.56155276]),
    b: ivy.array([0., 2., 4.])
}

>>> alpha = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([2., 2., 2.]))
>>> beta = ivy.Container(a=ivy.array([0.,2.]), b=ivy.array([2.,2.]))
>>> y = ivy.eigh_tridiagonal(alpha, beta)
>>> print(y)
{
    a: ivy.array([-0.56155282, 0., 3.56155276]),
    b: ivy.array([-0.82842714, 2., 4.82842731])
}
ivy.eigvals(x, /)[source]#

Compute eigenvalues of x. Returns a set of eigenvalues.

Parameters:

x (Union[Array, NativeArray]) – An array of shape (…, N, N).

Return type:

Array

Returns:

w – Not necessarily ordered array(…, N) of eigenvalues in complex type.

Examples

With ivy.Array inputs: >>> x = ivy.array([[1,2], [3,4]]) >>> w = ivy.eigvals(x) >>> w ivy.array([-0.37228132+0.j, 5.37228132+0.j])

>>> x = ivy.array([[[1,2], [3,4]], [[5,6], [5,6]]])
>>> w = ivy.eigvals(x)
>>> w
ivy.array(
    [
        [-0.37228132+0.j,  5.37228132+0.j],
        [ 0.        +0.j, 11.        +0.j]
    ]
)
ivy.general_inner_product(a, b, n_modes=None, /, *, out=None)[source]#

Generalised inner products between tensors.

Takes the inner product between the last (respectively first) n_modes of a (respectively b)

Parameters:

  • a (Union[Array, NativeArray]) – first input tensor.

  • b (Union[Array, NativeArray]) – second input tensor.

  • n_modes (Optional[int], default: None) – int, default is None. If None, the traditional inner product is returned (i.e. a float) otherwise, the product between the n_modes last modes of a and the n_modes first modes of b is returned. The resulting tensor’s order is len(a) - n_modes.

  • out (Optional[Array], default: None) – Optional output array. If provided, the output array to store the result.

Return type:

Array

Returns:

The inner product of the input arrays.

Examples

With ivy.Array inputs:

>>> a = ivy.array([1, 2, 3])
>>> b = ivy.array([4, 5, 6])
>>> result = ivy.general_inner_product(a, b, 1)
>>> print(result)
ivy.array(32)

>>> a = ivy.array([1, 2])
>>> b = ivy.array([4, 5])
>>> result = ivy.general_inner_product(a, b)
>>> print(result)
ivy.array(14)

>>> a = ivy.array([[1, 1], [1, 1]])
>>> b = ivy.array([[1, 2, 3, 4],[1, 1, 1, 1]])
>>> result = ivy.general_inner_product(a, b, 1)
>>> print(result)
ivy.array([[2, 3, 4, 5],
   [2, 3, 4, 5]])
ivy.higher_order_moment(x, order, /, *, out=None)[source]#

Compute the Higher-Order Moment.

Parameters:

  • x (Union[Array, NativeArray]) – matrix of size (n_samples, n_features) or tensor of size(n_samples, D1, …, DN)

  • order (int) – number of the higher-order moment to compute

Return type:

Array

Returns:

tensor – if tensor is a matrix of size (n_samples, n_features), tensor of size (n_features, )*order

Examples

>>> a = ivy.array([[1, 2], [3, 4]])
>>> result = ivy.higher_order_moment(a, 3)
>>> print(result)
ivy.array([[
    [14, 19],
    [19, 26]],
   [[19, 26],
    [26, 36]
]])
ivy.initialize_tucker(x, rank, modes, /, *, init='svd', seed=None, svd='truncated_svd', non_negative=False, mask=None, svd_mask_repeats=5)[source]#

Initialize core and factors used in tucker. The type of initialization is set using init. If init == ‘random’ then initialize factor matrices using random_state. If init == ‘svd’ then initialize the m`th factor matrix using the `rank left singular vectors of the `m`th unfolding of the input tensor.

Parameters:

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

  • rank (Sequence[int]) – number of components

  • modes (Sequence[int]) – modes to consider in the input tensor

  • seed (Optional[int], default: None) – Used to create a random seed distribution when init == ‘random’

  • init (Optional[Union[Literal['svd', 'random'], TuckerTensor]], default: 'svd') – initialization scheme for tucker decomposition.

  • svd (Optional[Literal['truncated_svd']], default: 'truncated_svd') – function to use to compute the SVD

  • non_negative (Optional[bool], default: False) – if True, non-negative factors are returned

  • mask (Optional[Union[Array, NativeArray]], default: None) – array of booleans with the same shape as tensor should be 0 where the values are missing and 1 everywhere else. Note: if tensor is sparse, then mask should also be sparse with a fill value of 1 (or True).

  • svd_mask_repeats (Optional[int], default: 5) – number of iterations for imputing the values in the SVD matrix when mask is not None

Return type:

Tuple[Array, Sequence[Array]]

Returns:

  • core – initialized core tensor

  • factors – list of factors

ivy.khatri_rao(x, weights=None, skip_matrix=None, mask=None, out=None)[source]#

Khatri-Rao product of a sequence of matrices.

This can be seen as a column-wise kronecker product. If one matrix only is given, that matrix is directly returned.

Parameters:

  • x (Sequence[Union[Array, NativeArray]]) –

    Sequence of tensors with the same number of columns, i.e.::
    for i in len(x):

    x[i].shape = (n_i, m)

  • weights (Optional[Union[Array, NativeArray]], default: None) – array of weights for each rank, of length m, the number of column of the factors (i.e. m == factor[i].shape[1] for any factor)

  • skip_matrix (Optional[Sequence[int]], default: None) – if not None, index of a matrix to skip

  • mask (Optional[Union[Array, NativeArray]], default: None) – array of 1s and 0s of length m

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

Return type:

Array

Returns:

khatri_rao_product (ivy.Array of shape (prod(n_i), m)) – where prod(n_i) = prod([m.shape[0] for m in input]) i.e. the product of the number of rows of all the input in the product.

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

Compute the Kronecker product, a composite array made of blocks of the second array scaled by the first.

Parameters:

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

  • b (Union[Array, NativeArray]) – Second input 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 – Array representing the Kronecker product of the input arrays.

Examples

>>> a = ivy.array([1,2])
>>> b = ivy.array([3,4])
>>> ivy.kron(a, b)
ivy.array([3, 4, 6, 8])
ivy.kronecker(x, skip_matrix=None, reverse=False, out=None)[source]#

Kronecker product of a list of matrices.

Parameters:

  • x (Sequence[Union[Array, NativeArray]]) – Sequence of matrices

  • skip_matrix (Optional[int], default: None) – if not None, index of a matrix to skip

  • reverse (Optional[bool], default: False) – if True, the order of the matrices is reversed

Return type:

Array

Returns:

kronecker_product (matrix of shape (prod(n_rows), prod(n_columns)) – where prod(n_rows) = prod([m.shape[0] for m in matrices]) and prod(n_columns) = prod([m.shape[1] for m in matrices])

ivy.lu_factor(A, /, *, pivot=True, out=None)[source]#
Parameters:

  • A (Union[Array, NativeArray]) – tensor of shape (*, m, n) where * is zero or more batch dimensions.

  • pivot (bool, default: True) – Whether to compute the LU decomposition with partial pivoting, or the regular LU decomposition. pivot = False not supported on CPU. Default: True.

  • out (Optional[Union[Array, NativeArray]], default: None) – tuple of two tensors to write the output to. Ignored if None. Default: None.

Return type:

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

Returns:

ret – A named tuple (LU, pivots).

ivy.lu_solve(lu, p, b, /, *, out=None)[source]#
Return type:

Array

ivy.make_svd_non_negative(x, U, S, V, /, *, nntype='nndsvd')[source]#

Use NNDSVD method to transform SVD results into a non-negative form. This method leads to more efficient solving with NNMF [1].

Parameters:

  • x (Union[Array, NativeArray]) – tensor being decomposed.

  • U (Union[Array, NativeArray]) – left singular matrix from SVD.

  • S (Union[Array, NativeArray]) – diagonal matrix from SVD.

  • V (Union[Array, NativeArray]) – right singular matrix from SVD.

  • nntype (Optional[Literal['nndsvd', 'nndsvda']], default: 'nndsvd') –

    whether to fill small values with 0.0 (nndsvd),

    or the tensor mean (nndsvda, default).

  • [1] (Boutsidis & Gallopoulos. Pattern Recognition, 41(4): 1350-1362, 2008.) –

Return type:

Tuple[Array, Array]

ivy.matrix_exp(x, /, *, out=None)[source]#

Compute the matrix exponential of a square matrix.

Parameters:

  • a – Square matrix.

  • 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 – the matrix exponential of the input.

Examples

>>> x = ivy.array([[[1., 0.],
                    [0., 1.]],
                    [[2., 0.],
                    [0., 2.]]])
>>> ivy.matrix_exp(x)
ivy.array([[[2.7183, 1.0000],
            [1.0000, 2.7183]],
            [[7.3891, 1.0000],
            [1.0000, 7.3891]]])
ivy.mode_dot(x, /, matrix_or_vector, mode, transpose=False, *, out=None)[source]#

N-mode product of a tensor and a matrix or vector at the specified mode.

Parameters:

  • x (Union[Array, NativeArray]) – tensor of shape (i_1, ..., i_k, ..., i_N)

  • matrix_or_vector (Union[Array, NativeArray]) – 1D or 2D array of shape (J, i_k) or (i_k, ) matrix or vectors to which to n-mode multiply the tensor

  • mode (int) – int in the range(1, N)

  • transpose (Optional[bool], default: False) – If True, the matrix is transposed. For complex tensors, the conjugate transpose is used.

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

Return type:

Array

Returns:

ivy.Array – mode-mode product of tensor by matrix_or_vector * of shape \((i_1, ..., i_{k-1}, J, i_{k+1}, ..., i_N)\)

if matrix_or_vector is a matrix

  • of shape \((i_1, ..., i_{k-1}, i_{k+1}, ..., i_N)\) if matrix_or_vector is a vector

ivy.multi_dot(x, /, *, out=None)[source]#

Compute the dot product of two or more matrices in a single function call, while selecting the fastest evaluation order.

Parameters:

  • x (Sequence[Union[Array, NativeArray]]) – sequence of matrices to multiply.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a valid shape, i.e. the resulting shape after applying regular matrix multiplication to the inputs.

Return type:

Array

Returns:

ret – dot product of the arrays.

Examples

With ivy.Array input:

>>> A = ivy.arange(2 * 3).reshape((2, 3))
>>> B = ivy.arange(3 * 2).reshape((3, 2))
>>> C = ivy.arange(2 * 2).reshape((2, 2))
>>> ivy.multi_dot((A, B, C))
ivy.array([[ 26,  49],
           [ 80, 148]])

>>> A = ivy.arange(2 * 3).reshape((2, 3))
>>> B = ivy.arange(3 * 2).reshape((3, 2))
>>> C = ivy.arange(2 * 2).reshape((2, 2))
>>> D = ivy.zeros((2, 2))
>>> ivy.multi_dot((A, B, C), out=D)
>>> print(D)
ivy.array([[ 26,  49],
           [ 80, 148]])
ivy.multi_mode_dot(x, mat_or_vec_list, /, modes=None, skip=None, transpose=False, *, out=None)[source]#

N-mode product of a tensor and several matrices or vectors over several modes.

Parameters:

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

  • mat_or_vec_list (Sequence[Union[Array, NativeArray]]) – sequence of matrices or vectors of length tensor.ndim

  • skip (Optional[Sequence[int]], default: None) – None or int, optional, default is None If not None, index of a matrix to skip.

  • modes (Optional[Sequence[int]], default: None) – None or int list, optional, default is None

  • transpose (Optional[bool], default: False) – If True, the matrices or vectors in in the list are transposed. For complex tensors, the conjugate transpose is used.

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

Return type:

Array

Returns:

ivy.Array – tensor times each matrix or vector in the list at mode mode

Notes

If no modes are specified, just assumes there is one matrix or vector per mode and returns: \(\\text{x }\\times_0 \\text{ matrix or vec list[0] }\\times_1 \\cdots \\times_n \\text{ matrix or vec list[n] }\)

ivy.partial_tucker(x, rank=None, modes=None, /, *, n_iter_max=100, init='svd', svd='truncated_svd', seed=None, mask=None, svd_mask_repeats=5, tol=0.0001, verbose=False, return_errors=False)[source]#

Partial tucker decomposition via Higher Order Orthogonal Iteration (HOI)

Decomposes tensor into a Tucker decomposition exclusively along the provided modes.

Parameters:

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

  • rank (Optional[Sequence[int]], default: None) – size of the core tensor, (len(ranks) == tensor.ndim) if int, the same rank is used for all modes if None, original tensors size will be preserved.

  • modes (Optional[Sequence[int]], default: None) – list of the modes on which to perform the decomposition

  • n_iter_max (Optional[int], default: 100) – maximum number of iteration

  • init (Optional[Union[Literal['svd', 'random'], TuckerTensor]], default: 'svd') – {‘svd’, ‘random’}, or TuckerTensor optional if a TuckerTensor is provided, this is used for initialization

  • svd (Optional[Literal['truncated_svd']], default: 'truncated_svd') – str, default is ‘truncated_svd’ function to use to compute the SVD,

  • seed (Optional[int], default: None) – Used to create a random seed distribution when init == ‘random’

  • mask (Optional[Union[Array, NativeArray]], default: None) – array of booleans with the same shape as tensor should be 0 where the values are missing and 1 everywhere else. Note: if tensor is sparse, then mask should also be sparse with a fill value of 1 (or True).

  • svd_mask_repeats (Optional[int], default: 5) – number of iterations for imputing the values in the SVD matrix when mask is not None

  • tol (Optional[float], default: 0.0001) – tolerance: the algorithm stops when the variation in the reconstruction error is less than the tolerance.

  • verbose (Optional[bool], default: False) – if True, different in reconstruction errors are returned at each iteration.

  • return_erros – if True, list of reconstruction errors are returned.

Return type:

Tuple[Array, Sequence[Array]]

Returns:

  • core (ndarray) – core tensor of the Tucker decomposition

  • factors (ndarray list) – list of factors of the Tucker decomposition. with core.shape[i] == (tensor.shape[i], ranks[i]) for i in modes

ivy.solve_triangular(x1, x2, /, *, upper=True, adjoint=False, unit_diagonal=False, out=None)[source]#

Return the unique solution to the triangular system of linear equations AX = B.

Parameters:

  • x1 (Union[Array, NativeArray]) – Triangular coefficient array A of shape (…, N, N), with no zeros on diagonal.

  • x2 (Union[Array, NativeArray]) – Right-hand side array B of shape (…, N, K).

  • upper (bool, default: True) – Whether the input x1 is upper triangular.

  • adjoint (bool, default: False) – Whether to take the adjoint (conjugate transpose) of x1 as the matrix A.

  • unit_diagonal (bool, default: False) – Whether to ignore the diagonal entries of A and assume them all equal to 1.

  • out (Optional[Array], default: None) – Optional output array. If provided, the output array to store the result.

Return type:

Array

Returns:

ret – The solution X, which has the same shape as B.

Examples

With ivy.Array inputs:

>>> a = ivy.array([[3, 0, 0, 0],
...                [2, 1, 0, 0],
...                [1, 0, 1, 0],
...                [1, 1, 1, 1]], dtype=ivy.float32)
>>> b = ivy.array([[4],
...                [2],
...                [4],
...                [2]], dtype=ivy.float32)
>>> x = ivy.solve_triangular(a, b, upper=False)
>>> ivy.matmul(a, x)
ivy.array([[4.],
           [2.],
           [4.],
           [2.]])
ivy.svd_flip(U, V, /, u_based_decision=True)[source]#

Sign correction to ensure deterministic output from SVD. Adjusts the columns of u and the rows of v such that the loadings in the columns in u that are largest in absolute value are always positive. This function is borrowed from scikit- learn/utils/extmath.py.

Parameters:

  • U (Union[Array, NativeArray]) – left singular matrix output of SVD

  • V (Union[Array, NativeArray]) – right singular matrix output of SVD

  • u_based_decision (Optional[bool], default: True) – If True, use the columns of u as the basis for sign flipping. Otherwise, use the rows of v. The choice of which variable to base the decision on is generally algorithm dependent.

Return type:

Tuple[Array, Array]

Returns:

u_adjusted, v_adjusted (arrays with the same dimensions as the input.)

ivy.tensor_train(input_tensor, rank, /, *, svd='truncated_svd', verbose=False)[source]#

TT decomposition via recursive SVD.

Decomposes the input into a sequence of order-3 tensors (factors) Also known as Tensor-Train decomposition [1]

Parameters:

  • input_tensor (Union[Array, NativeArray]) – tensor to decompose

  • rank (Union[int, Sequence[int]]) – maximum allowable TT rank of the factors if int, then this is the same for all the factors if int list, then rank[k] is the rank of the kth factor

  • svd (Optional[Literal['truncated_svd']], default: 'truncated_svd') – function to use to compute the SVD

  • verbose (Optional[bool], default: False) – level of verbosity

Return type:

TTTensor

Returns:

  • factors – order-3 tensors of the TT decomposition

  • [1] (Ivan V. Oseledets. “Tensor-train decomposition”,)

  • SIAM J. Scientific Computing, 33(5) (2295–2317, 2011.)

ivy.truncated_svd(x, /, compute_uv=True, n_eigenvecs=None)[source]#

Compute a truncated SVD on x using the standard SVD.

Parameters:

  • x (Union[Array, NativeArray]) – 2D-array compute_uv If True then left and right singular vectors will be computed and returned in U and Vh, respectively. Otherwise, only the singular values will be computed, which can be significantly faster.

  • n_eigenvecs (Optional[int], default: None) – if specified, number of eigen[vectors-values] to return else full matrices will be returned

Return type:

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

Returns:

ret – a namedtuple (U, S, Vh) Each returned array must have the same floating-point data type as x.

ivy.tt_matrix_to_tensor(tt_matrix, /, *, out=None)[source]#

Return the full tensor whose TT-Matrix decomposition is given by ‘factors’ Re- assembles ‘factors’, which represent a tensor in TT-Matrix format into the corresponding full tensor.

Parameters:

  • tt_matrix (Union[Array, NativeArray]) – array of 4D-arrays TT-Matrix factors (known as core) of shape (rank_k, left_dim_k, right_dim_k, rank_{k+1})

  • out (Optional[Array], default: None) – Optional output array. If provided, the output array to store the result.

Return type:

Array

Returns:

output_tensor (array) – tensor whose TT-Matrix decomposition was given by ‘factors’

Examples

>>> x = ivy.array([[[[[0.49671414],
...                      [-0.1382643]],
...
...                     [[0.64768857],
...                      [1.5230298]]]],
...                   [[[[-0.23415337],
...                      [-0.23413695]],
...
...                     [[1.57921278],
...                      [0.76743472]]]]])
>>> y = ivy.tt_matrix_to_tensor(x)
>>> print(y)
ivy.array([[[[-0.1163073 , -0.11629914],
[ 0.03237505,  0.03237278]],

[[ 0.78441733, 0.38119566], [-0.21834874, -0.10610882]]],

[[[-0.15165846, -0.15164782], [-0.35662258, -0.35659757]],

[[ 1.02283812, 0.49705869], [ 2.40518808, 1.16882598]]]])

ivy.tucker(x, rank=None, /, *, fixed_factors=None, n_iter_max=100, init='svd', svd='truncated_svd', seed=None, mask=None, svd_mask_repeats=5, tol=0.0001, verbose=False, return_errors=False)[source]#

Tucker decomposition via Higher Order Orthogonal Iteration (HOI)

Decomposes tensor into a Tucker decomposition: tensor = [| core; factors[0], ...factors[-1] |] [1]

Parameters:

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

  • rank (Optional[Sequence[int]], default: None) – size of the core tensor, (len(ranks) == tensor.ndim) if int, the same rank is used for all modes

  • fixed_factors (Optional[Sequence[int]], default: None) – if not None, list of modes for which to keep the factors fixed. Only valid if a Tucker tensor is provided as init.

  • n_iter_max (Optional[int], default: 100) – maximum number of iteration

  • init (Optional[Union[Literal['svd', 'random'], TuckerTensor]], default: 'svd') – {‘svd’, ‘random’}, or TuckerTensor optional if a TuckerTensor is provided, this is used for initialization

  • svd (Optional[Literal['truncated_svd']], default: 'truncated_svd') – str, default is ‘truncated_svd’ function to use to compute the SVD,

  • seed (Optional[int], default: None) – Used to create a random seed distribution when init == ‘random’

  • mask (Optional[Union[Array, NativeArray]], default: None) – array of booleans with the same shape as tensor should be 0 where the values are missing and 1 everywhere else. Note: if tensor is sparse, then mask should also be sparse with a fill value of 1 (or True).

  • svd_mask_repeats (Optional[int], default: 5) – number of iterations for imputing the values in the SVD matrix when mask is not None

  • tol (Optional[float], default: 0.0001) – tolerance: the algorithm stops when the variation in the reconstruction error is less than the tolerance

  • verbose (Optional[bool], default: False) – if True, different in reconstruction errors are returned at each iteration.

  • return_errors (Optional[bool], default: False) – Indicates whether the algorithm should return all reconstruction errors and computation time of each iteration or not Default: False

Returns:

ivy.TuckerTensor or ivy.TuckerTensor and list of reconstruction errors if return_erros is True.

References

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

On this page