stdlib-js / stdlib-js/stdlib

[RFC]: mismatch between BLAS band storage and `to-compact` layout

Open
#10,863 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
6k
Forks
1.3k
Avg merge
1d 3h
Merged PRs (30d)
611

Description

### Description

## Description

While implementing `blas/base/cgbmv`, I noticed that the band matrix storage format expected by BLAS `gbmv` differs from the layout produced by [`@stdlib/array/base/banded/to-compact`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/banded/to-compact).

`to-compact` produces a **diagonal-centered layout**, whereas BLAS expects a **band storage layout** compatible with the `gbmv` routines (as documented in ([Intel® oneAPI Math Kernel Library](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-dpcpp/2023-1/matrix-storage.html#GUID-7101306A-AB1A-4A3D-9ED5-21E0B5404202)).

Because of this difference, `to-compact` cannot be directly used for preparing matrices for `gbmv`.

This behaviour is only present in **colexicographic** or column wise packing.

### For example, given:
```js
var A = [
[ 1, 2, 3, 0, 0 ],
[ -2, 4, 5, 6, 0 ],
[ -3, -5, 7, 8, 9 ],
[ 0, -6, -8, 10, 11 ],
[ 0, 0, -9,-11, 12 ]
];
```

### Output from `to-compact`

#### Column wise (colexicographic) packing
```js
AC = toCompact( A, 2, 2, true );
/* e.g., returns =>
[
[ 0, 0, 1, -2, -3 ],
[ 0, 2, 4, -5, -6 ],
[ 3, 5, 7, -8, -9 ],
[ 6, 8, 10, -11, 0 ],
[ 9, 11, 12, 0, 0 ]
]
*/
```

### Expected BLAS band storage (MKL / Netlib)

BLAS gbmv expects band matrices packed differently.
> Band Matrix
A general band matrix A of m rows and n columns with kl sub-diagonals, ku super-diagonals and leading dimension lda is represented as a one dimensional array a of size at least lda * n (respectively, lda * m) if column (respectively, row) major layout is used.
Before entry in any BLAS function using a general band matrix, the leading (kl + ku + 1) by n (respectively, m) part of the array a must contain the matrix A. This matrix must be supplied column-by-column (respectively, row-by-row), with the main diagonal of the matrix in row ku (respectively, column kl) of the array (0-based indexing), the first super-diagonal starting at position 1 (respectively, 0) in row (ku – 1) (respectively, column (kl + 1)), the first sub-diagonal starting at position 0 (respectively, 1) in row (ku + 1) (respectively, column (kl – 1)), and so on. Elements in the array a that do not correspond to elements in the band matrix (such as the top left ku-by-ku triangle) are not referenced.

```js
Acompact = [
[  0,   0,  1,  2, 3 ],
  [  0,  -2,  4,  5, 6 ],
  [ -3,  -5,  7,  8, 9 ],
  [ -6,  -8, 10, 11, 0 ],
  [ -9, -11, 12,  0, 0 ]
]
```

### Related Issues

Related issues # , # , and # .

### Questions

No.

### Demo

_No response_

### Reproduction

```shell
var toCompact = require('@stdlib/array/base/banded/to-compact');

var A = [
[ 1, 2, 3, 0, 0 ],
[ -2, 4, 5, 6, 0 ],
[ -3, -5, 7, 8, 9 ],
[ 0, -6, -8, 10, 11 ],
[ 0, 0, -9,-11, 12 ]
];

var AC = toCompact( A, 2, 2, true );

console.log( AC );
```

### Expected Results

```shell
[
[ 0, 0, 1, 2, 3 ],
[ 0, -2, 4, 5, 6 ],
[ -3, -5, 7, 8, 9 ],
[ -6, -8, 10, 11, 0 ],
[ -9, -11, 12, 0, 0 ]
]
```

### Actual Results

```shell
[
[ 0, 0, 1, -2, -3 ],
[ 0, 2, 4, -5, -6 ],
[ 3, 5, 7, -8, -9 ],
[ 6, 8, 10, -11, 0 ],
[ 9, 11, 12, 0, 0 ]
]
```

### Version

_No response_

### Environments

Node.js

### Browser Version

_No response_

### Node.js / npm Version

20.20.0

### Platform

Linux

### Checklist

- [x] Read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [x] Searched for existing issues and pull requests.

Contributor guide

Open the contributing guide

Research direction

Start with the @stdlib/array/base/banded/to-compact entry point and the blas/base/cgbmv implementation mentioned in the issue. Compare their colexicographic storage conventions with the linked BLAS documentation, then inspect related issues and the package tests. Done means the intended column-wise layout is explicitly decided and the observed output agrees with that decision.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
data
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.