Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: develop
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
d04bbf9
docs: add banded matrices intro section in lapack/base
aayush0325 Sep 16, 2025
5e9bfc5
docs: update copy
kgryte Sep 16, 2025
a165f27
docs: update copy
kgryte Sep 16, 2025
c418f0c
docs: update copy
kgryte Sep 16, 2025
1d53da9
docs: update copy
kgryte Sep 16, 2025
3983026
docs: add missing period
kgryte Sep 16, 2025
461abb7
docs: fix copy
kgryte Sep 16, 2025
4a61392
style: align ampersands
kgryte Sep 16, 2025
939a824
style: remove trailing whitespace
kgryte Sep 16, 2025
b284d11
chore: remove newlines
aayush0325 Sep 17, 2025
d41266a
docs: add example
aayush0325 Sep 21, 2025
1bc74d4
fix: fix search and replace error
aayush0325 Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 70 additions & 18 deletions lib/node_modules/@stdlib/lapack/base/README.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this is looking good. It's a more readable version of https://netlib.org/lapack/lug/node124.html. That stated, one thing which needs to be changed is that currently everything is written using one-based indexing. We need to update everything to zero-based indexing.

Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aayush0325 What was the rationale for changing A to AB here and below? Now at, e.g., L101, you have

Element `A[i, j]` is stored in `A[1+i-j, j]`.

which no longer makes sense.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ran a silly search and replace here, sorry!! fixing


**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
Expand All @@ -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} \\
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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} \\
Expand All @@ -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)."> -->

Expand All @@ -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} & * \\
Expand All @@ -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 -->
Expand Down