-
-
Notifications
You must be signed in to change notification settings - Fork 843
feat: add lapack/base/dlascl
#7515
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
base: develop
Are you sure you want to change the base?
Changes from all commits
10e8866
5e0cb56
543cbc7
6420a10
9e43ff5
9cf127e
938d704
ec09f0f
1d595e0
f72cc1b
213300c
bd61b1e
cd982b0
e833c89
1b9c79e
31b4286
1940240
f60ca96
2f26be3
b30f33f
382580e
bd9df6b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,249 @@ | ||||||||||||||||||
<!-- | ||||||||||||||||||
|
||||||||||||||||||
@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. | ||||||||||||||||||
|
||||||||||||||||||
--> | ||||||||||||||||||
|
||||||||||||||||||
# dlascl | ||||||||||||||||||
|
||||||||||||||||||
> LAPACK routine to multiply a real M by N matrix `A` by a real scalar `CTO/CFROM`. | ||||||||||||||||||
|
||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I suggest adding an intro section stating something like: This routine multiplies each element of an In order to more readily avoid underflow/overflow, this routine chooses to represent |
||||||||||||||||||
<section class="usage"> | ||||||||||||||||||
|
||||||||||||||||||
## Usage | ||||||||||||||||||
|
||||||||||||||||||
```javascript | ||||||||||||||||||
var dlascl = require( '@stdlib/lapack/base/dlascl' ); | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
#### dlascl( order, type, KL, KU, CFROM, CTO, M, N, A, LDA ) | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use the actual greek characters. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In JSDoc, use |
||||||||||||||||||
|
||||||||||||||||||
Multiplies a real M by N matrix `A` by a real scalar `CTO/CFROM`. | ||||||||||||||||||
|
||||||||||||||||||
```javascript | ||||||||||||||||||
var Float64Array = require( '@stdlib/array/float64' ); | ||||||||||||||||||
|
||||||||||||||||||
var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); // => [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] | ||||||||||||||||||
|
||||||||||||||||||
dlascl( 'row-major', 'general', 0, 0, 1.0, 2.0, 3, 2, A, 2 ); | ||||||||||||||||||
// A => <Float64Array>[ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
The function has the following parameters: | ||||||||||||||||||
|
||||||||||||||||||
- **order**: storage layout. | ||||||||||||||||||
- **type**: specifies the type of matrix `A` ( should be one of these: `general`, `upper`, `lower`, `upper-hessenberg`, `symmetric-banded-lower`, `symmetric-banded-upper` or `banded` ). | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
- **KL**: lower band width of `A`. Referenced only if type is `symmetric-banded-lower` or `banded`. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
- **KU**: upper band width of `A`. Referenced only if type is `symmetric-banded-upper` or `banded`. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
- **CFROM**: the matrix `A` is multiplied by `CTO / CFROM`. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
- **CTO**: the matrix `A` is multiplied by `CTO / CFROM`. | ||||||||||||||||||
- **M**: number of rows in matrix `A`. | ||||||||||||||||||
- **N**: number of columns in matrix `A`. | ||||||||||||||||||
- **A**: input [`Float64Array`][mdn-float64array]. | ||||||||||||||||||
- **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`). | ||||||||||||||||||
|
||||||||||||||||||
If `type` is `banded`, `symmetric-banded-lower` or `symmetric-banded-upper` the matrix should be stored in the [`Band storage`][lapack-band-storage] format. | ||||||||||||||||||
|
||||||||||||||||||
Comment on lines
+59
to
+60
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
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 A0 = new Float64Array( [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); | ||||||||||||||||||
|
||||||||||||||||||
// Create offset views... | ||||||||||||||||||
Comment on lines
+68
to
+71
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
var A1 = new Float64Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element | ||||||||||||||||||
|
||||||||||||||||||
dlascl( 'row-major', 'general', 0, 0, 1.0, 2.0, 3, 2, A1, 2 ); | ||||||||||||||||||
// A0 => <Float64Array>[ 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
#### dlascl.ndarray( type, KL, KU, CFROM, CTO, M, N, A, strideA1, strideA2, offsetA ) | ||||||||||||||||||
|
||||||||||||||||||
Multiplies a real M by N matrix `A` by a real scalar `CTO/CFROM` using alternative indexing semantics. | ||||||||||||||||||
|
||||||||||||||||||
```javascript | ||||||||||||||||||
var Float64Array = require( '@stdlib/array/float64' ); | ||||||||||||||||||
|
||||||||||||||||||
var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); // => [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ] | ||||||||||||||||||
|
||||||||||||||||||
dlascl.ndarray( 'general', 0, 0, 1.0, 2.0, 3, 2, A, 2, 1, 0 ); | ||||||||||||||||||
// A => <Float64Array>[ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
The function has the following additional parameters: | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
|
||||||||||||||||||
- **type**: specifies the type of matrix `A` ( should be one of these: `general`, `upper`, `lower`, `upper-hessenberg`, `symmetric-banded-lower`, `symmetric-banded-upper` or `banded` ). | ||||||||||||||||||
- **KL**: lower band width of `A`. Referenced only if type is `symmetric-banded-lower` or `banded`. | ||||||||||||||||||
- **KU**: upper band width of `A`. Referenced only if type is `symmetric-banded-upper` or `banded`. | ||||||||||||||||||
- **CFROM**: the matrix `A` is multiplied by `CTO / CFROM`. | ||||||||||||||||||
- **CTO**: the matrix `A` is multiplied by `CTO / CFROM`. | ||||||||||||||||||
- **M**: number of rows in matrix `A`. | ||||||||||||||||||
- **N**: number of columns in matrix `A`. | ||||||||||||||||||
- **A**: input [`Float64Array`][mdn-float64array]. | ||||||||||||||||||
- **strideA1**: stride of the first dimension of `A`. | ||||||||||||||||||
- **strideA2**: stride of the second dimension of `A`. | ||||||||||||||||||
- **offsetA**: starting index for `A`. | ||||||||||||||||||
|
||||||||||||||||||
If `type` is `banded`, `symmetric-banded-lower` or `symmetric-banded-upper` the matrix should be stored in the [`Band storage`][lapack-band-storage] format. | ||||||||||||||||||
|
||||||||||||||||||
Comment on lines
+105
to
+106
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||
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( [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); | ||||||||||||||||||
|
||||||||||||||||||
dlascl.ndarray( 'general', 0, 0, 1.0, 2.0, 3, 2, A, 2, 1, 1 ); | ||||||||||||||||||
// A => <Float64Array>[ 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
</section> | ||||||||||||||||||
|
||||||||||||||||||
<!-- /.usage --> | ||||||||||||||||||
|
||||||||||||||||||
<section class="notes"> | ||||||||||||||||||
|
||||||||||||||||||
## Notes | ||||||||||||||||||
|
||||||||||||||||||
- `dlascl()` corresponds to the [LAPACK][lapack] routine [`dlascl`][lapack-dlascl]. | ||||||||||||||||||
- If `type` is `banded`, `symmetric-banded-lower` or `symmetric-banded-upper` the matrix should be stored in the [`Band storage`][lapack-band-storage] format. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. May be good to provide a brief schematic using math equations in terms of what is meant. |
||||||||||||||||||
|
||||||||||||||||||
</section> | ||||||||||||||||||
|
||||||||||||||||||
<!-- /.notes --> | ||||||||||||||||||
|
||||||||||||||||||
<section class="examples"> | ||||||||||||||||||
|
||||||||||||||||||
## Examples | ||||||||||||||||||
|
||||||||||||||||||
<!-- eslint no-undef: "error" --> | ||||||||||||||||||
|
||||||||||||||||||
```javascript | ||||||||||||||||||
var Float64Array = require( '@stdlib/array/float64' ); | ||||||||||||||||||
var dlascl = require( '@stdlib/lapack/base/dlascl' ); | ||||||||||||||||||
|
||||||||||||||||||
// Define a matrix A (3x2 in row-major order): | ||||||||||||||||||
var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); | ||||||||||||||||||
console.log( 'Initial A (row-major): ', A ); | ||||||||||||||||||
|
||||||||||||||||||
dlascl( 'row-major', 'general', 0, 0, 1.0, 2.0, 3, 2, A, 2 ); | ||||||||||||||||||
console.log( 'Scaled A (row-major): ', A ); | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
</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-dlascl]: https://www.netlib.org/lapack/explore-html-3.6.1/d7/d43/group__aux_o_t_h_e_rauxiliary_ga7bce4c35ec5a86ee0bfdd15c476d99c8.html | ||||||||||||||||||
|
||||||||||||||||||
[lapack-band-storage]: https://www.netlib.org/lapack/lug/node124.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 --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
/** | ||
* @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 dlascl = require( './../lib/dlascl.js' ); | ||
|
||
|
||
// VARIABLES // | ||
|
||
var LAYOUTS = [ | ||
'row-major', | ||
'column-major' | ||
]; | ||
|
||
|
||
// FUNCTIONS // | ||
|
||
/** | ||
* Creates a benchmark function. | ||
* | ||
* @private | ||
* @param {string} order - storage layout | ||
* @param {PositiveInteger} N - number of rows/columns | ||
* @returns {Function} benchmark function | ||
*/ | ||
function createBenchmark( order, N ) { | ||
var LDA; | ||
var A; | ||
|
||
LDA = N; | ||
|
||
A = uniform( N*N, -10.0, 10.0, { | ||
'dtype': 'float64' | ||
}); | ||
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 = dlascl( order, 'general', 0, 0, 1.0, 2.0, N, N, A, LDA ); | ||
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 min; | ||
var max; | ||
var ord; | ||
var N; | ||
var f; | ||
var i; | ||
var k; | ||
|
||
min = 1; // 10^min | ||
max = 6; // 10^max | ||
|
||
for ( k = 0; k < LAYOUTS.length; k++ ) { | ||
ord = LAYOUTS[ k ]; | ||
for ( i = min; i <= max; i++ ) { | ||
N = floor( pow( pow( 10, i ), 1.0/2.0 ) ); | ||
f = createBenchmark( ord, N ); | ||
bench( pkg+'::square_matrix:order='+ord+',size='+(N*N), f ); | ||
} | ||
} | ||
} | ||
|
||
main(); |
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.