Skip to content

feat: add blas/base/dsbmv #6650

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.

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 31 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
d811c8c
feat: add blas/base/dsbmv
ShabiShett07 Apr 11, 2025
6e2483c
chore: add complete implementation
ShabiShett07 Apr 12, 2025
0a25c0d
chore: update copyright years
stdlib-bot Apr 12, 2025
409d821
chore: add test cases
ShabiShett07 Apr 12, 2025
16a9063
chore: add test cases
ShabiShett07 Apr 12, 2025
30e624d
chore: update test cases
ShabiShett07 Apr 13, 2025
a4a8183
chore: update examples
ShabiShett07 Apr 14, 2025
e25f528
chore: update examples
ShabiShett07 Apr 14, 2025
5f6910a
chore: update fixtures
ShabiShett07 Apr 16, 2025
4fd0fcd
chore: update jsdoc
ShabiShett07 Apr 16, 2025
7475eff
chore: update examples
ShabiShett07 Apr 16, 2025
55a7239
chore: fix test fixtures
ShabiShett07 Apr 24, 2025
56ff685
chore: fix test fixtures
ShabiShett07 Apr 24, 2025
87bd6e9
test: update test cases
ShabiShett07 Apr 29, 2025
3f6abe6
remove: indentation
ShabiShett07 Apr 30, 2025
541a527
bench: update variable declarations
Jul 23, 2025
0e094de
chore: update repl.txt
Jul 23, 2025
6739244
chore: update jsdoc
Jul 23, 2025
bc5a88f
chore: update test cases
Jul 24, 2025
673ff3b
chore: update example
Jul 24, 2025
210b9a1
refactor: update jsdoc and reduce arithmetic operations
Jul 24, 2025
5fb6caf
chore: update jsdoc
Jul 24, 2025
9b116b9
chore: use alpha and beta symbols
Jul 24, 2025
506ba6b
test: update fixtures
Jul 24, 2025
f6e13a0
test: update fixtures
Jul 24, 2025
d3e5a48
test: update test description
Jul 24, 2025
6d52968
test: update test description
Jul 24, 2025
1270d7c
chore: update description
Jul 24, 2025
c7f20c0
chore: update markdown file
Jul 24, 2025
a4cb271
test: complete test coverage
Jul 24, 2025
1ebeb8a
test: fix test cases
Jul 24, 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
269 changes: 269 additions & 0 deletions lib/node_modules/@stdlib/blas/base/dsbmv/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,269 @@
<!--

@license Apache-2.0

Copyright (c) 2025 The Stdlib Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->

# dsbmv

> Perform the matrix-vector operation `y = alpha*A*x + beta*y`.

<section class="usage">

## Usage

```javascript
var dsbmv = require( '@stdlib/blas/base/dsbmv' );
```

#### dsbmv( order, uplo, N, K, α, A, x, LDA, sx, β, y, sy )

Performs the matrix-vector operation `y = alpha*A*x + beta*y` where `alpha` and `beta` are scalars, `x` and `y` are `N` element vectors, and `A` is an `N` by `N` symmetric band matrix, with `K` super-diagonals.

```javascript
var Float64Array = require( '@stdlib/array/float64' );

Copy link
Member

Choose a reason for hiding this comment

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

I suggest adding a comment here illustrating the "original" matrix. E.g.,

Suggested change
/*
[
1.0, 2.0, 0.0,
2.0, 1.0, 3.0,
0.0, 3.0, 1.0
]
*/

var A = new Float64Array( [ 1.0, 2.0, 4.0, 3.0, 5.0, 0.0 ] );
var x = new Float64Array( [ 1.0, 2.0, 3.0 ] );
var y = new Float64Array( [ 0.0, 0.0, 0.0 ] );

dsbmv( 'row-major', 'lower', 3, 1, 1.0, A, 2, x, 1, 0.0, y, 1 );
// y => <Float64Array>[ 10.0, 25.0, 10.0 ]
```

The function has the following parameters:

- **order**: storage layout.
- **uplo**: specifies whether the upper or lower triangular part of the symmetric matrix `A` is supplied.
- **N**: specifies the order of the matrix `A`.
- **K**: specifies the number of super-diagonals of the matrix `A`
- **α**: scalar constant.
- **A**: packed banded form of a symmetric matrix `A` stored in linear memory as a [`Float64Array`][mdn-float64array].
- **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`)
- **x**: input [`Float64Array`][mdn-float64array].
- **sx**: stride length for `x`.
- **β**: scalar constant.
- **y**: output [`Float64Array`][mdn-float64array].
- **sy**: stride length for `y`.

The stride parameters determine how elements in the input arrays are accessed at runtime. For example, to iterate over the elements of `y` in reverse order,

```javascript
var Float64Array = require( '@stdlib/array/float64' );

var A = new Float64Array( [ 1.0, 2.0, 4.0, 3.0, 5.0, 0.0 ] );
var x = new Float64Array( [ 1.0, 2.0, 3.0 ] );
var y = new Float64Array( [ 0.0, 0.0, 0.0 ] );

dsbmv( 'row-major', 'lower', 3, 1, 1.0, A, 2, x, 1, 0.0, y, -1 );
// y => <Float64Array>[ 10.0, 25.0, 10.0 ]
```

Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.

<!-- eslint-disable stdlib/capitalized-comments -->

```javascript
var Float64Array = require( '@stdlib/array/float64' );

// Initial arrays...
var x0 = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0 ] );
var A = new Float64Array( [ 1.0, 2.0, 4.0, 3.0, 5.0, 0.0 ] );

