diff --git a/lib/node_modules/@stdlib/lapack/base/README.md b/lib/node_modules/@stdlib/lapack/base/README.md index 26b6cbe0402a..96829f5e6651 100644 --- a/lib/node_modules/@stdlib/lapack/base/README.md +++ b/lib/node_modules/@stdlib/lapack/base/README.md @@ -22,6 +22,213 @@ limitations under the License. > Base (i.e., lower-level) linear algebra package (LAPACK) routines. +
+ +## Band Storage + +Many LAPACK routines work with banded matrices, which are stored compactly in two-dimensional arrays arranged in linear memory in order to save memory and improve computational efficiency. The following are the different band storage formats used throughout LAPACK. + +### General Band Matrix Storage + +A general band matrix of size `M`-by-`N` with `KL` subdiagonals and `KU` superdiagonals is stored in a two-dimensional array `AB` with `KL+KU+1` rows and `N` columns. + +**Storage Mapping:** + +- Columns of the original matrix are stored in corresponding columns of the array `AB`. +- Diagonals of the matrix are stored in rows of the array `AB`. +- Element `A[i, j]` from the original matrix is stored in `AB[KU+1+i-j, j]`. +- Valid range for `i`: `max(1, j-KU) <= i <= min(M, j+KL)`. + +#### Example + +Let `M = N = 5`, `KL = 2`, and `KU = 1`. Given an original band matrix `A` + + + +```math +A = \left[ +\begin{array}{rrrrr} + a_{11} & a_{12} & 0 & 0 & 0 \\ + a_{21} & a_{22} & a_{23} & 0 & 0 \\ + a_{31} & a_{32} & a_{33} & a_{34} & 0 \\ + 0 & a_{42} & a_{43} & a_{44} & a_{45} \\ + 0 & 0 & a_{53} & a_{54} & a_{55} +\end{array} +\right] +``` + + + +the band storage matrix `AB` is then + + + +```math +AB = \left[ +\begin{array}{rrrrr} + * & a_{12} & a_{23} & a_{34} & a_{45} \\ + a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\ + a_{21} & a_{32} & a_{43} & a_{54} & * \\ + a_{31} & a_{42} & a_{53} & * & * +\end{array} +\right] +``` + + + +`AB` is a 4×5 matrix as `KL+KU+1 = 2+1+1 = 4`. Elements marked `*` need not be set and are not referenced by LAPACK routines. + +**Note:** When a band matrix is supplied for LU factorization, space must be allowed to store an additional `KL` superdiagonals, which are generated by fill-in as a result of row interchanges. This means that the matrix is stored according to the above scheme, but with `KL + KU` superdiagonals. + +### Triangular Band Matrices + +Triangular band matrices are stored in the same format as general band matrices: + +- If `KL = 0`, the matrix is upper triangular. +- If `KU = 0`, the matrix is lower triangular. + +### Symmetric or Hermitian Band Matrices + +For symmetric or Hermitian band matrices with `KD` subdiagonals or superdiagonals, only the upper or lower triangle (as specified by an `UPLO` parameter) needs to be stored. + +**Upper Triangle Storage (UPLO = 'U'):** + +- Element `A[i, j]` is stored in `AB[KD+1+i-j, j]`. +- Valid range for `i`: `max(1, j-KD) <= i <= j`. + +**Lower Triangle Storage (UPLO = 'L'):** + +- Element `A[i, j]` is stored in `AB[1+i-j, j]`. +- Valid range for `i`: `j <= i <= min(N, j+KD)`. + +#### Example + +Let `N = 5` and `KD = 2`. Given the following matrix `A`, + + + +```math +A = \left[ +\begin{array}{rrrrr} + a_{11} & a_{12} & a_{13} & 0 & 0 \\ + {a_{12}} & a_{22} & a_{23} & a_{24} & 0 \\ + {a_{13}} & {a_{23}} & a_{33} & a_{34} & a_{35} \\ + 0 & {a_{24}} & {a_{34}} & a_{44} & a_{45} \\ + 0 & 0 & {a_{35}} & {a_{45}} & a_{55} +\end{array} +\right] +``` + + + +the band storage matrix `AB` when `UPLO = 'U'` (i.e., upper triangle) is + + + +```math +AB = \left[ +\begin{array}{rrrrr} + * & * & a_{13} & a_{24} & a_{35} \\ + * & a_{12} & a_{23} & a_{34} & a_{45} \\ + a_{11} & a_{22} & a_{33} & a_{44} & a_{55} +\end{array} +\right] +``` + + + +`AB` is a 3×5 matrix as `KD+1 = 2+1 = 3`. Similarly, given the following matrix `A`, + + + +```math +A = \left[ +\begin{array}{rrrrr} + a_{11} & {a_{21}} & {a_{31}} & 0 & 0 \\ + a_{21} & a_{22} & {a_{32}} & {a_{42}} & 0 \\ + a_{31} & a_{32} & a_{33} & {a_{43}} & {a_{53}} \\ + 0 & a_{42} & a_{43} & a_{44} & {a_{54}} \\ + 0 & 0 & a_{53} & a_{54} & a_{55} +\end{array} +\right] +``` + + + +the band storage matrix `AB` when `UPLO = 'L'` (i.e., lower triangle) is + + + +```math +AB = \left[ +\begin{array}{rrrrr} + a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\ + a_{21} & a_{32} & a_{43} & a_{54} & * \\ + a_{31} & a_{42} & a_{53} & * & * +\end{array} +\right] +``` + +`AB` is a 3×5 matrix as `KD+1 = 2+1 = 3`. + + + +### Example + +Consider a 4×4 general band matrix with `KL = 2` subdiagonals and `KU = 1` superdiagonal: + + + +```math +A = \left[ +\begin{array}{rrrr} + 1.0 & 2.0 & 0.0 & 0.0 \\ + 3.0 & 4.0 & 5.0 & 0.0 \\ + 6.0 & 7.0 & 8.0 & 9.0 \\ + 0.0 & 10.0 & 11.0 & 12.0 +\end{array} +\right] +``` + + + +#### Band Storage Representation + +The band storage matrix `AB` has dimensions `(KL+KU+1) × N = (2+1+1) × 4 = 4 × 4`: + + + +```math +AB = \left[ +\begin{array}{rrrr} + * & 2.0 & 5.0 & 9.0 \\ + 1.0 & 4.0 & 8.0 & 12.0 \\ + 3.0 & 7.0 & 11.0 & * \\ + 6.0 & 10.0 & * & * +\end{array} +\right] +``` + + + +Here's how to represent this band matrix in JavaScript using `Float64Array`: + +##### Row-Major Layout + +```javascript +var AB = new Float64Array( [ 0.0, 2.0, 5.0, 9.0, 1.0, 4.0, 8.0, 12.0, 3.0, 7.0, 11.0, 0.0, 6.0, 10.0, 0.0, 0.0 ] ); +``` + +##### Column-Major Layout + +```javascript +var AB = new Float64Array( [ 0.0, 1.0, 3.0, 6.0, 2.0, 4.0, 7.0, 10.0, 5.0, 8.0, 11.0, 0.0, 9.0, 12.0, 0.0, 0.0 ] ); +``` + +
+ + +
## Usage