Skip to content

feat: add lapack/base/dlasq3 #13199

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
prajjwalbajpai wants to merge 3 commits into
base: develop
Choose a base branch
from
+8,285 −0
Open

feat: add lapack/base/dlasq3 #13199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
52185e3
feat: add `lapack/base/dlasq3`
prajjwalbajpai Jun 29, 2026
770962f
feat: add tests
prajjwalbajpai Jul 1, 2026
ace9da0
feat: add benchmarks, examples and docs
prajjwalbajpai Jul 2, 2026
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
280 changes: 280 additions & 0 deletions lib/node_modules/@stdlib/lapack/base/dlasq3/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
<!--

@license Apache-2.0

Copyright (c) 2026 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.

-->

# dlasq3

> Check for deflation, compute a shift (`TAU`) and call DQDS.

<section class="intro">

The `dlasq3` routine checks for deflation of the QD array, computes a shift `TAU` and then calls DQDS. In case of failure it changes shifts and tries again until the output is positive. It is used as a helper by `sbdsqr` and `sstegr` when computing singular values and eigenvalues.

The QD array `Z` stores interleaved values in the following format:

```text
Z[4*i] = d(i) (diagonal from q-array)
Z[4*i+1] = e(i) (off-diagonal)
Z[4*i+2] = d(i+1) (diagonal from d-array, ping)
Z[4*i+3] = e(i+1) (off-diagonal)
```

</section>

<!-- /.intro -->

<section class="usage">

## Usage

```javascript
var dlasq3 = require( '@stdlib/lapack/base/dlasq3' );
```

#### dlasq3( I0, N0, Z, PP, IEEE, out )

Checks for deflation, computes a shift (`TAU`) and calls DQDS.

<!-- eslint-disable max-len -->

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

var Z = new Float64Array( [ 100, 4, 81, 3, 64, 2.5, 49, 2, 36, 1.5, 25, 1, 16, 0.5, 9, 0 ] );
var out = new Float64Array( 15 );

dlasq3( 0, 3, Z, 0, true, out );
// Z => <Float64Array>[ ~100.0, ~181.0, ~81.0, ~28.641, ~64.0, ~84.359, ~49.0, ~20.911, ~36.0, ~40.089, ~25.0, ~9.978, ~16.0, ~6.022, ~9.0, ~28.641 ]
// out => <Float64Array> ~6.022, ~181.0, ~0.0, ~0.0, ~0.0, ~1.0, ~5.0, ~-1.0, ~15.089, ~35.359, ~6.022, ~15.089, ~35.359, ~0.0, ~0.0 ]
```

The function has the following parameters:

- **I0**: first index.
- **N0**: last index.
- **Z**: the QD array as a [`Float64Array`][@stdlib/array/float64]. Should have `4*N0 + 4` indexed elements. `Z` is mutated in-place during the computation.
- **PP**: ping-pong flag. `0` for ping, `1` for pong, `2` indicates that flipping was applied to the `Z` array and that the initial tests for deflation should not be performed.
- **IEEE**: flag for IEEE or non IEEE arithmetic. Passed to `DLASQ5`.
- **out**: output array as a [`Float64Array`][@stdlib/array/float64] of length `15` containing the 15 scalar values `DMIN`, `SIGMA`, `DESIG`, `QMAX`, `NFAIL`, `ITER`, `NDIV`, `TTYPE`, `DMIN1`, `DMIN2`, `DN`, `DN1`, `DN2`, `G`, and `TAU`. On input, `out` should be initialized with the current values of these scalars.

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, max-len -->

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

// Initial arrays...
var Z0 = new Float64Array( [ 0.0, 100, 4, 81, 3, 64, 2.5, 49, 2, 36, 1.5, 25, 1, 16, 0.5, 9, 0 ] );
var out0 = new Float64Array( 16 );

// Create offset views...
var Z = new Float64Array( Z0.buffer, Z0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var out = new Float64Array( out0.buffer, out0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

dlasq3( 0, 3, Z, 0, true, out );
// Z0 => <Float64Array>[ 0.0, ~100.0, ~181.0, ~81.0, ~28.641, ~64.0, ~84.359, ~49.0, ~20.911, ~36.0, ~40.089, ~25.0, ~9.978, ~16.0, ~6.022, ~9.0, ~28.641 ]
// out0 => <Float64Array>[ 0.0, ~6.022, ~181.0, ~0.0, ~0.0, ~0.0, ~1.0, ~5.0, ~-1.0, ~15.089, ~35.359, ~6.022, ~15.089, ~35.359, ~0.0, ~0.0 ]
```

#### dlasq3.ndarray( I0,N0,Z,strideZ,offsetZ,PP,IEEE,out,strideOut,offsetOut )

Checks for deflation, computes a shift (`TAU`) and calls DQDS using alternative indexing semantics.

<!-- eslint-disable max-len -->

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

var Z = new Float64Array( [ 100, 4, 81, 3, 64, 2.5, 49, 2, 36, 1.5, 25, 1, 16, 0.5, 9, 0 ] );
var out = new Float64Array( 15 );

