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]) – optional output array, for writing the result to. It must have a shape that the (default: None) 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.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]]) – The order of the norm of the matrix (see ivy.norm() for details). (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) 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.cov(x1, x2=None, /, *, rowVar=True, bias=False, ddof=None, fweights=None, aweights=None, dtype=None)[source]#

Compute the covariance of matrix x1, or variables x1 and x2.

Parameters:

  • x1 (Union[Array, NativeArray]) – a 1D or 2D input array, with a numeric data type.

  • x2 (Optional[Union[Array, NativeArray]]) – optional second 1D or 2D input array, with a numeric data type. (default: None) Must have the same shape as self.

  • rowVar (bool) – optional variable where each row of input is interpreted as a variable (default: True) (default = True). If set to False, each column is instead interpreted as a variable.

  • bias (bool) – optional variable for normalizing input (default = False) by (N - 1) where (default: False) N is the number of given observations. If set to True, then normalization is instead by N. Can be overridden by keyword ddof.

  • ddof (Optional[int]) – optional variable to override bias (default = None). ddof=1 will return (default: None) the unbiased estimate, even with fweights and aweights given. ddof=0 will return the simple average.

  • fweights (Optional[Array]) – optional 1D array of integer frequency weights; the number of times each (default: None) observation vector should be repeated.

  • aweights (Optional[Array]) – optional 1D array of observation vector weights. These relative weights are (default: None) typically large for observations considered “important” and smaller for observations considered less “important”. If ddof=0 is specified, the array of weights can be used to assign probabilities to observation vectors.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – optional variable to set data-type of the result. By default, data-type (default: None) will have at least numpy.float64 precision.

  • out – 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 covariance matrix of an input matrix, or the covariance matrix of two variables. The returned array must have a floating-point data type determined by Type Promotion Rules and must be a square matrix of shape (N, N), where N is the number of variables in the input(s).

  • 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/extensions/generated/signatures.linalg.cov.html>`_ # noqa)

  • 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([[1,2,3], … [4,5,6]]) >>> y = x.cov() >>> print(y) ivy.array([[ 1., 1. ], … [ 1., 1. ]] With ivy.Container inputs: >>> x = ivy.Container(a=ivy.array([1., 2., 3.]), b=ivy.array([1., 2., 3.])) >>> y = ivy.Container(a=ivy.array([3., 2., 1.]), b=ivy.array([3., 2., 1.])) >>> z = ivy.Container.static_cov(x, y) >>> print(z) {

a: ivy.array([ 1., -1., -1., -1.]

[ 1., 1., -1., -1.]),

b: ivy.array([-1., -1., 1., 1.]

[-1., 1., 1., 1.])

} With a combination of ivy.Array and ivy.Container inputs: >>> x = ivy.array([1., 2., 3.]) >>> y = ivy.Container(a=ivy.array([3. ,2. ,1.]), b=ivy.array([-1., -2., -3.])) >>> z = ivy.cov(x, y) >>> print(z) {

a: ivy.array([ 1., -1.]

[-1., 1.]),

b: ivy.array([ 1., -1.]

[-1., 1.])

} With ivy.Array input and rowVar flag set to False (True by default): >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> y = x.cov(rowVar=False) >>> print(y) ivy.array([[ 4.5, 4.5, 4.5 ], … [ 4.5, 4.5, 4.5 ], … [ 4.5, 4.5, 4.5 ]]) With ivy.Array input and bias flag set to True (False by default): >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> y = x.cov(bias=True) >>> print(y) ivy.array([[ 0.6667, 0.6667 ], … [ 0.6667, 0.6667 ]] With ivy.Array input with both fweights and aweights given: >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> fw = ivy.array([1,2,3]) >>> aw = ivy.array([ 1.2, 2.3, 3.4 ]) >>> y = x.cov(fweights=fw, aweights=aw) >>> print(y) ivy.array([[ 0.48447205, 0.48447205 ], … [ 0.48447205, 0.48447205 ]] With ivy.Array input with both fweights and aweights given, and rowVar set to False: >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> fw = ivy.array([1,3]) >>> aw = ivy.array([ 1.5, 4 ]) >>> y = x.cov(fweights=fw, aweights=aw, rowVar=False) >>> print(y) ivy.array([[ 1.22727273, 1.22727273, 1.22727273 ], … [ 1.22727273, 1.22727273, 1.22727273 ], … [ 1.22727273, 1.22727273, 1.22727273 ]])

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]]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type:

Array

Returns:

ret – The 2-D output array.

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

This function conforms to the Array API Standard. This docstring is an extension of the docstring # noqa 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.

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) – If False, both eigenvalues and corresponding eigenvectors are (default: True) computed. If True, only eigenvalues are computed. Default is True.

  • select (str) – Optional string with values in {‘a’, ‘v’, ‘i’} (default is ‘a’) that (default: 'a') 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]]) – Size 2 tuple or list or array specifying the range of eigenvalues to (default: None) compute together with select. If select is ‘a’, select_range is ignored.

  • tol (Optional[float]) – Optional scalar. Ignored when backend is not Tensorflow. The absolute (default: None) 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.38196, 2.61803])

>>> 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.38196, 2.61803])

>>> ivy.set_backend("tensorflow")
>>> 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.18749806, 2.81250191]), ivy.array([[ 0.350609  , -0.56713122],
    [ 0.06563006, -0.74146169],
    [-0.74215561, -0.0636413 ],
    [ 0.56742489,  0.35291126]]))

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.56155, 0., 3.56155]),
    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.56155, 0., 3.56155]),
    b: ivy.array([-0.82842, 2., 4.82842])
}
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.

Functional 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.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]) – optional output array, for writing the result to. It must have a shape that the (default: None) 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.matrix_exp(x, /, *, out=None)[source]#

Compute the matrix exponential of a square matrix.

Parameters:

  • a – Square matrix.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) 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.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]) – optional output array, for writing the result to. It must have a valid (default: None) 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]])