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

aayush0325 · 2025-09-16T02:48:29Z

Description

What is the purpose of this pull request?

This pull request:

adds band matrix storage format documentation in the README of lapack/base as discussed

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

Read, understood, and followed the contributing guidelines.

@stdlib-js/reviewers

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

stdlib-bot · 2025-09-16T02:49:41Z

Coverage Report

Package	Statements	Branches	Functions	Lines
lapack/base	$\color{green}294/294$ $\color{green}+100.00\%$	$\color{green}1/1$ $\color{green}+100.00\%$	$\color{green}0/0$ $\color{green}+100.00\%$	$\color{green}294/294$ $\color{green}+100.00\%$

The above coverage report was generated for the changes in this PR.

Signed-off-by: Athan <[email protected]>

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

Signed-off-by: Athan <[email protected]>

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

Signed-off-by: Athan <[email protected]>

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

Signed-off-by: Athan <[email protected]>

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

Signed-off-by: Athan <[email protected]>

kgryte · 2025-09-16T05:34:28Z

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

+
+Triangular band matrices are stored in the same format as general band matrices:
+
+-   If `KL = 0`, the matrix is upper triangular.


It would be good to actually show matrices which are upper and lower triangular here.

kgryte · 2025-09-16T05:36:01Z

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

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.

kgryte

One question I have: how do row- and column-major orders factor in here. For example, in dgbbrd, the routine accepts a layout argument.

It may be good to also show how the band storage matrices are stored in linear memory for the two supported layouts. IIRC, this was a point of confusion during development.

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

Signed-off-by: Athan <[email protected]>

kgryte · 2025-09-16T05:41:54Z

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

+
+Let `M = N = 5`, `KL = 2`, and `KU = 1`. Given an original band matrix `A`
+
+<!-- <equation class="equation" label="eq:band_matrix_a" align="center" raw="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]" alt="Representation of band matrix A."> -->


In these comments, you do not need to preserve extra whitespace for aligning array elements. In fact, removing is preferred.

aayush0325 · 2025-09-17T10:47:49Z

One question I have: how do row- and column-major orders factor in here. For example, in dgbbrd, the routine accepts a layout argument.

this is how i understand the row and column major interpretations of these matrices:

for column major:

{
  "order": "column-major",
  "type": "banded",
  "M": 5,
  "N": 5,
  "KL": 2,
  "KU": 1,
  "A": [
    0.0, 0.0, 0.0, 1.1, 2.1, 3.1,
    0.0, 0.0, 1.2, 2.2, 3.2, 4.2,
    0.0, 0.0, 2.3, 3.3, 4.3, 5.3,
    0.0, 0.0, 3.4, 4.4, 5.4, 0.0,
    0.0, 0.0, 4.5, 5.5, 0.0, 0.0
  ],
  "A_mat": [
    [ 1.1, 1.2, 0.0, 0.0, 0.0 ],
    [ 2.1, 2.2, 2.3, 0.0, 0.0 ],
    [ 3.1, 3.2, 3.3, 3.4, 0.0 ],
    [ 0.0, 4.2, 4.3, 4.4, 4.5 ],
    [ 0.0, 0.0, 5.3, 5.4, 5.5 ]
  ],
}

for row major:

{
  "order": "row-major",
  "type": "banded",
  "M": 5,
  "N": 5,
  "KL": 2,
  "KU": 1,
  "A": [
    0.0, 0.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 0.0, 0.0,
    0.0, 1.2, 2.3, 3.4, 4.5,
    1.1, 2.2, 3.3, 4.4, 5.5,
    2.1, 3.2, 4.3, 5.4, 0.0,
    3.1, 4.2, 5.3, 0.0, 0.0
  ],
  "A_mat": [
    [ 1.1, 1.2, 0.0, 0.0, 0.0 ],
    [ 2.1, 2.2, 2.3, 0.0, 0.0 ],
    [ 3.1, 3.2, 3.3, 3.4, 0.0 ],
    [ 0.0, 4.2, 4.3, 4.4, 4.5 ],
    [ 0.0, 0.0, 5.3, 5.4, 5.5 ]
  ]
}

i am basically reading this column-by-column for col-major and row-by-row for row-major

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

kgryte · 2025-09-17T18:53:24Z

@aayush0325 What you are displaying is specific for LU correct with the extra cols/rows?

Regardless, I suggest making explicit with a couple of brief examples showing how banded matrices are stored according to layouts.

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

kgryte · 2025-09-22T08:48:17Z

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

 ### 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.


@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.

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

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

stdlib-bot added LAPACK Issue or pull request related to the Linear Algebra Package (LAPACK). Needs Review A pull request which needs code review. labels Sep 16, 2025

kgryte added 2 commits September 15, 2025 22:21

docs: update copy

5e9bfc5

Signed-off-by: Athan <[email protected]>

docs: update copy

a165f27

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

lib/node_modules/@stdlib/lapack/base/README.md Outdated Show resolved Hide resolved

docs: update copy

c418f0c

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

lib/node_modules/@stdlib/lapack/base/README.md Outdated Show resolved Hide resolved

docs: update copy

1d53da9

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

lib/node_modules/@stdlib/lapack/base/README.md Outdated Show resolved Hide resolved

docs: add missing period

3983026

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

lib/node_modules/@stdlib/lapack/base/README.md Outdated Show resolved Hide resolved

kgryte added 2 commits September 15, 2025 22:29

docs: fix copy

461abb7

Signed-off-by: Athan <[email protected]>

style: align ampersands

4a61392

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

kgryte requested changes Sep 16, 2025

View reviewed changes

kgryte reviewed Sep 16, 2025

View reviewed changes

lib/node_modules/@stdlib/lapack/base/README.md Outdated Show resolved Hide resolved

style: remove trailing whitespace

939a824

Signed-off-by: Athan <[email protected]>

kgryte reviewed Sep 16, 2025

View reviewed changes

kgryte added Documentation Improvements, additions, or changes to documentation. Needs Changes Pull request which needs changes before being merged. and removed Needs Review A pull request which needs code review. labels Sep 16, 2025

aayush0325 requested a review from kgryte September 21, 2025 04:50

stdlib-bot added the Needs Review A pull request which needs code review. label Sep 21, 2025

kgryte reviewed Sep 22, 2025

View reviewed changes

aayush0325 requested a review from kgryte September 22, 2025 08:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

aayush0325 commented Sep 16, 2025

Uh oh!

stdlib-bot commented Sep 16, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kgryte Sep 16, 2025

Uh oh!

kgryte Sep 16, 2025

Uh oh!

kgryte left a comment

Uh oh!

Uh oh!

kgryte Sep 16, 2025

Uh oh!

aayush0325 commented Sep 17, 2025

Uh oh!

kgryte commented Sep 17, 2025

Uh oh!

kgryte Sep 22, 2025

Uh oh!

aayush0325 Sep 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Triangular band matrices are stored in the same format as general band matrices:

		- If `KL = 0`, the matrix is upper triangular.


		Let `M = N = 5`, `KL = 2`, and `KU = 1`. Given an original band matrix `A`

		<!-- <equation class="equation" label="eq:band_matrix_a" align="center" raw="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]" alt="Representation of band matrix A."> -->

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

aayush0325 commented Sep 16, 2025

Description

Related Issues

Questions

Other

Checklist

Uh oh!

stdlib-bot commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kgryte Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

kgryte Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

kgryte left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kgryte Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

aayush0325 commented Sep 17, 2025

Uh oh!

kgryte commented Sep 17, 2025

Uh oh!

kgryte Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

aayush0325 Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

stdlib-bot commented Sep 16, 2025 •

edited

Loading