diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 209a2f787..f1a5ee60c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -144,10 +144,31 @@ TODO TODO -(function-matrix_power)= -### matrix_power() +(function-linalg-matrix_power)= +### linalg.matrix_power(x, n, /) -TODO +Raises a square matrix (or a stack of square matrices) `x` to an integer power `n`. + +#### Parameters + +- **x**: _<array>_ + + - 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. + +#### Returns + +- **out**: _<array>_ + + - 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 {ref}`type-promotion`. + +#### Raises + +- if the innermost two dimensions of `x` are not the same size (i.e., form square matrices). +- if `n` is less than zero and a square matrix is not invertible. (function-matrix_rank)= ### matrix_rank()