docs: add band matrix storage format documentation in the README of lapack/base

lib/node_modules/@stdlib/lapack/base/README.md

@@ -30,13 +30,13 @@ Many LAPACK routines work with banded matrices, which are stored compactly in tw
 
 ### 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.
+A general band matrix of size `M`-by-`N` with `KL` subdiagonals and `KU` superdiagonals is stored in a two-dimensional array `A` 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]`.
+-   Columns of the original matrix are stored in corresponding columns of the array `A`.
+-   Diagonals of the matrix are stored in rows of the array `A`.
+-   Element `A[i, j]` from the original matrix is stored in `A[KU+1+i-j, j]`.
 -   Valid range for `i`: `max(1, j-KU) <= i <= min(M, j+KL)`.
 
 #### Example
@@ -59,12 +59,12 @@ A = \left[
 
 <!-- </equation> -->
 
-the band storage matrix `AB` is then
+the band storage matrix `A` is then
 
-<!-- <equation class="equation" label="eq:band_storage_ab" align="center" raw="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]" alt="Band storage representation of matrix A."> -->
+<!-- <equation class="equation" label="eq:band_storage_ab" align="center" raw="A = \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]" alt="Band storage representation of matrix A."> -->
 
 ```math
-AB = \left[
+A = \left[
 \begin{array}{rrrrr}
     *      & a_{12} & a_{23} & a_{34} & a_{45} \\
     a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\
@@ -76,7 +76,7 @@ AB = \left[
 
 <!-- </equation> -->
 
-`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.
+`A` 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.
 
@@ -93,12 +93,12 @@ For symmetric or Hermitian band matrices with `KD` subdiagonals or superdiagonal
 
 **Upper Triangle Storage (UPLO = 'U'):**
 
--   Element `A[i, j]` is stored in `AB[KD+1+i-j, j]`.
+-   Element `A[i, j]` is stored in `A[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]`.
+-   Element `A[i, j]` is stored in `A[1+i-j, j]`.
 -   Valid range for `i`: `j <= i <= min(N, j+KD)`.
 
 #### Example
@@ -121,12 +121,12 @@ A = \left[
 
 <!-- </equation> -->
 
-the band storage matrix `AB` when `UPLO = 'U'` (i.e., upper triangle) is
+the band storage matrix `A` when `UPLO = 'U'` (i.e., upper triangle) is
 
-<!-- <equation class="equation" label="eq:symmetric_upper_ab" align="center" raw="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]" alt="Band storage representation of symmetric matrix A (upper triangle)."> -->
+<!-- <equation class="equation" label="eq:symmetric_upper_ab" align="center" raw="A = \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]" alt="Band storage representation of symmetric matrix A (upper triangle)."> -->
 
 ```math
-AB = \left[
+A = \left[
 \begin{array}{rrrrr}
     *      & *      & a_{13} & a_{24} & a_{35} \\
     *      & a_{12} & a_{23} & a_{34} & a_{45} \\
@@ -137,7 +137,7 @@ AB = \left[
 
 <!-- </equation> -->
 
-`AB` is a 3×5 matrix as `KD+1 = 2+1 = 3`. Similarly, given the following matrix `A`,
+`A` is a 3×5 matrix as `KD+1 = 2+1 = 3`. Similarly, given the following matrix `A`,
 
 <!-- <equation class="equation" label="eq:symmetric_lower_a" align="center" raw="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]" alt="Representation of symmetric band matrix A (lower triangle)."> -->
 
@@ -155,12 +155,12 @@ A = \left[
 
 <!-- </equation> -->
 
-the band storage matrix `AB` when `UPLO = 'L'` (i.e., lower triangle) is
+the band storage matrix `A` when `UPLO = 'L'` (i.e., lower triangle) is
 
-<!-- <equation class="equation" label="eq:symmetric_lower_ab" align="center" raw="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]" alt="Band storage representation of symmetric matrix A (lower triangle)."> -->
+<!-- <equation class="equation" label="eq:symmetric_lower_ab" align="center" raw="A = \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]" alt="Band storage representation of symmetric matrix A (lower triangle)."> -->
 
 ```math
-AB = \left[
+A = \left[
 \begin{array}{rrrrr}
     a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\
     a_{21} & a_{32} & a_{43} & a_{54} & *      \\
@@ -169,10 +169,62 @@ AB = \left[
 \right]
 ```
 
-`AB` is a 3×5 matrix as `KD+1 = 2+1 = 3`.
+`A` is a 3×5 matrix as `KD+1 = 2+1 = 3`.
+
+<!-- </equation> -->
+
+### Example
+
+Consider a 4×4 general band matrix with `KL = 2` subdiagonals and `KU = 1` superdiagonal:
+
+<!-- <equation class="equation" label="eq:band_matrix_numeric_a" align="center" raw="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]" alt="Representation of band matrix A with numeric values."> -->
+
+```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]
+```
+
+<!-- </equation> -->
+
+#### Band Storage Representation
+
+The band storage matrix `A` has dimensions `(KL+KU+1) × N = (2+1+1) × 4 = 4 × 4`:
+
+<!-- <equation class="equation" label="eq:band_storage_numeric_a" align="center" raw="A = \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]" alt="Band storage representation of matrix A with numeric values."> -->
+
+```math
+A = \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]
+```
 
 <!-- </equation> -->
 
+Here's how to represent this band matrix in JavaScript using `Float64Array`:
+
+##### Row-Major Layout
+
+```javascript
+var A = 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 A = 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 ] );
+```
+
 </section>
 
 <!-- /.intro -->