feat: add blas/base/dgbmv

[ShabiShett07]

---

type: pre_push_report
description: Results of running various checks prior to pushing changes. report:

• task: run_javascript_examples status: na
• task: run_c_examples status: na
• task: run_cpp_examples status: na
• task: run_javascript_readme_examples status: na
• task: run_c_benchmarks status: na
• task: run_cpp_benchmarks status: na
• task: run_fortran_benchmarks status: na
• task: run_javascript_benchmarks status: na
• task: run_julia_benchmarks status: na
• task: run_python_benchmarks status: na
• task: run_r_benchmarks status: na
• task: run_javascript_tests status: na ---

Progresses: #2039

Description

What is the purpose of this pull request?

This pull request:

• progresses [RFC]: Add BLAS bindings and implementations for linear algebra (tracking issue) #2039

Related Issues

Does this pull request have any related issues?

This pull request:

• progresses [RFC]: Add BLAS bindings and implementations for linear algebra (tracking issue) #2039

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

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
blas/base/dgbmv	$\color{green}492/492$ $\color{green}+100.00\%$	$\color{green}73/73$ $\color{green}+100.00\%$	$\color{green}3/3$ $\color{green}+100.00\%$	$\color{green}492/492$ $\color{green}+100.00\%$

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

[ShabiShett07]

/stdlib update-copyright-years

[ShabiShett07]

@kgryte, need your feedback especially on the fixtures

[ShabiShett07]

@kgryte, I have made changes as you suggested

[DivitJain26]

Hi @ShabiShett07
Great work!

I wanted to point out that, based on my research, the packing used for the row-major band matrix does not align with the format described in the Intel® oneAPI Math Kernel Library. This inconsistency appears across all the row-major fixtures.

The documentation states:

Layout = CblasRowMajor: Before entry, the leading (kl + ku + 1) by m part of the array a must contain the matrix of coefficients. This matrix must be supplied row-by-row, with the leading diagonal of the matrix in column (kl) of the array, the first super-diagonal starting at position 0 in column (kl + 1), the first sub-diagonal starting at position 1 in 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 kl by kl triangle) are not referenced.

According to the MKL documentation, the expected layout would be:

"A_compact": [
  [ 0.0, 3.0, 1.0 ],
  [ 6.0, 4.0, 2.0 ],
  [ 7.0, 5.0, 0.0 ]
],
"A": [ 0.0, 3.0, 1.0, 6.0, 4.0, 2.0, 7.0, 5.0, 0.0 ],

Here, the packing for row-major and column-major matrices is the same. However, in the MKL documentation, both layouts have their respective methods for packing. This was also confirmed by @kgryte on zulip in blas-lapack/Guidance on js CGBMV

[DivitJain26]

Hello @kgryte

Here I have demonstrated how Intel MKL expects band matrices to be packed for band routines.

Note: I am using OpenBLAS instead of SciPy, as OpenBLAS exposes the CBLAS interface directly and allows explicit control over row-major and column-major layouts (free form). Reproducing the same setup in SciPy is less straightforward because SciPy internally assumes Fortran-style (column-major) storage for BLAS routines.

As a baseline reference, I first verified the results using the general matrix-vector multiplication routine (dgemv).

#include <stdio.h>
#include <cblas.h>

int main()
{

	// Matrix dimensions
	int m = 3;
	int n = 3;

	double x[] = {1.0, 2.0, 3.0};

	// Scalars
	double alpha = 0.5;
	double beta = 0.5;

	/*
		A_mat: [
			[1.0, 3.0, 0.0],
			[2.0, 5.0, 7.0],
			[0.0, 6.0, 8.0]
		]
	*/

	// Row-major matrix
	double A_row_major[] = {1.0, 3.0, 0.0, 2.0, 5.0, 7.0, 0.0, 6.0, 8.0};
	double y1[] = {3.0, 2.0, 1.0};
	
	cblas_dgemv(CblasRowMajor, CblasNoTrans, m, n, alpha, A_row_major, n, x, 1, beta, y1, 1);
	
	printf("Row-Major Result: ");
	for (int i = 0; i < m; i++) {
		printf("%f, ", y1[i]);
	}
	printf("\n");
	
	// Column-major matrix
	double A_cloumn_major[] = {1.0, 2.0, 0.0, 3.0, 5.0, 6.0, 0.0, 7.0, 8.0};
	double y2[] = {3.0, 2.0, 1.0};
	
	cblas_dgemv(CblasColMajor, CblasNoTrans, m, n, alpha, A_cloumn_major, m, x, 1, beta, y2, 1);
	
	printf("Column-Major Result: ");
	for (int i = 0; i < m; i++) {
		printf("%f, ", y2[i]);
	}
	printf("\n");

	return 0;
}

