From 2f844266db8171ae70771a3e3a9477346d12df5d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 02:49:25 -0800 Subject: [PATCH 1/2] Add initial specs --- .../linear_algebra_functions.md | 104 +++++++++++++++++- 1 file changed, 100 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba92aa7b0..fd449d6b9 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -103,14 +103,110 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a TODO (function-eig)= -### eig() +### eig(x, /) -TODO +Computes the eigenvalues and eigenvectors of a square matrix (or stack of square matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + + TODO: support complex numbers + +#### Returns + +- **out**: _Tuple\[ <array> ]_ + + - a namedtuple (`e`, `v`) whose first element must have shape `(..., M)` and consist of computed eigenvalues and whose second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. + +```{note} + +Eigenvalue sort order is left unspecified. +``` + +(function-eigh)= +### eigh(x, /, *, upper=False) + +Returns the eigenvalues and eigenvectors of a symmetric matrix (or stack of symmetric matrices) `x`. + + + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + + TODO: support complex numbers + +- **upper**: _bool_ + + - If `True`, use the upper-triangular part to compute the eigenvalues and eigenvectors. If `False`, use the lower-triangular part to compute the eigenvalues and eigenvectors. Default: `False`. + +#### Returns + +- **out**: _Tuple\[ <array> ]_ + + - a namedtuple (`e`, `v`) whose first element must have shape `(..., M)` and consist of computed eigenvalues and whose second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. + +```{note} + +Eigenvalue sort order is left unspecified. +``` + +(function-eigvals)= +### eigvals(x, /) + +Computes the eigenvalues of a square matrix (or stack of square matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + + TODO: support complex numbers + +#### Returns + +- **out**: _<array>_ + + - an array containing the computed eigenvalues. The array must have shape `(..., M)`. + +```{note} + +Eigenvalue sort order is left unspecified. +``` (function-eigvalsh)= -### eigvalsh() +### eigvalsh(x, /, *, upper=False) -TODO +Computes the eigenvalues of a square matrix (or stack of square matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + + TODO: support complex numbers + +- **upper**: _bool_ + + - If `True`, use the upper-triangular part to compute the eigenvalues. If `False`, use the lower-triangular part to compute the eigenvalues. Default: `False`. + +#### Returns + +- **out**: _<array>_ + + - an array containing the computed eigenvalues. The array must have shape `(..., M)`. + +```{note} + +Eigenvalue sort order is left unspecified. +``` (function-einsum)= ### einsum() From 3f1ad4d3d9ca32e6ae185106e80f5ce683abfa0f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 12 Apr 2021 11:19:31 -0700 Subject: [PATCH 2/2] Update specifications --- .../linear_algebra_functions.md | 71 +++---------------- 1 file changed, 10 insertions(+), 61 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index fd449d6b9..de65fd707 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -105,13 +105,13 @@ TODO (function-eig)= ### eig(x, /) -Computes the eigenvalues and eigenvectors of a square matrix (or stack of square matrices) `x`. +Computes the eigenvalues and eigenvectors of a square matrix (or a stack of square matrices) `x`. #### Parameters - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a floating-point data type. TODO: support complex numbers @@ -119,37 +119,12 @@ Computes the eigenvalues and eigenvectors of a square matrix (or stack of square - **out**: _Tuple\[ <array> ]_ - - a namedtuple (`e`, `v`) whose first element must have shape `(..., M)` and consist of computed eigenvalues and whose second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. - -```{note} - -Eigenvalue sort order is left unspecified. -``` - -(function-eigh)= -### eigh(x, /, *, upper=False) - -Returns the eigenvalues and eigenvectors of a symmetric matrix (or stack of symmetric matrices) `x`. - - - -#### Parameters - -- **x**: _<array>_ - - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. - - TODO: support complex numbers - -- **upper**: _bool_ - - - If `True`, use the upper-triangular part to compute the eigenvalues and eigenvectors. If `False`, use the lower-triangular part to compute the eigenvalues and eigenvectors. Default: `False`. - -#### Returns - -- **out**: _Tuple\[ <array> ]_ + - a namedtuple (`e`, `v`) whose + + - first element must have shape `(..., M)` and consist of computed eigenvalues + - second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. - - a namedtuple (`e`, `v`) whose first element must have shape `(..., M)` and consist of computed eigenvalues and whose second element must have shape `(..., M, M)`and have the columns of the inner most matrices contain the computed eigenvectors. + TODO: add note regarding return types ```{note} @@ -159,13 +134,13 @@ Eigenvalue sort order is left unspecified. (function-eigvals)= ### eigvals(x, /) -Computes the eigenvalues of a square matrix (or stack of square matrices) `x`. +Computes the eigenvalues of a square matrix (or a stack of square matrices) `x`. #### Parameters - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a floating-point data type. TODO: support complex numbers @@ -175,33 +150,7 @@ Computes the eigenvalues of a square matrix (or stack of square matrices) `x`. - an array containing the computed eigenvalues. The array must have shape `(..., M)`. -```{note} - -Eigenvalue sort order is left unspecified. -``` - -(function-eigvalsh)= -### eigvalsh(x, /, *, upper=False) - -Computes the eigenvalues of a square matrix (or stack of square matrices) `x`. - -#### Parameters - -- **x**: _<array>_ - - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. - - TODO: support complex numbers - -- **upper**: _bool_ - - - If `True`, use the upper-triangular part to compute the eigenvalues. If `False`, use the lower-triangular part to compute the eigenvalues. Default: `False`. - -#### Returns - -- **out**: _<array>_ - - - an array containing the computed eigenvalues. The array must have shape `(..., M)`. + TODO: add note regarding return data type. ```{note}