// Create offset views...
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

dsbmv( 'row-major', 'lower', 3, 1, 1.0, A, 2, x1, 1, 0.0, y1, 1 );
// y0 => <Float64Array>[ 0.0, 10.0, 25.0, 10.0 ]
```

#### dsbmv.ndarray( uplo, N, K, α, A, sa1, sa2, oa, x, sx, ox, β, y, sy, oy )

Performs the matrix-vector operation `y = alpha*A*x + beta*y` using alternative indexing semantics where `alpha` and `beta` are scalars, `x` and `y` are `N` element vectors, and `A` is an `N` by `N` symmetric band matrix, with `K` super-diagonals.

```javascript
var Float64Array = require( '@stdlib/array/float64' );

var A = new Float64Array( [ 1.0, 2.0, 4.0, 3.0, 5.0, 0.0 ] );
var x = new Float64Array( [ 1.0, 2.0, 3.0 ] );
var y = new Float64Array( [ 0.0, 0.0, 0.0 ] );

dsbmv.ndarray( 'lower', 3, 1, 1.0, A, 2, 1, 0, x, 1, 0, 0.0, y, 1, 0 );
// y => <Float64Array>[ 10.0, 25.0, 10.0 ]
```

The function has the following additional parameters:

- **oa**: starting index for `A`.
- **sa1**: first dimension stride length for `A`.
- **sa2**: second dimension stride length for `A`.
- **ox**: starting index for `x`.
- **oy**: starting index for `y`.

While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example,

```javascript
var Float64Array = require( '@stdlib/array/float64' );

var A = new Float64Array( [ 1.0, 2.0, 4.0, 3.0, 5.0, 0.0 ] );
var x = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0 ] );

dsbmv.ndarray( 'lower', 3, 1, 1.0, A, 2, 1, 0, x, 1, 1, 0.0, y, 1, 1 );
// y => <Float64Array>[ 0.0, 10.0, 25.0, 10.0 ]
```

</section>

<!-- /.usage -->

<section class="notes">

## Notes

- `dsbmv()` corresponds to the [BLAS][blas] level 2 function [`dsbmv`][dsbmv].

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var dsbmv = require( '@stdlib/blas/base/dsbmv' );

var opts = {
'dtype': 'float64'
};

var N = 3;
var A = [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0 ];

var x = discreteUniform( N, -10, 10, opts );
var y = discreteUniform( N, -10, 10, opts );

dsbmv( 'row-major', 'upper', N, 1, 1.0, A, 2, x, 1, 1.0, y, 1 );
console.log( y );

dsbmv.ndarray( 'upper', N, 1, 1.0, A, 2, 1, 0, x, 1, 0, 1.0, y, 1, 0 );
console.log( y );
```

</section>

<!-- /.examples -->

<!-- C interface documentation. -->

* * *

<section class="c">

## C APIs

<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->

<section class="intro">

</section>

<!-- /.intro -->

<!-- C usage documentation. -->

<section class="usage">

### Usage

```c
TODO
```

#### TODO

TODO.

```c
TODO
```

TODO

```c
TODO
```

</section>

<!-- /.usage -->

<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="notes">

</section>

<!-- /.notes -->

<!-- C API usage examples. -->

<section class="examples">

### Examples

```c
TODO
```

</section>

<!-- /.examples -->

</section>

<!-- /.c -->

<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->

<section class="related">

</section>

<!-- /.related -->

<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="links">

[blas]: http://www.netlib.org/blas

[dsbmv]: https://www.netlib.org/lapack/explore-html-3.6.1/d7/d15/group__double__blas__level2_ga5c7ca036c788c5fd42e04ade0dc92d44.html

[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array

[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray

</section>

<!-- /.links -->
97 changes: 97 additions & 0 deletions lib/node_modules/@stdlib/blas/base/dsbmv/benchmark/benchmark.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2025 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

'use strict';

// MODULES //

var bench = require( '@stdlib/bench' );
var uniform = require( '@stdlib/random/array/uniform' );
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var pow = require( '@stdlib/math/base/special/pow' );
var floor = require( '@stdlib/math/base/special/floor' );
var pkg = require( './../package.json' ).name;
var dsbmv = require( './../lib/dsbmv.js' );


// VARIABLES //

var options = {
'dtype': 'float64'
};


// FUNCTIONS //

/**
* Creates a benchmark function.
*
* @private
* @param {PositiveInteger} N - array dimension size
* @returns {Function} benchmark function
*/
function createBenchmark( N ) {
var x = uniform( N, -10.0, 10.0, options );
var y = uniform( N, -10.0, 10.0, options );
var A = uniform( N*N, -10.0, 10.0, options );
return benchmark;

/**
* Benchmark function.
*
* @private
* @param {Benchmark} b - benchmark instance
*/
function benchmark( b ) {
var z;
var i;

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
z = dsbmv( 'row-major', 'upper', N, 1.0, 1, A, 2, x, 1, 1.0, y, 1 );
if ( isnan( z[ i%z.length ] ) ) {
b.fail( 'should not return NaN' );
}
}
b.toc();
if ( isnan( z[ i%z.length ] ) ) {
b.fail( 'should not return NaN' );
}
b.pass( 'benchmark finished' );
b.end();
}
}


// MAIN //

/**
* Main execution sequence.
*
* @private
*/
function main() {
var N;
var f;

N = floor( pow( pow( 10, 1 ), 1.0/2.0 ) );
f = createBenchmark( N );
bench( pkg+':size='+(N*N), f );
}

main();
Loading