dlasq3.ndarray( 0, 3, Z, 1, 0, 0, true, out, 1, 0 );
// Z => <Float64Array>[ ~100.0, ~181.0, ~81.0, ~28.641, ~64.0, ~84.359, ~49.0, ~20.911, ~36.0, ~40.089, ~25.0, ~9.978, ~16.0, ~6.022, ~9.0, ~28.641 ]
// out => <Float64Array>[ ~6.022, ~181.0, ~0.0, ~0.0, ~0.0, ~1.0, ~5.0, ~-1.0, ~15.089, ~35.359, ~6.022, ~15.089, ~35.359, ~0.0, ~0.0 ]
```

The function has the following additional parameters:

- **strideZ**: stride length for `Z`.
- **offsetZ**: starting index for `Z`.
- **strideOut**: stride length for `out`.
- **offsetOut**: starting index for `out`.

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,

<!-- eslint-disable max-len -->

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

var Z = new Float64Array( [ 0.0, 100, 4, 81, 3, 64, 2.5, 49, 2, 36, 1.5, 25, 1, 16, 0.5, 9, 0 ] );
var out = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );

dlasq3.ndarray( 0, 3, Z, 1, 1, 0, true, out, 1, 1 );
// Z => <Float64Array>[ 0.0, ~100.0, ~181.0, ~81.0, ~28.641, ~64.0, ~84.359, ~49.0, ~20.911, ~36.0, ~40.089, ~25.0, ~9.978, ~16.0, ~6.022, ~9.0, ~28.641 ]
// out => <Float64Array>[ 0.0, ~6.022, ~181.0, ~0.0, ~0.0, ~0.0, ~1.0, ~5.0, ~-1.0, ~15.089, ~35.359, ~6.022, ~15.089, ~35.359, ~0.0, ~0.0 ]
```

</section>

<!-- /.usage -->

<section class="notes">

## Notes

- Both functions mutate the input arrays `Z` and `out`.
- The `out` array provides space to store the 15 scalar values `DMIN`, `SIGMA`, `DESIG`, `QMAX`, `NFAIL`, `ITER`, `NDIV`, `TTYPE`, `DMIN1`, `DMIN2`, `DN`, `DN1`, `DN2`, `G`, and `TAU`. These scalar values are maintained across successive calls to `dlasq3`.
- `dlasq3()` corresponds to the [LAPACK][LAPACK] routine [`dlasq3`][lapack-dlasq3].

</section>

<!-- /.notes -->

<section class="examples">

## Examples

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

<!-- eslint-disable max-len -->

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

var I0 = 0;
var N0 = 3;
var PP = 0;
var IEEE = true;

var out = new Float64Array( 15 );
var Z = new Float64Array( [ 100, 4, 81, 3, 64, 2.5, 49, 2, 36, 1.5, 25, 1, 16, 0.5, 9, 0 ] );

/*
Z is a flattened QD array of size 4*N0+4 = 16 where:
- Z[4*i] = d(i) (diagonal elements)
- Z[4*i+1] = e(i) (off-diagonal elements)
*/

// Perform the DQDS iteration:
dlasq3( I0, N0, Z, PP, IEEE, out );

console.log( Z );
console.log( out );
```

</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">

[lapack]: https://www.netlib.org/lapack/explore-html/

[lapack-dlasq3]: https://www.netlib.org/lapack/explore-html/d9/d22/group__lasq3_gab56750e63973f380503fa3f10f68ff95.html#gab56750e63973f380503fa3f10f68ff95

[@stdlib/array/float64]: https://stdlib.io/docs/api/latest/@stdlib/array/float64

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

</section>

<!-- /.links -->
104 changes: 104 additions & 0 deletions lib/node_modules/@stdlib/lapack/base/dlasq3/benchmark/benchmark.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2026 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 pow = require( '@stdlib/math/base/special/pow' );
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var Float64Array = require( '@stdlib/array/float64' );
var format = require( '@stdlib/string/format' );
var pkg = require( './../package.json' ).name;
var dlasq3 = require( './../lib/dlasq3.js' );


// VARIABLES //

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


// FUNCTIONS //

/**
* Creates a benchmark function.
*
* @private
* @param {PositiveInteger} len - array length
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var out = new Float64Array( 15 );
var Z = uniform( ( 4 * ( len + 1 ) ) + 1, 0.0, 100.0, options );
return benchmark;

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

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
dlasq3( 0, len, Z, 0, true, out );
if ( isnan( Z[ i%Z.length ] ) ) {
b.fail( 'unexpected NaN value' );
}
}
b.toc();
if ( isnan( Z[ i%Z.length ] ) ) {
b.fail( 'unexpected NaN value' );
}
b.pass( 'benchmark finished' );
b.end();
}
}


// MAIN //

/**
* Main execution sequence.
*
* @private
*/
function main() {
var len;
var min;
var max;
var f;
var i;

min = 1; // 10^min
max = 6; // 10^max

for ( i = min; i <= max; i++ ) {
len = pow( 10, i );
f = createBenchmark( len );
bench( format( '%s:len=%d', pkg, len ), f );
}
}

main();
Loading