Output:

Row-Major Result: 5.000000, 17.500000, 18.500000, 
Column-Major Result: 5.000000, 17.500000, 18.500000, 

Next, I repeated the same computation using the specialized banded routine dgbmv.

According to the MKL documentation:

Layout = CblasRowMajor: Before entry, the leading (kl + ku + 1) by m part of the array a must contain the matrix of coefficients. This matrix must be supplied row-by-row, with the leading diagonal of the matrix in column (kl) of the array, the first super-diagonal starting at position 0 in column (kl + 1), the first sub-diagonal starting at position 1 in row (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 kl by kl triangle) are not referenced.

Layout = CblasColMajor: Before entry, the leading (kl + ku + 1) by n part of the array a must contain the matrix of coefficients. This matrix must be supplied column-by-column, with the leading diagonal of the matrix in row (ku) of the array, the first super-diagonal starting at position 1 in row (ku - 1), the first sub-diagonal starting at position 0 in row (ku + 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.

#include <stdio.h>
#include <cblas.h>

int main() {

    int m = 3;
    int n = 3;

    int kl = 1;
    int ku = 1;

    double alpha = 0.5;
    double beta  = 0.5;

    double x[] = {1.0, 2.0, 3.0};

		/*
			A_mat: [
				[1.0, 3.0, 0.0],
				[2.0, 5.0, 7.0],
				[0.0, 6.0, 8.0]
			]
		*/

    // Row-Major Band Packing

    /*
			A_compact_row_major: [
				[0.0, 1.0, 3.0],
				[2.0, 5.0, 7.0],
				[6.0, 8.0, 0.0]
			]
    */

    double AC_row_major[] = {0.0, 1.0, 3.0, 2.0, 5.0, 7.0, 6.0, 8.0, 0.0};
    double y1[] = {3.0, 2.0, 1.0};

    cblas_dgbmv(CblasRowMajor, CblasNoTrans, m, n, kl, ku, alpha, AC_row_major, (kl+ku+1), x, 1, beta, y1, 1);

    printf("Row-Major Result: ");
    for (int i = 0; i < m; i++) {
        printf("%f, ", y1[i]);
    }
    printf("\n");

    // Column-Major Band Packing
		
		/*
			A_compact_cloumn_major: [
				[0.0, 3.0, 7.0],
				[1.0, 5.0, 8.0],
				[2.0, 6.0, 0.0]
			]
		*/
		
    double AC_cloumn_major[] = {0.0, 1.0, 2.0, 3.0, 5.0, 6.0, 7.0, 8.0, 0.0};
    double y2[] = {3.0, 2.0, 1.0};
		
    cblas_dgbmv(CblasColMajor, CblasNoTrans, m, n, kl, ku, alpha, AC_cloumn_major, (kl+ku+1), x, 1, beta, y2, 1);

    printf("Column-Major Result: ");
    for (int i = 0; i < m; i++) {
        printf("%f, ", y2[i]);
    }
    printf("\n");

    return 0;
}

Output:

Row-Major Result: 5.000000, 17.500000, 18.500000, 
Column-Major Result: 5.000000, 17.500000, 18.500000, 

The important observation here is that the compact band storage differs between row-major and column-major layouts. The underlying matrix is identical, but the packing order changes depending on the selected layout.