Skip to content

Commit 30b0391

Browse files
authored
Add matrix_power specification (#112)
* Add matrix_power spec * Update description * Add article * Add note on possible exceptions * Add exception * Update dtype requirements * Update copy * Move API to submodule
1 parent e0c0c87 commit 30b0391

File tree

1 file changed

+24
-3
lines changed

1 file changed

+24
-3
lines changed

spec/API_specification/linear_algebra_functions.md

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -273,10 +273,31 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
273273
- if `x1` is a one-dimensional array having shape `(N)`, `x2` is a one-dimensional array having shape `(M)`, and `N != M`.
274274
- if `x1` is an array having shape `(..., M, K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`.
275275

276-
(function-matrix_power)=
277-
### matrix_power()
276+
(function-linalg-matrix_power)=
277+
### linalg.matrix_power(x, n, /)
278278

279-
TODO
279+
Raises a square matrix (or a stack of square matrices) `x` to an integer power `n`.
280+
281+
#### Parameters
282+
283+
- **x**: _<array>_
284+
285+
- input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type.
286+
287+
- **n**: _int_
288+
289+
- integer exponent.
290+
291+
#### Returns
292+
293+
- **out**: _<array>_
294+
295+
- 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`.
296+
297+
#### Raises
298+
299+
- if the innermost two dimensions of `x` are not the same size (i.e., form square matrices).
300+
- if `n` is less than zero and a square matrix is not invertible.
280301

281302
(function-linalg-matrix_rank)=
282303
### linalg.matrix_rank(x, /, *, rtol=None)

0 commit comments

Comments
 (0)