matrix_power

ivy.matrix_power(x, n, /, *, out=None)

Raise a square matrix (or a stack of square matrices) x to an integer power n.

Parameters:

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

• n (int) – integer exponent.

Return type:

Array

Returns:

ret

if n is equal to zero, an array containing the identity matrix for each square matrix. If n is less than zero, an array containing the inverse of each square matrix raised to the absolute value of n, provided that each square matrix is invertible. If n is greater than zero, an array containing the result of raising each square matrix to the power n. The returned array must have the same shape as x and a floating-point data type determined by Type Promotion Rules.

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

With :code: ‘ivy.Array’ inputs:

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

>>> x = ivy.array([[3., 2.], [-5., -3.]])
>>> ivy.matrix_power(x,-1)
ivy.array([[-3., -2.],
           [ 5.,  3.]])

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

>>> x = ivy.array([[1., 2.], [0., 1.]])
>>> ivy.matrix_power(x,5)
ivy.array([[ 1., 10.],
           [ 0.,  1.]])

>>> x = ivy.array([[1/2, 0.], [0., -1/3]])
>>> ivy.matrix_power(x,-2)
ivy.array([[4., 0.],
           [0., 9.]])

With :code: ‘ivy.NativeArray’ inputs:

>>> x = ivy.native_array([[1., 2., 3.], [6., 5., 4.], [7., 8., 9.]])
>>> ivy.matrix_power(x,2)
ivy.array([[ 34.,  36.,  38.],
           [ 64.,  69.,  74.],
           [118., 126., 134.]])

With :code: ‘ivy.Container’ inputs:

>>> x = ivy.Container(a = ivy.array([[1., 2.], [3., 4.]]),
                      b = ivy.array([[1., 0.], [0., 0.]]))
>>> ivy.matrix_power(x,3)
{
    a: ivy.array([[37., 54.],
                  [81., 118.]]),
    b: ivy.array([[1., 0.],
                  [0., 0.]])
}

Array.matrix_power(self, n, /, *, out=None)

Return type:

Array

Container.matrix_power(self, n, /, *, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)

Return type:

Container