From c305bbc0fc0253e02ec37c2305827296d53649e0 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Wed, 28 May 2025 11:48:22 +0000 Subject: [PATCH 01/16] feat: add base implementation --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/lib/base.js | 116 ++++++++++++++++++ .../@stdlib/lapack/base/dlarfg/lib/dlapy2.js | 67 ++++++++++ 2 files changed, 183 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js new file mode 100644 index 000000000000..f1a4b9a4528a --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -0,0 +1,116 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 dnrm2 = require( '@stdlib/blas/base/dnrm2' ).ndarray; +var sign = require( '@stdlib/math/base/special/copysign' ); +var dlamch = require( '@stdlib/lapack/base/dlamch' ); +var abs = require( '@stdlib/math/base/special/abs' ); +var dscal = require( '@stdlib/blas/base/dscal' ).ndarray; +var dlapy2 = require( './dlapy2.js' ); + + +// MAIN // + +/** +* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* +* ## Notes +* +* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* +* @private +* @param {NonNegativeInteger} N - order of matrix `A` +* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {integer} strideX - stride length for `X` +* @param {NonNegativeInteger} offsetX - starting index of `X` +* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @param {integer} strideOut - stride length for `out` +* @param {NonNegativeInteger} offsetOut - starting index of `out` +* @returns {void} overwrites the array `X` and `out` in place +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg( 4, X, 1, 0, out, 1, 0 ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +*/ +function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { + var safemin; + var rsafmin; + var xnorm; + var alpha; + var beta; + var tau; + var knt; + var i; + + if ( N <= 1 ) { + tau = 0.0; // tau = 0.0 + out[ offsetOut + strideOut ] = tau; + return; + } + + xnorm = dnrm2( N - 1, X, strideX, offsetX ); + alpha = out[ offsetOut ]; + + if ( xnorm === 0.0 ) { + tau = 0.0; // tau = 0.0 + out[ strideOut + offsetOut ] = tau; + } else { + beta = -1.0 * sign( dlapy2( alpha, xnorm ), alpha ); + safemin = dlamch( 'S' ) / dlamch( 'E' ); + knt = 0; + if ( abs( beta ) < safemin ) { + rsafmin = 1.0 / safemin; + while ( abs( beta ) < safemin && knt < 20 ) { + knt += 1; + dscal( N-1, rsafmin, X, strideX, offsetX ); + beta *= rsafmin; + alpha *= rsafmin; // alpha *= rsafmin + } + xnorm = dnrm2( N - 1, X, strideX, offsetX ); + beta = -1.0 * sign( dlapy2( alpha, xnorm ), alpha ); + } + tau = ( beta - alpha ) / beta; // tau = (beta - alpha) / beta + dscal( N-1, 1.0 / ( alpha - beta ), X, strideX, offsetX ); + for ( i = 0; i < knt; i++ ) { + beta *= safemin; + } + alpha = beta; + + out[ offsetOut ] = alpha; + out[ strideOut + offsetOut ] = tau; + } +} + + +// EXPORTS // + +module.exports = dlarfg; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js new file mode 100644 index 000000000000..7041101c9b77 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js @@ -0,0 +1,67 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 abs = require( '@stdlib/math/base/special/abs' ); +var min = require( '@stdlib/math/base/special/min' ); +var max = require( '@stdlib/math/base/special/max' ); +var sqrt = require( '@stdlib/math/base/special/sqrt' ); +var pow = require( '@stdlib/math/base/special/pow' ); + + +// MAIN // + +/** +* Returns sqrt( x^2 + y^2 ) in a manner which doesn't cause unnecessary overflow. +* +* @private +* @param {number} x - order of matrix `A` +* @param {number} y - order of matrix `A` +* @returns {integer} status code +* +* @example +* var out = dlapy2( 3.0, 4.0, ); +* // returns 5 +*/ +function dlapy2( x, y ) { + // TODO - make a separate package for this + var xabs; + var yabs; + var w; + var z; + + xabs = abs( x ); + yabs = abs( y ); + + w = max( xabs, yabs ); + z = min( xabs, yabs ); + + if ( z === 0.0 ) { + return w; + } + + return w * ( sqrt( 1.0 + pow( z / w, 2.0 ) ) ); +} + + +// EXPORTS // + +module.exports = dlapy2; From e833bc462d63a7e1773895844a846b84ff3ac4ff Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Wed, 28 May 2025 12:40:15 +0000 Subject: [PATCH 02/16] feat: complete main exports --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/lib/base.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/dlapy2.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 63 +++++++++++++++ .../@stdlib/lapack/base/dlarfg/lib/index.js | 79 +++++++++++++++++++ .../@stdlib/lapack/base/dlarfg/lib/main.js | 35 ++++++++ .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 66 ++++++++++++++++ 6 files changed, 245 insertions(+), 2 deletions(-) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/main.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index f1a4b9a4528a..29b0e2f5eaba 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2024 The Stdlib Authors. +* 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. diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js index 7041101c9b77..e23eec83643e 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2024 The Stdlib Authors. +* 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. diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js new file mode 100644 index 000000000000..5ec7343b5c66 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -0,0 +1,63 @@ +/** +* @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 base = require( './base.js' ); + + +// MAIN // + +/** +* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* +* ## Notes +* +* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* +* @private +* @param {NonNegativeInteger} N - order of matrix `A` +* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {integer} incx - stride length for `X` +* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @returns {void} overwrites the array `X` and `out` in place +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg( 4, X, 1, out ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +*/ +function dlarfg( N, X, incx, out ) { + base( N, X, incx, 0, out, 1, 0 ); +} + + +// EXPORTS // + +module.exports = dlarfg; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js new file mode 100644 index 000000000000..17267b82356c --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js @@ -0,0 +1,79 @@ +/** +* @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'; + +/** +* LAPACK routine to generate a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* +* ## Notes +* +* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* +* @module @stdlib/lapack/base/dlarfg +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var dlarfg = require( '@stdlib/lapack/base/dlarfg' ); +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg( 4, X, 1, out ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var dlarfg = require( '@stdlib/lapack/base/dlarfg' ); + +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +*/ + +// MODULES // + +var join = require( 'path' ).join; +var tryRequire = require( '@stdlib/utils/try-require' ); +var isError = require( '@stdlib/assert/is-error' ); +var main = require( './main.js' ); + + +// MAIN // + +var dlarfg; +var tmp = tryRequire( join( __dirname, './native.js' ) ); +if ( isError( tmp ) ) { + dlarfg = main; +} else { + dlarfg = tmp; +} + + +// EXPORTS // + +module.exports = dlarfg; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/main.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/main.js new file mode 100644 index 000000000000..c7d8c0cc83fd --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/main.js @@ -0,0 +1,35 @@ +/** +* @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 setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var dlarfg = require( './dlarfg.js' ); +var ndarray = require( './ndarray.js' ); + + +// MAIN // + +setReadOnly( dlarfg, 'ndarray', ndarray ); + + +// EXPORTS // + +module.exports = dlarfg; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js new file mode 100644 index 000000000000..a01c129f87ef --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -0,0 +1,66 @@ +/** +* @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 base = require( './base.js' ); + + +// MAIN // + +/** +* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* +* ## Notes +* +* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* +* @private +* @param {NonNegativeInteger} N - order of matrix `A` +* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {integer} strideX - stride length for `X` +* @param {NonNegativeInteger} offsetX - starting index of `X` +* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @param {integer} strideOut - stride length for `out` +* @param {NonNegativeInteger} offsetOut - starting index of `out` +* @returns {void} overwrites the array `X` and `out` in place +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg( 4, X, 1, 0, out, 1, 0 ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +*/ +function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { + base( N, X, strideX, offsetX, out, strideOut, offsetOut ); +} + + +// EXPORTS // + +module.exports = dlarfg; From 39a04b79d312391413b60374fdbbe47b659ed4b9 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 05:56:18 +0000 Subject: [PATCH 03/16] test: add tests --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../dlarfg/test/fixtures/n_eq_one_test.json | 11 +++ .../dlarfg/test/fixtures/n_gt_one_test.json | 11 +++ .../lapack/base/dlarfg/test/test.dlarfg.js | 89 +++++++++++++++++++ .../@stdlib/lapack/base/dlarfg/test/test.js | 82 +++++++++++++++++ 4 files changed, 193 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_eq_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_gt_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.js diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_eq_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_eq_one_test.json new file mode 100644 index 000000000000..f440195e8dec --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_eq_one_test.json @@ -0,0 +1,11 @@ +{ + "N": 1, + "X": [], + "strideX": 1, + "offsetX": 0, + "out": [ 4.0, 0.0 ], + "strideOut": 1, + "offsetOut": 0, + "expectedX": [], + "expectedOut": [ 4.0, 0.0 ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_gt_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_gt_one_test.json new file mode 100644 index 000000000000..2e97d2698f09 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/n_gt_one_test.json @@ -0,0 +1,11 @@ +{ + "N": 4, + "X": [ 2.0, 3.0, 4.0 ], + "strideX": 1, + "offsetX": 0, + "out": [ 4.0, 0.0 ], + "strideOut": 1, + "offsetOut": 0, + "expectedX": [ 0.18677268499995647, 0.28015902749993471, 0.37354536999991295 ], + "expectedOut": [ -6.7082039324993685, 1.5962847939999441 ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js new file mode 100644 index 000000000000..5ee129e26979 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js @@ -0,0 +1,89 @@ +/** +* @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 tape = require( 'tape' ); +var Float64Array = require( '@stdlib/array/float64' ); +var dlarfg = require( './../lib/dlarfg.js' ); + + +// FIXTURES // + +var N_GT_ONE_DATA = require( './fixtures/n_gt_one_test.json' ); +var N_EQ_ONE_DATA = require( './fixtures/n_eq_one_test.json' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof dlarfg, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function has an arity of 4', function test( t ) { + t.strictEqual( dlarfg.length, 4, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N > 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, out ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, out ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.js new file mode 100644 index 000000000000..b7eccd0bc69f --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.js @@ -0,0 +1,82 @@ +/** +* @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 tape = require( 'tape' ); +var proxyquire = require( 'proxyquire' ); +var IS_BROWSER = require( '@stdlib/assert/is-browser' ); +var dlarfg = require( './../lib' ); + + +// VARIABLES // + +var opts = { + 'skip': IS_BROWSER +}; + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof dlarfg, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the main export is a method providing an ndarray interface', function test( t ) { + t.strictEqual( typeof dlarfg.ndarray, 'function', 'method is a function' ); + t.end(); +}); + +tape( 'if a native implementation is available, the main export is the native implementation', opts, function test( t ) { + var dlarfg = proxyquire( './../lib', { + '@stdlib/utils/try-require': tryRequire + }); + + t.strictEqual( dlarfg, mock, 'returns expected value' ); + t.end(); + + function tryRequire() { + return mock; + } + + function mock() { + // Mock... + } +}); + +tape( 'if a native implementation is not available, the main export is a JavaScript implementation', opts, function test( t ) { + var dlarfg; + var main; + + main = require( './../lib/dlarfg.js' ); + + dlarfg = proxyquire( './../lib', { + '@stdlib/utils/try-require': tryRequire + }); + + t.strictEqual( dlarfg, main, 'returns expected value' ); + t.end(); + + function tryRequire() { + return new Error( 'Cannot find module' ); + } +}); From a3c6ca5945a2e9ad5dbe23817012b5d12d265bb7 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 06:14:54 +0000 Subject: [PATCH 04/16] test: more tests --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../test/fixtures/small_values_test.json | 11 +++++ .../test/fixtures/xnorm_eq_zerro_test.json | 11 +++++ .../lapack/base/dlarfg/test/test.dlarfg.js | 46 +++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/small_values_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/xnorm_eq_zerro_test.json diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/small_values_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/small_values_test.json new file mode 100644 index 000000000000..77bef0709a13 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/small_values_test.json @@ -0,0 +1,11 @@ +{ + "N": 4, + "X": [ 2.2250738585217783e-313, 2.2250738585217783e-313, 2.2250738585217783e-313 ], + "strideX": 1, + "offsetX": 0, + "out": [ 2.2250738585217783e-313, 0.0 ], + "strideOut": 1, + "offsetOut": 0, + "expectedX": [ 0.33333333333333337, 0.33333333333333337, 0.33333333333333337 ], + "expectedOut": [ -4.4501477170435566e-313, 1.5 ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/xnorm_eq_zerro_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/xnorm_eq_zerro_test.json new file mode 100644 index 000000000000..60eca89aeee7 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/xnorm_eq_zerro_test.json @@ -0,0 +1,11 @@ +{ + "N": 4, + "X": [ 0.0, 0.0, 0.0 ], + "strideX": 1, + "offsetX": 0, + "out": [ 4.0, 0.0 ], + "strideOut": 1, + "offsetOut": 0, + "expectedX": [ 0.0, 0.0, 0.0 ], + "expectedOut": [ 4.0, 0.0 ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js index 5ee129e26979..dbf4566919e8 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.dlarfg.js @@ -29,6 +29,8 @@ var dlarfg = require( './../lib/dlarfg.js' ); var N_GT_ONE_DATA = require( './fixtures/n_gt_one_test.json' ); var N_EQ_ONE_DATA = require( './fixtures/n_eq_one_test.json' ); +var XNORM_EQ_ZERO_DATA = require( './fixtures/xnorm_eq_zerro_test.json' ); +var SMALL_VALUES_DATA = require( './fixtures/small_values_test.json' ); // TESTS // @@ -87,3 +89,47 @@ tape( 'the function returns expected output when N = 1', function test( t ) { t.deepEqual( out, expectedOut, 'returns expected value' ); t.end(); }); + +tape( 'the function returns expected output when xnorm = 0', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, out ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, out ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); From 983d3bd5bd2fd9533ec1bc7f4b81c4ab8fabfc58 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 06:34:38 +0000 Subject: [PATCH 05/16] test: add ndarray tests --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../fixtures/large_strides/n_eq_one_test.json | 21 +++++++++++ .../fixtures/large_strides/n_gt_one_test.json | 35 +++++++++++++++++++ .../large_strides/small_values_test.json | 35 +++++++++++++++++++ .../large_strides/xnorm_eq_zerro_test.json | 35 +++++++++++++++++++ .../negative_strides/n_eq_one_test.json | 20 +++++++++++ .../negative_strides/n_gt_one_test.json | 28 +++++++++++++++ .../negative_strides/small_values_test.json | 28 +++++++++++++++ .../negative_strides/xnorm_eq_zerro_test.json | 28 +++++++++++++++ .../test/fixtures/offsets/n_eq_one_test.json | 23 ++++++++++++ .../test/fixtures/offsets/n_gt_one_test.json | 29 +++++++++++++++ .../fixtures/offsets/small_values_test.json | 29 +++++++++++++++ .../fixtures/offsets/xnorm_eq_zerro_test.json | 29 +++++++++++++++ 12 files changed, 340 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_eq_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_gt_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/small_values_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/xnorm_eq_zerro_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_eq_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_gt_one_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/small_values_test.json create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/xnorm_eq_zerro_test.json diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_eq_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_eq_one_test.json new file mode 100644 index 000000000000..1e5ec6ce4851 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_eq_one_test.json @@ -0,0 +1,21 @@ +{ + "N": 1, + "X": [], + "strideX": 2, + "offsetX": 0, + "out": [ + 4.0, + 9999.0, + 0.0, + 9999.0 + ], + "strideOut": 2, + "offsetOut": 0, + "expectedX": [], + "expectedOut": [ + 4.0, + 9999.0, + 0.0, + 9999.0 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_gt_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_gt_one_test.json new file mode 100644 index 000000000000..594af1d847a3 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/n_gt_one_test.json @@ -0,0 +1,35 @@ +{ + "N": 4, + "X": [ + 2, + 9999.0, + 3, + 9999.0, + 4, + 9999 + ], + "strideX": 2, + "offsetX": 0, + "out": [ + 4, + 9999.0, + 0, + 9999 + ], + "strideOut": 2, + "offsetOut": 0, + "expectedX": [ + 0.18677268499995647, + 9999.0, + 0.2801590274999347, + 9999.0, + 0.37354536999991295, + 9999 + ], + "expectedOut": [ + -6.7082039324993685, + 9999.0, + 1.596284793999944, + 9999 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/small_values_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/small_values_test.json new file mode 100644 index 000000000000..42d2c19e28f7 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/small_values_test.json @@ -0,0 +1,35 @@ +{ + "N": 4, + "X": [ + 2.2250738585e-313, + 9999.0, + 2.2250738585e-313, + 9999.0, + 2.2250738585e-313, + 9999.0 + ], + "strideX": 2, + "offsetX": 0, + "out": [ + 2.2250738585e-313, + 9999.0, + 0, + 9999.0 + ], + "strideOut": 2, + "offsetOut": 0, + "expectedX": [ + 0.33333333333333337, + 9999.0, + 0.33333333333333337, + 9999.0, + 0.33333333333333337, + 9999.0 + ], + "expectedOut": [ + -4.45014771704e-313, + 9999.0, + 1.5, + 9999.0 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/xnorm_eq_zerro_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/xnorm_eq_zerro_test.json new file mode 100644 index 000000000000..358c40ae991e --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/large_strides/xnorm_eq_zerro_test.json @@ -0,0 +1,35 @@ +{ + "N": 4, + "X": [ + 0.0, + 9999.0, + 0.0, + 9999.0, + 0.0, + 9999.0 + ], + "strideX": 2, + "offsetX": 0, + "out": [ + 4.0, + 9999.0, + 0.0, + 9999.0 + ], + "strideOut": 2, + "offsetOut": 0, + "expectedX": [ + 0.0, + 9999.0, + 0.0, + 9999.0, + 0.0, + 9999.0 + ], + "expectedOut": [ + 4.0, + 9999.0, + 0.0, + 9999.0 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json new file mode 100644 index 000000000000..ed755417ed02 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json @@ -0,0 +1,20 @@ +{ + "N": 1, + "X": [], + "strideX": -1, + "offsetX": -1, + "out": [ + 0.0, + 4.0 + ], + "strideOut": -1, + "offsetOut": 0, + "expectedX": [], + "expectedOut": [ + 0.0, + 4.0 + ], + "offsetout": 1, + "offsetexpectedX": -1, + "offsetexpectedOut": 1 +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json new file mode 100644 index 000000000000..682d4a7f1116 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json @@ -0,0 +1,28 @@ +{ + "N": 4, + "X": [ + 4.0, + 3.0, + 2.0 + ], + "strideX": -1, + "offsetX": 2, + "out": [ + 0.0, + 4.0 + ], + "strideOut": -1, + "offsetOut": 0, + "expectedX": [ + 0.37354536999991295, + 0.2801590274999347, + 0.18677268499995647 + ], + "expectedOut": [ + 1.596284793999944, + -6.7082039324993685 + ], + "offsetout": 1, + "offsetexpectedX": 2, + "offsetexpectedOut": 1 +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json new file mode 100644 index 000000000000..4b1aff4a1001 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json @@ -0,0 +1,28 @@ +{ + "N": 4, + "X": [ + 2.2250738585e-313, + 2.2250738585e-313, + 2.2250738585e-313 + ], + "strideX": -1, + "offsetX": 2, + "out": [ + 0.0, + 2.2250738585e-313 + ], + "strideOut": -1, + "offsetOut": 0, + "expectedX": [ + 0.33333333333333337, + 0.33333333333333337, + 0.33333333333333337 + ], + "expectedOut": [ + 1.5, + -4.45014771704e-313 + ], + "offsetout": 1, + "offsetexpectedX": 2, + "offsetexpectedOut": 1 +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json new file mode 100644 index 000000000000..007f58c81d6b --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json @@ -0,0 +1,28 @@ +{ + "N": 4, + "X": [ + 0.0, + 0.0, + 0.0 + ], + "strideX": -1, + "offsetX": 2, + "out": [ + 0.0, + 4.0 + ], + "strideOut": -1, + "offsetOut": 0, + "expectedX": [ + 0.0, + 0.0, + 0.0 + ], + "expectedOut": [ + 0.0, + 4.0 + ], + "offsetout": 1, + "offsetexpectedX": 2, + "offsetexpectedOut": 1 +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_eq_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_eq_one_test.json new file mode 100644 index 000000000000..aea21703f1bb --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_eq_one_test.json @@ -0,0 +1,23 @@ +{ + "N": 1, + "X": [ + 9999.0 + ], + "strideX": 1, + "offsetX": 1, + "out": [ + 9999.0, + 4.0, + 0.0 + ], + "strideOut": 1, + "offsetOut": 1, + "expectedX": [ + 9999.0 + ], + "expectedOut": [ + 9999.0, + 4.0, + 0.0 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_gt_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_gt_one_test.json new file mode 100644 index 000000000000..08ff089c9f07 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/n_gt_one_test.json @@ -0,0 +1,29 @@ +{ + "N": 4, + "X": [ + 9999.0, + 2.0, + 3.0, + 4.0 + ], + "strideX": 1, + "offsetX": 1, + "out": [ + 9999.0, + 4.0, + 0.0 + ], + "strideOut": 1, + "offsetOut": 1, + "expectedX": [ + 9999.0, + 0.18677268499995647, + 0.2801590274999347, + 0.37354536999991295 + ], + "expectedOut": [ + 9999.0, + -6.7082039324993685, + 1.596284793999944 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/small_values_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/small_values_test.json new file mode 100644 index 000000000000..8c3c2fb4042c --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/small_values_test.json @@ -0,0 +1,29 @@ +{ + "N": 4, + "X": [ + 9999.0, + 2.2250738585e-313, + 2.2250738585e-313, + 2.2250738585e-313 + ], + "strideX": 1, + "offsetX": 1, + "out": [ + 9999.0, + 2.2250738585e-313, + 0 + ], + "strideOut": 1, + "offsetOut": 1, + "expectedX": [ + 9999.0, + 0.33333333333333337, + 0.33333333333333337, + 0.33333333333333337 + ], + "expectedOut": [ + 9999.0, + -4.45014771704e-313, + 1.5 + ] +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/xnorm_eq_zerro_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/xnorm_eq_zerro_test.json new file mode 100644 index 000000000000..a4593dd60696 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/offsets/xnorm_eq_zerro_test.json @@ -0,0 +1,29 @@ +{ + "N": 4, + "X": [ + 9999.0, + 0.0, + 0.0, + 0 + ], + "strideX": 1, + "offsetX": 1, + "out": [ + 9999.0, + 4.0, + 0.0 + ], + "strideOut": 1, + "offsetOut": 1, + "expectedX": [ + 9999.0, + 0.0, + 0.0, + 0 + ], + "expectedOut": [ + 9999.0, + 4.0, + 0.0 + ] +} From 9a7d15899a5071abfb38bccc234d6ea8be3538da Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 08:02:49 +0000 Subject: [PATCH 06/16] test: add ndarray tests --- .../lapack/base/dlarfg/test/test.ndarray.js | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js new file mode 100644 index 000000000000..08b264642e94 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js @@ -0,0 +1,152 @@ +/** +* @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. +*/ + +/* eslint-disable max-len */ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var Float64Array = require( '@stdlib/array/float64' ); +var dlarfg = require( './../lib/ndarray.js' ); + + +// FIXTURES // + +var N_GT_ONE_DATA = require( './fixtures/n_gt_one_test.json' ); +var N_EQ_ONE_DATA = require( './fixtures/n_eq_one_test.json' ); +var XNORM_EQ_ZERO_DATA = require( './fixtures/xnorm_eq_zerro_test.json' ); +var SMALL_VALUES_DATA = require( './fixtures/small_values_test.json' ); + +var OFFSET_N_GT_ONE_DATA = require( './fixtures/offsets/n_gt_one_test.json' ); +var OFFSET_N_EQ_ONE_DATA = require( './fixtures/offsets/n_eq_one_test.json' ); +var OFFSET_XNORM_EQ_ZERO_DATA = require( './fixtures/offsets/xnorm_eq_zerro_test.json' ); +var OFFSET_SMALL_VALUES_DATA = require( './fixtures/offsets/small_values_test.json' ); + +var NEG_STRIDE_N_GT_ONE_DATA = require( './fixtures/negative_strides/n_gt_one_test.json' ); +var NEG_STRIDE_N_EQ_ONE_DATA = require( './fixtures/negative_strides/n_eq_one_test.json' ); +var NEG_STRIDE_XNORM_EQ_ZERO_DATA = require( './fixtures/negative_strides/xnorm_eq_zerro_test.json' ); +var NEG_STRIDE_SMALL_VALUES_DATA = require( './fixtures/negative_strides/small_values_test.json' ); + +var LARGE_STRIDE_N_GT_ONE_DATA = require( './fixtures/large_strides/n_gt_one_test.json' ); +var LARGE_STRIDE_N_EQ_ONE_DATA = require( './fixtures/large_strides/n_eq_one_test.json' ); +var LARGE_STRIDE_XNORM_EQ_ZERO_DATA = require( './fixtures/large_strides/xnorm_eq_zerro_test.json' ); +var LARGE_STRIDE_SMALL_VALUES_DATA = require( './fixtures/large_strides/small_values_test.json' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof dlarfg, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function has an arity of 7', function test( t ) { + t.strictEqual( dlarfg.length, 7, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N > 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when xnorm = 0', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); From c30263739b1e992f667ffdb33cf4c0d2f27b7d55 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 08:08:57 +0000 Subject: [PATCH 07/16] test: add all ndarray tests --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../negative_strides/n_eq_one_test.json | 2 +- .../negative_strides/n_gt_one_test.json | 2 +- .../negative_strides/small_values_test.json | 2 +- .../negative_strides/xnorm_eq_zerro_test.json | 2 +- .../lapack/base/dlarfg/test/test.ndarray.js | 354 +++++++++++++++++- 5 files changed, 357 insertions(+), 5 deletions(-) diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json index ed755417ed02..fb498939e7b4 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_eq_one_test.json @@ -8,7 +8,7 @@ 4.0 ], "strideOut": -1, - "offsetOut": 0, + "offsetOut": 1, "expectedX": [], "expectedOut": [ 0.0, diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json index 682d4a7f1116..3722a2b452e1 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/n_gt_one_test.json @@ -12,7 +12,7 @@ 4.0 ], "strideOut": -1, - "offsetOut": 0, + "offsetOut": 1, "expectedX": [ 0.37354536999991295, 0.2801590274999347, diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json index 4b1aff4a1001..6b27a74937ae 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/small_values_test.json @@ -12,7 +12,7 @@ 2.2250738585e-313 ], "strideOut": -1, - "offsetOut": 0, + "offsetOut": 1, "expectedX": [ 0.33333333333333337, 0.33333333333333337, diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json index 007f58c81d6b..635c53311e7d 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/fixtures/negative_strides/xnorm_eq_zerro_test.json @@ -12,7 +12,7 @@ 4.0 ], "strideOut": -1, - "offsetOut": 0, + "offsetOut": 1, "expectedX": [ 0.0, 0.0, diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js index 08b264642e94..1334568019f3 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/test/test.ndarray.js @@ -16,7 +16,7 @@ * limitations under the License. */ -/* eslint-disable max-len */ +/* eslint-disable max-len, id-length */ 'use strict'; @@ -150,3 +150,355 @@ tape( 'the function returns expected output for small values', function test( t t.deepEqual( out, expectedOut, 'returns expected value' ); t.end(); }); + +tape( 'the function returns expected output when N > 1 (offsets)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = OFFSET_N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1 (offsets)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = OFFSET_N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when xnorm = 0 (offsets)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = OFFSET_XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values (offsets)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = OFFSET_SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N > 1 (large strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = LARGE_STRIDE_N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1 (large strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = LARGE_STRIDE_N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when xnorm = 0 (large strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = LARGE_STRIDE_XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values (large strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = LARGE_STRIDE_SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N > 1 (negative strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = NEG_STRIDE_N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1 (negative strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = NEG_STRIDE_N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when xnorm = 0 (negative strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = NEG_STRIDE_XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values (negative strides)', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = NEG_STRIDE_SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N > 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_GT_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when N = 1', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = N_EQ_ONE_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output when xnorm = 0', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = XNORM_EQ_ZERO_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns expected output for small values', function test( t ) { + var expectedOut; + var expectedX; + var data; + var out; + var X; + + data = SMALL_VALUES_DATA; + + X = new Float64Array( data.X ); + out = new Float64Array( data.out ); + + expectedX = new Float64Array( data.expectedX ); + expectedOut = new Float64Array( data.expectedOut ); + + dlarfg( data.N, X, data.strideX, data.offsetX, out, data.strideOut, data.offsetOut ); + + t.deepEqual( X, expectedX, 'returns expected value' ); + t.deepEqual( out, expectedOut, 'returns expected value' ); + t.end(); +}); From d685395c16ce0db3b33be5b746ac4a56d28389e2 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 08:37:11 +0000 Subject: [PATCH 08/16] feat: add benchmarks and examples --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../lapack/base/dlarfg/benchmark/benchmark.js | 103 ++++++++++++++++++ .../dlarfg/benchmark/benchmark.ndarray.js | 103 ++++++++++++++++++ .../lapack/base/dlarfg/examples/index.js | 40 +++++++ .../@stdlib/lapack/base/dlarfg/package.json | 69 ++++++++++++ 4 files changed, 315 insertions(+) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.ndarray.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/examples/index.js create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/package.json diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.js new file mode 100644 index 000000000000..fccf79d1baae --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.js @@ -0,0 +1,103 @@ +/** +* @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 pkg = require( './../package.json' ).name; +var dlarfg = require( './../lib/dlarfg.js' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} N - number of elements along each dimension +* @returns {Function} benchmark function +*/ +function createBenchmark( N ) { + var opts; + var out; + var X; + + opts = { + 'dtype': 'float64' + }; + + X = uniform( N-1, -10.0, 10.0, opts ); + out = uniform( 2, -10.0, 10.0, opts ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + dlarfg( N, X, 1, out ); + if ( isnan( X[ i%X.length ] ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( X[ i%X.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 N; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + N = pow( 10, i ); + f = createBenchmark( N ); + bench( pkg+':size='+(N), f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.ndarray.js new file mode 100644 index 000000000000..70fbbc5b8851 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/benchmark/benchmark.ndarray.js @@ -0,0 +1,103 @@ +/** +* @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 pkg = require( './../package.json' ).name; +var dlarfg = require( './../lib/ndarray.js' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} N - number of elements along each dimension +* @returns {Function} benchmark function +*/ +function createBenchmark( N ) { + var opts; + var out; + var X; + + opts = { + 'dtype': 'float64' + }; + + X = uniform( N-1, -10.0, 10.0, opts ); + out = uniform( 2, -10.0, 10.0, opts ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + dlarfg( N, X, 1, 0, out, 1, 0 ); + if ( isnan( X[ i%X.length ] ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( X[ i%X.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 N; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + N = pow( 10, i ); + f = createBenchmark( N ); + bench( pkg+':size='+(N), f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/examples/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/examples/index.js new file mode 100644 index 000000000000..bc6a258e1854 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/examples/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +var uniform = require( '@stdlib/random/array/discrete-uniform' ); +var Float64Array = require( '@stdlib/array/float64' ); +var dlarfg = require( './../lib' ); + +var N = 4; + +var X = uniform( N - 1, -10, 10, { + 'dtype': 'float64' +}); +console.log( 'X: ', X ); + +var alpha = 4.0; + +var out = new Float64Array( [ alpha, 0.0 ] ); + +dlarfg( N, X, 1, out ); + +console.log( 'V: ', X ); +console.log( 'beta: ', out[ 0 ] ); +console.log( 'tau: ', out[ 1 ] ); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json new file mode 100644 index 000000000000..f47e91dc0696 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json @@ -0,0 +1,69 @@ +{ + "name": "@stdlib/lapack/base/dlarfg", + "version": "0.0.0", + "description": "LAPACK routine to generate a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdmath", + "mathematics", + "math", + "lapack", + "dlarfg", + "copy", + "linear", + "algebra", + "subroutines", + "array", + "ndarray", + "matrix", + "float64", + "double", + "float64array" + ] +} From 4632c5bbc9d02f6d3037b3f94ec854577bfd62aa Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 29 May 2025 11:23:11 +0000 Subject: [PATCH 09/16] docs: add ts files --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed --- --- .../lapack/base/dlarfg/docs/types/index.d.ts | 119 +++++++++ .../lapack/base/dlarfg/docs/types/test.ts | 229 ++++++++++++++++++ .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 1 - .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 1 - 4 files changed, 348 insertions(+), 2 deletions(-) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/test.ts diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts new file mode 100644 index 000000000000..e899ab506c8c --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -0,0 +1,119 @@ +/* +* @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. +*/ + +// TypeScript Version: 4.1 + +/** +* Interface describing `dlarfg`. +*/ +interface Routine { + /** + * Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. + * + * ## Notes + * + * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. + * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. + * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. + * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. + * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. + * + * @param N - order of matrix `A` + * @param X - overwritten by the vector `V` on exit + * @param incx - stride length for `X` + * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` + * @returns overwrites the array `X` and `out` in place + * + * @example + * var Float64Array = require( '@stdlib/array/float64' ); + * + * var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); + * var out = new Float64Array( [ 4.0, 0.0 ] ); + * + * dlarfg( 4, X, 1, out ); + * // X => [ ~0.19, ~0.28, ~0.37 ] + * // out => [ ~6.7, ~1.6 ] + */ + ( N: number, X: Float64Array, incx: number, out: Float64Array ): void; + + /** + * Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. + * + * ## Notes + * + * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. + * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. + * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. + * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. + * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. + * + * @param N - order of matrix `A` + * @param X - overwritten by the vector `V` on exit + * @param strideX - stride length for `X` + * @param offsetX - starting index of `X` + * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` + * @param strideOut - stride length for `out` + * @param offsetOut - starting index of `out` + * @returns overwrites the array `X` and `out` in place + * + * @example + * var Float64Array = require( '@stdlib/array/float64' ); + * + * var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); + * var out = new Float64Array( [ 4.0, 0.0 ] ); + * + * dlarfg( 4, X, 1, 0, out, 1, 0 ); + * // X => [ ~0.19, ~0.28, ~0.37 ] + * // out => [ ~6.7, ~1.6 ] + */ + ndarray( N: number, X: Float64Array, strideX: number, offsetX: number, out: Float64Array, strideOut: number, offsetOut: number ): void; +} + +/** +* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* +* ## Notes +* +* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* +* @param N - order of matrix `A` +* @param X - overwritten by the vector `V` on exit +* @param incx - stride length for `X` +* @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @returns overwrites the array `X` and `out` in place +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +* var out = new Float64Array( [ 4.0, 0.0 ] ); +* +* dlarfg( 4, X, 1, out ); +* // X => [ ~0.19, ~0.28, ~0.37 ] +* // out => [ ~6.7, ~1.6 ] +*/ +declare var dlarfg: Routine; + + +// EXPORTS // + +export = dlarfg; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/test.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/test.ts new file mode 100644 index 000000000000..2fff79e07f68 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/test.ts @@ -0,0 +1,229 @@ +/* +* @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. +*/ + +import dlarfg = require( './index' ); + + +// TESTS // + +// The function returns undefined... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg( 4, X, 1, out ); // $ExpectType void +} + +// The compiler throws an error if the function is provided a first argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg( '5', X, 1, out ); // $ExpectError + dlarfg( true, X, 1, out ); // $ExpectError + dlarfg( false, X, 1, out ); // $ExpectError + dlarfg( null, X, 1, out ); // $ExpectError + dlarfg( void 0, X, 1, out ); // $ExpectError + dlarfg( [], X, 1, out ); // $ExpectError + dlarfg( {}, X, 1, out ); // $ExpectError + dlarfg( ( x: number ): number => x, X, 1, out ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a Float64Array... +{ + const out = new Float64Array( 2 ); + + dlarfg( 4, '5', 1, out ); // $ExpectError + dlarfg( 4, 5, 1, out ); // $ExpectError + dlarfg( 4, true, 1, out ); // $ExpectError + dlarfg( 4, false, 1, out ); // $ExpectError + dlarfg( 4, null, 1, out ); // $ExpectError + dlarfg( 4, void 0, 1, out ); // $ExpectError + dlarfg( 4, [], 1, out ); // $ExpectError + dlarfg( 4, {}, 1, out ); // $ExpectError + dlarfg( 4, ( x: number ): number => x, 1, out ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg( 4, X, '1', out ); // $ExpectError + dlarfg( 4, X, true, out ); // $ExpectError + dlarfg( 4, X, false, out ); // $ExpectError + dlarfg( 4, X, null, out ); // $ExpectError + dlarfg( 4, X, void 0, out ); // $ExpectError + dlarfg( 4, X, [], out ); // $ExpectError + dlarfg( 4, X, {}, out ); // $ExpectError + dlarfg( 4, X, ( x: number ): number => x, out ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a Float64Array... +{ + const X = new Float64Array( 3 ); + + dlarfg( 4, X, 1, '5' ); // $ExpectError + dlarfg( 4, X, 1, 5 ); // $ExpectError + dlarfg( 4, X, 1, true ); // $ExpectError + dlarfg( 4, X, 1, false ); // $ExpectError + dlarfg( 4, X, 1, null ); // $ExpectError + dlarfg( 4, X, 1, void 0 ); // $ExpectError + dlarfg( 4, X, 1, [] ); // $ExpectError + dlarfg( 4, X, 1, {} ); // $ExpectError + dlarfg( 4, X, 1, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg(); // $ExpectError + dlarfg( 4 ); // $ExpectError + dlarfg( 4, X ); // $ExpectError + dlarfg( 4, X, 1 ); // $ExpectError + dlarfg( 4, X, 1, out, 10 ); // $ExpectError +} + +// Attached to main export is an `ndarray` method which returns undefined... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); // $ExpectType void +} + +// The compiler throws an error if the function is provided a first argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( '5', X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( true, X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( false, X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( null, X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( void 0, X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( [], X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( {}, X, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( ( x: number ): number => x, X, 1, 0, out, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a Float64Array... +{ + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, '5', 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, 5, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, true, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, false, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, null, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, void 0, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, [], 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, {}, 1, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, ( x: number ): number => x, 1, 0, out, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, X, '1', 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, true, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, false, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, null, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, void 0, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, [], 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, {}, 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, ( x: number ): number => x, 0, out, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, X, 1, '0', out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, true, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, false, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, null, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, void 0, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, [], out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, {}, out, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, ( x: number ): number => x, out, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fifth argument which is not a Float64Array... +{ + const X = new Float64Array( 3 ); + + dlarfg.ndarray( 4, X, 1, 0, '5', 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, 5, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, true, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, false, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, null, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, void 0, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, [], 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, {}, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, ( x: number ): number => x, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a sixth argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, X, 1, 0, out, '1', 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, true, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, false, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, null, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, void 0, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, [], 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, {}, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, ( x: number ): number => x, 0 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a seventh argument which is not a number... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray( 4, X, 1, 0, out, 1, '0' ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, true ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, false ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, null ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, void 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, [] ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, {} ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided an unsupported number of arguments... +{ + const X = new Float64Array( 3 ); + const out = new Float64Array( 2 ); + + dlarfg.ndarray(); // $ExpectError + dlarfg.ndarray( 4 ); // $ExpectError + dlarfg.ndarray( 4, X ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1 ); // $ExpectError + dlarfg.ndarray( 4, X, 1, 0, out, 1, 0, 10 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index 5ec7343b5c66..012753f08403 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -36,7 +36,6 @@ var base = require( './base.js' ); * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. * -* @private * @param {NonNegativeInteger} N - order of matrix `A` * @param {Float64Array} X - overwritten by the vector `V` on exit * @param {integer} incx - stride length for `X` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index a01c129f87ef..62be8aaded98 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -36,7 +36,6 @@ var base = require( './base.js' ); * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. * -* @private * @param {NonNegativeInteger} N - order of matrix `A` * @param {Float64Array} X - overwritten by the vector `V` on exit * @param {integer} strideX - stride length for `X` From 2ac13b03422c4d13f7b4349c6815ea7a01a74e22 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Fri, 30 May 2025 05:11:08 +0000 Subject: [PATCH 10/16] docs: update docs --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/docs/types/index.d.ts | 12 ++++++------ .../@stdlib/lapack/base/dlarfg/lib/base.js | 4 ++-- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 4 ++-- .../@stdlib/lapack/base/dlarfg/lib/index.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 4 ++-- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts index e899ab506c8c..8f6e19902235 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -31,10 +31,10 @@ interface Routine { * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. - * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. + * - otherwise, `1 <= tau <= 2` * * @param N - order of matrix `A` - * @param X - overwritten by the vector `V` on exit + * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param incx - stride length for `X` * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` * @returns overwrites the array `X` and `out` in place @@ -60,10 +60,10 @@ interface Routine { * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. - * - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. + * - otherwise, `1 <= tau <= 2` * * @param N - order of matrix `A` - * @param X - overwritten by the vector `V` on exit + * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param strideX - stride length for `X` * @param offsetX - starting index of `X` * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` @@ -93,10 +93,10 @@ interface Routine { * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* - otherwise, `1 <= tau <= 2` * * @param N - order of matrix `A` -* @param X - overwritten by the vector `V` on exit +* @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param incx - stride length for `X` * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` * @returns overwrites the array `X` and `out` in place diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index 29b0e2f5eaba..a24f1e2ddc25 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -39,11 +39,11 @@ var dlapy2 = require( './dlapy2.js' ); * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* - otherwise, `1 <= tau <= 2` * * @private * @param {NonNegativeInteger} N - order of matrix `A` -* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index 012753f08403..623c50c3173e 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -34,10 +34,10 @@ var base = require( './base.js' ); * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* - otherwise, `1 <= tau <= 2` * * @param {NonNegativeInteger} N - order of matrix `A` -* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} incx - stride length for `X` * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` * @returns {void} overwrites the array `X` and `out` in place diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js index 17267b82356c..9716971ab385 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js @@ -27,7 +27,7 @@ * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* - otherwise, `1 <= tau <= 2` * * @module @stdlib/lapack/base/dlarfg * diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index 62be8aaded98..e607b6914b5b 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -34,10 +34,10 @@ var base = require( './base.js' ); * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` and `H` is orthogonal, i.e., `H^T * H = I`. +* - otherwise, `1 <= tau <= 2` * * @param {NonNegativeInteger} N - order of matrix `A` -* @param {Float64Array} X - overwritten by the vector `V` on exit +* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` From b9458c198e366cff2a3c6571b4360a8dff5417ba Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Fri, 30 May 2025 06:01:12 +0000 Subject: [PATCH 11/16] docs: add README --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/README.md | 257 ++++++++++++++++++ .../lapack/base/dlarfg/docs/types/index.d.ts | 24 +- .../@stdlib/lapack/base/dlarfg/lib/base.js | 8 +- .../@stdlib/lapack/base/dlarfg/lib/dlapy2.js | 4 +- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 8 +- .../@stdlib/lapack/base/dlarfg/lib/index.js | 6 +- .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 8 +- .../@stdlib/lapack/base/dlarfg/package.json | 2 +- 8 files changed, 287 insertions(+), 30 deletions(-) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/README.md diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md new file mode 100644 index 000000000000..06cfef7e7705 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md @@ -0,0 +1,257 @@ + + +# dlarfg + +> LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. + +
+ +## Usage + +```javascript +var dlarfg = require( '@stdlib/lapack/base/dlarfg' ); +``` + +#### dlarfg( N, X, incx, out ) + +Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +var out = new Float64Array( [ 4.0, 0.0 ] ); + +dlarfg( 4, X, 1, out ); +// X => [ ~0.19, ~0.28, ~0.37 ] +// out => [ ~6.7, ~1.6 ] +``` + +The function has the following parameters: + +- **N**: number of rows/columns of the elementary reflector `H`. +- **X**: overwritten by the vector `V` on exit, expects `N - 1` indexed elements [`Float64Array`][mdn-float64array]. +- **incx**: stride length of `X`. +- **out**: output [`Float64Array`][mdn-float64array], the first element of `out` represents alpha and the second element of `out` represents `tau`. + +Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. + + + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +// Initial arrays... +var X0 = new Float64Array( [ 0.0, 2.0, 3.0, 4.0 ] ); +var out0 = new Float64Array( [ 0.0, 4.0, 0.0 ] ); + +// Create offset views... +var X1 = new Float64Array( X0.buffer, X0.BYTES_PER_ELEMENT*1 ); // start at 2nd element +var out1 = new Float64Array( out0.buffer, out0.BYTES_PER_ELEMENT*1 ); // start at 2nd element + +dlarfg( 4, X1, 1, out1 ); +// X0 => [ 0.0, ~0.19, ~0.28, ~0.37 ] +// out0 => [ 0.0, ~6.7, ~1.6 ] +``` + +#### dlarfg.ndarray( N, X, strideX, offsetX, out, strideOut, offsetOut ) + +Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X` using alternative indexing semantics. + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var X = new Float64Array( [ 2.0, 3.0, 4.0 ] ); +var out = new Float64Array( [ 4.0, 0.0 ] ); + +dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); +// X => [ ~0.19, ~0.28, ~0.37 ] +// out => [ ~6.7, ~1.6 ] +``` + +The function has the following parameters: + +- **N**: number of rows/columns of the elementary reflector `H`. +- **X**: overwritten by the vector `V` on exit, expects `N - 1` indexed elements [`Float64Array`][mdn-float64array]. +- **strideX**: stride length of `X`. +- **offsetX**: starting index of `X`. +- **out**: output [`Float64Array`][mdn-float64array], the first element of `out` represents alpha and the second element of `out` represents `tau`. +- **strideOut**: stride length of `out`. +- **offsetOut**: starting index of `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, + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var X = new Float64Array( [ 0.0, 2.0, 3.0, 4.0 ] ); +var out = new Float64Array( [ 0.0, 4.0, 0.0 ] ); + +dlarfg.ndarray( 4, X, 1, 1, out, 1, 1 ); +// X => [ 0.0, ~0.19, ~0.28, ~0.37 ] +// out => [ 0.0, ~6.7, ~1.6 ] +``` + +
+ + + +
+ +## Notes + +- `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. +- the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +- the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +- if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. +- otherwise, `1 <= tau <= 2` +- `dlarfg()` corresponds to the [LAPACK][lapack] routine [`dlarfg`][lapack-dlarfg]. + +
+ + + +
+ +## Examples + + + +```javascript +var uniform = require( '@stdlib/random/array/discrete-uniform' ); +var Float64Array = require( '@stdlib/array/float64' ); +var dlarfg = require( '@stdlib/lapack/base/dlarfg' ); + +var N = 4; + +var X = uniform( N - 1, -10, 10, { + 'dtype': 'float64' +}); +console.log( 'X: ', X ); + +var alpha = 4.0; + +var out = new Float64Array( [ alpha, 0.0 ] ); + +dlarfg( N, X, 1, out ); + +console.log( 'V: ', X ); +console.log( 'beta: ', out[ 0 ] ); +console.log( 'tau: ', out[ 1 ] ); +``` + +
+ + + + + +* * * + +
+ +## C APIs + + + +
+ +
+ + + + + +
+ +### Usage + +```c +TODO +``` + +#### TODO + +TODO. + +```c +TODO +``` + +TODO + +```c +TODO +``` + +
+ + + + + +
+ +
+ + + + + +
+ +### Examples + +```c +TODO +``` + +
+ + + +
+ + + + + +
+ +
+ + + + + +
+ +[lapack]: https://www.netlib.org/lapack/explore-html/ + +[lapack-dlarfg]: https://netlib.org/lapack/explore-html-3.6.1/d7/da9/dlarfg_8f_aabb59655e820b3551af27781bd716143.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 + +
+ + diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts index 8f6e19902235..6cfa1493d014 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -23,17 +23,17 @@ */ interface Routine { /** - * Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. + * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. - * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. + * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. - * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. + * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * - * @param N - order of matrix `A` + * @param N - number of rows/columns of the elementary reflector `H` * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param incx - stride length for `X` * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` @@ -52,17 +52,17 @@ interface Routine { ( N: number, X: Float64Array, incx: number, out: Float64Array ): void; /** - * Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. + * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. - * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. + * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. - * - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. + * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * - * @param N - order of matrix `A` + * @param N - number of rows/columns of the elementary reflector `H` * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param strideX - stride length for `X` * @param offsetX - starting index of `X` @@ -85,17 +85,17 @@ interface Routine { } /** -* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * -* @param N - order of matrix `A` +* @param N - number of rows/columns of the elementary reflector `H` * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param incx - stride length for `X` * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index a24f1e2ddc25..f6d41e1e7cc9 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -31,18 +31,18 @@ var dlapy2 = require( './dlapy2.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * * @private -* @param {NonNegativeInteger} N - order of matrix `A` +* @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` * @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js index e23eec83643e..f0c14c6e6fcd 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js @@ -33,8 +33,8 @@ var pow = require( '@stdlib/math/base/special/pow' ); * Returns sqrt( x^2 + y^2 ) in a manner which doesn't cause unnecessary overflow. * * @private -* @param {number} x - order of matrix `A` -* @param {number} y - order of matrix `A` +* @param {number} x - number of rows/columns of the elementary reflector `H` +* @param {number} y - number of rows/columns of the elementary reflector `H` * @returns {integer} status code * * @example diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index 623c50c3173e..030bf1933d75 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -26,17 +26,17 @@ var base = require( './base.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * -* @param {NonNegativeInteger} N - order of matrix `A` +* @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` * @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} incx - stride length for `X` * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js index 9716971ab385..eda3ea4c700f 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js @@ -19,14 +19,14 @@ 'use strict'; /** -* LAPACK routine to generate a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * * @module @stdlib/lapack/base/dlarfg diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index e607b6914b5b..b377db7c026b 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -26,17 +26,17 @@ var base = require( './base.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X` using alternative indexing semantics. * * ## Notes * * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `x` is a real `(n-1)`-element vector. +* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `x` are zero, then `tau = 0` and `H` is the identity matrix. +* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * -* @param {NonNegativeInteger} N - order of matrix `A` +* @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` * @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json index f47e91dc0696..37bc3eb46dea 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json @@ -1,7 +1,7 @@ { "name": "@stdlib/lapack/base/dlarfg", "version": "0.0.0", - "description": "LAPACK routine to generate a real elementary reflector `H` of order `n` such that applying `H` to a vector `[alpha; x]` zeros out `x`.", + "description": "LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`.", "license": "Apache-2.0", "author": { "name": "The Stdlib Authors", From 8b4265275ae9dbeabb6ce7c6ffd00a2c7d215285 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Fri, 30 May 2025 07:57:51 +0000 Subject: [PATCH 12/16] docs: update examples --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/README.md | 6 +- .../@stdlib/lapack/base/dlarfg/docs/repl.txt | 96 +++++++++++++++++++ .../lapack/base/dlarfg/docs/types/index.d.ts | 6 +- .../@stdlib/lapack/base/dlarfg/lib/base.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/index.js | 4 +- .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 2 +- 7 files changed, 107 insertions(+), 11 deletions(-) create mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md index 06cfef7e7705..1c8e1627253a 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md @@ -2,7 +2,7 @@ @license Apache-2.0 -Copyright (c) 2024 The Stdlib Authors. +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. @@ -42,7 +42,7 @@ var out = new Float64Array( [ 4.0, 0.0 ] ); dlarfg( 4, X, 1, out ); // X => [ ~0.19, ~0.28, ~0.37 ] -// out => [ ~6.7, ~1.6 ] +// out => [ ~-6.7, ~1.6 ] ``` The function has the following parameters: @@ -84,7 +84,7 @@ var out = new Float64Array( [ 4.0, 0.0 ] ); dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); // X => [ ~0.19, ~0.28, ~0.37 ] -// out => [ ~6.7, ~1.6 ] +// out => [ ~-6.7, ~1.6 ] ``` The function has the following parameters: diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt new file mode 100644 index 000000000000..50dde02f10b5 --- /dev/null +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt @@ -0,0 +1,96 @@ + +{{alias}}( N, X, incx, out ) + Generates a real elementary reflector `H` of order `N` such that applying + `H` to a vector `[alpha; x]` zeros out `X`. + + `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, + where `tau` is a scalar and `v` is a vector. The input vector is + `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element + vector. The result of applying `H` to `[alpha; x]` is `[beta; 0]`, with + `beta` being a scalar and the rest of the vector zeroed. If all elements of + `X` are zero, then `tau = 0` and `H` is the identity matrix. Otherwise, + `1 <= tau <= 2`. + + Indexing is relative to the first index. To introduce an offset, use typed + array views. + + Parameters + ---------- + N: integer + Number of row/columns of the elementary reflector `H`. + + X: Float64Array + Input vector, overwritten by the vector `V` on exit, expects `N - 1` + indexed elements. + + incx: integer + Increment between successive values of `X`. + + out: Float64Array + Array to store `alpha` and `tau`, first indexed element stores `alpha` + and the second indexed element stores `tau`. + + Examples + -------- + > var X = new {{alias:@stdlib/array/float64}}( [ 2.0, 3.0, 4.0 ] ); + > var out = new {{alias:@stdlib/array/float64}}( [ 4.0, 0.0 ] ); + > {{alias}}( 4, X, 1, out ); + > X + [ ~0.19, ~0.28, ~0.37 ] + > out + [ ~-6.7, ~1.6 ] + + +{{alias}}.ndarray( N, X, strideX, offsetX, out, strideOut, offsetOut ) + Generates a real elementary reflector `H` of order `N` such that applying + `H` to a vector `[alpha; x]` zeros out `X`. + + `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, + where `tau` is a scalar and `v` is a vector. The input vector is + `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element + vector. The result of applying `H` to `[alpha; x]` is `[beta; 0]`, with + `beta` being a scalar and the rest of the vector zeroed. If all elements of + `X` are zero, then `tau = 0` and `H` is the identity matrix. Otherwise, + `1 <= tau <= 2`. + + While typed array views mandate a view offset based on the underlying + buffer, the offset parameters support indexing semantics based on starting + indices. + + Parameters + ---------- + N: integer + Number of row/columns of the elementary reflector `H`. + + X: Float64Array + Input vector, overwritten by the vector `V` on exit, expects `N - 1` + indexed elements. + + strideX: integer + Stride length for `X`. + + offsetX: integer + Starting index for `X. + + out: Float64Array + Array to store `alpha` and `tau`, first indexed element stores `alpha` + and the second indexed element stores `tau`. + + strideOut: integer + Stride length for `out`. + + offsetOut: integer + Starting index for `out`. + + Examples + -------- + > var X = new {{alias:@stdlib/array/float64}}( [ 2.0, 3.0, 4.0 ] ); + > var out = new {{alias:@stdlib/array/float64}}( [ 4.0, 0.0 ] ); + > {{alias}}.ndarray( 4, X, 1, 0, out, 1, 0 ); + > X + [ ~0.19, ~0.28, ~0.37 ] + > out + [ ~-6.7, ~1.6 ] + + See Also + -------- diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts index 6cfa1493d014..ad2d25c8e380 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -47,7 +47,7 @@ interface Routine { * * dlarfg( 4, X, 1, out ); * // X => [ ~0.19, ~0.28, ~0.37 ] - * // out => [ ~6.7, ~1.6 ] + * // out => [ ~-6.7, ~1.6 ] */ ( N: number, X: Float64Array, incx: number, out: Float64Array ): void; @@ -79,7 +79,7 @@ interface Routine { * * dlarfg( 4, X, 1, 0, out, 1, 0 ); * // X => [ ~0.19, ~0.28, ~0.37 ] - * // out => [ ~6.7, ~1.6 ] + * // out => [ ~-6.7, ~1.6 ] */ ndarray( N: number, X: Float64Array, strideX: number, offsetX: number, out: Float64Array, strideOut: number, offsetOut: number ): void; } @@ -109,7 +109,7 @@ interface Routine { * * dlarfg( 4, X, 1, out ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] */ declare var dlarfg: Routine; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index f6d41e1e7cc9..22816804fbe9 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -59,7 +59,7 @@ var dlapy2 = require( './dlapy2.js' ); * * dlarfg( 4, X, 1, 0, out, 1, 0 ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] */ function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { var safemin; diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index 030bf1933d75..b3e49191ef9d 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -50,7 +50,7 @@ var base = require( './base.js' ); * * dlarfg( 4, X, 1, out ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] */ function dlarfg( N, X, incx, out ) { base( N, X, incx, 0, out, 1, 0 ); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js index eda3ea4c700f..beca3c2bea5f 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js @@ -40,7 +40,7 @@ * * dlarfg( 4, X, 1, out ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] * * @example * var Float64Array = require( '@stdlib/array/float64' ); @@ -52,7 +52,7 @@ * * dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] */ // MODULES // diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index b377db7c026b..88388dc87403 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -53,7 +53,7 @@ var base = require( './base.js' ); * * dlarfg( 4, X, 1, 0, out, 1, 0 ); * // X => [ ~0.19, ~0.28, ~0.37 ] -* // out => [ ~6.7, ~1.6 ] +* // out => [ ~-6.7, ~1.6 ] */ function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { base( N, X, strideX, offsetX, out, strideOut, offsetOut ); From f7e00903b9ba8f89fdd21c7790c09f3e56f2a369 Mon Sep 17 00:00:00 2001 From: Aayush Khanna <96649223+aayush0325@users.noreply.github.com> Date: Wed, 4 Jun 2025 09:00:14 +0530 Subject: [PATCH 13/16] chore: use package for dlapy2 --- .../@stdlib/lapack/base/dlarfg/lib/base.js | 2 +- .../@stdlib/lapack/base/dlarfg/lib/dlapy2.js | 67 ------------------- 2 files changed, 1 insertion(+), 68 deletions(-) delete mode 100644 lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index 22816804fbe9..cc214e09577d 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -25,7 +25,7 @@ var sign = require( '@stdlib/math/base/special/copysign' ); var dlamch = require( '@stdlib/lapack/base/dlamch' ); var abs = require( '@stdlib/math/base/special/abs' ); var dscal = require( '@stdlib/blas/base/dscal' ).ndarray; -var dlapy2 = require( './dlapy2.js' ); +var dlapy2 = require( '@stdlib/lapack/base/dlapy2' ); // MAIN // diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js deleted file mode 100644 index f0c14c6e6fcd..000000000000 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlapy2.js +++ /dev/null @@ -1,67 +0,0 @@ -/** -* @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 abs = require( '@stdlib/math/base/special/abs' ); -var min = require( '@stdlib/math/base/special/min' ); -var max = require( '@stdlib/math/base/special/max' ); -var sqrt = require( '@stdlib/math/base/special/sqrt' ); -var pow = require( '@stdlib/math/base/special/pow' ); - - -// MAIN // - -/** -* Returns sqrt( x^2 + y^2 ) in a manner which doesn't cause unnecessary overflow. -* -* @private -* @param {number} x - number of rows/columns of the elementary reflector `H` -* @param {number} y - number of rows/columns of the elementary reflector `H` -* @returns {integer} status code -* -* @example -* var out = dlapy2( 3.0, 4.0, ); -* // returns 5 -*/ -function dlapy2( x, y ) { - // TODO - make a separate package for this - var xabs; - var yabs; - var w; - var z; - - xabs = abs( x ); - yabs = abs( y ); - - w = max( xabs, yabs ); - z = min( xabs, yabs ); - - if ( z === 0.0 ) { - return w; - } - - return w * ( sqrt( 1.0 + pow( z / w, 2.0 ) ) ); -} - - -// EXPORTS // - -module.exports = dlapy2; From 0f4398806745d808d58539ed169bdaf990f9d9ff Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 5 Jun 2025 04:48:53 +0000 Subject: [PATCH 14/16] chore: cleanup --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/README.md | 20 +++++++-------- .../@stdlib/lapack/base/dlarfg/docs/repl.txt | 20 +++++++-------- .../lapack/base/dlarfg/docs/types/index.d.ts | 24 +++++++++--------- .../@stdlib/lapack/base/dlarfg/lib/base.js | 25 ++++++++----------- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 10 ++++---- .../@stdlib/lapack/base/dlarfg/lib/index.js | 8 +++--- .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 10 ++++---- .../@stdlib/lapack/base/dlarfg/package.json | 2 +- 8 files changed, 58 insertions(+), 61 deletions(-) diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md index 1c8e1627253a..5d4ead9704fa 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md @@ -20,7 +20,7 @@ limitations under the License. # dlarfg -> LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +> LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`.
@@ -32,7 +32,7 @@ var dlarfg = require( '@stdlib/lapack/base/dlarfg' ); #### dlarfg( N, X, incx, out ) -Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. ```javascript var Float64Array = require( '@stdlib/array/float64' ); @@ -48,9 +48,9 @@ dlarfg( 4, X, 1, out ); The function has the following parameters: - **N**: number of rows/columns of the elementary reflector `H`. -- **X**: overwritten by the vector `V` on exit, expects `N - 1` indexed elements [`Float64Array`][mdn-float64array]. +- **X**: a [`Float64Array`][mdn-float64array] which is overwritten by the vector `V`. Should have `N - 1` indexed elements. - **incx**: stride length of `X`. -- **out**: output [`Float64Array`][mdn-float64array], the first element of `out` represents alpha and the second element of `out` represents `tau`. +- **out**: output [`Float64Array`][mdn-float64array]. The first element of `out` represents alpha and the second element of `out` represents `tau`. Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. @@ -74,7 +74,7 @@ dlarfg( 4, X1, 1, out1 ); #### dlarfg.ndarray( N, X, strideX, offsetX, out, strideOut, offsetOut ) -Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X` using alternative indexing semantics. +Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X` using alternative indexing semantics. ```javascript var Float64Array = require( '@stdlib/array/float64' ); @@ -90,10 +90,10 @@ dlarfg.ndarray( 4, X, 1, 0, out, 1, 0 ); The function has the following parameters: - **N**: number of rows/columns of the elementary reflector `H`. -- **X**: overwritten by the vector `V` on exit, expects `N - 1` indexed elements [`Float64Array`][mdn-float64array]. +- **X**: a [`Float64Array`][mdn-float64array] which is overwritten by the vector `V`. Should have `N - 1` indexed elements. - **strideX**: stride length of `X`. - **offsetX**: starting index of `X`. -- **out**: output [`Float64Array`][mdn-float64array], the first element of `out` represents alpha and the second element of `out` represents `tau`. +- **out**: output [`Float64Array`][mdn-float64array]. The first element of `out` represents alpha and the second element of `out` represents `tau`. - **strideOut**: stride length of `out`. - **offsetOut**: starting index of `out`. @@ -118,9 +118,9 @@ dlarfg.ndarray( 4, X, 1, 1, out, 1, 1 ); ## Notes -- `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -- the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -- the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +- `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +- the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +- the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. - otherwise, `1 <= tau <= 2` - `dlarfg()` corresponds to the [LAPACK][lapack] routine [`dlarfg`][lapack-dlarfg]. diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt index 50dde02f10b5..9b497cfba405 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/repl.txt @@ -1,12 +1,12 @@ {{alias}}( N, X, incx, out ) Generates a real elementary reflector `H` of order `N` such that applying - `H` to a vector `[alpha; x]` zeros out `X`. + `H` to a vector `[alpha; X]` zeros out `X`. - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, - where `tau` is a scalar and `v` is a vector. The input vector is - `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element - vector. The result of applying `H` to `[alpha; x]` is `[beta; 0]`, with + `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, + where `tau` is a scalar and `V` is a vector. The input vector is + `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element + vector. The result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. If all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. Otherwise, `1 <= tau <= 2`. @@ -43,12 +43,12 @@ {{alias}}.ndarray( N, X, strideX, offsetX, out, strideOut, offsetOut ) Generates a real elementary reflector `H` of order `N` such that applying - `H` to a vector `[alpha; x]` zeros out `X`. + `H` to a vector `[alpha; X]` zeros out `X`. - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, - where `tau` is a scalar and `v` is a vector. The input vector is - `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element - vector. The result of applying `H` to `[alpha; x]` is `[beta; 0]`, with + `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, + where `tau` is a scalar and `V` is a vector. The input vector is + `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element + vector. The result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. If all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. Otherwise, `1 <= tau <= 2`. diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts index ad2d25c8e380..644d384803da 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -23,13 +23,13 @@ */ interface Routine { /** - * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. + * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * - * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. - * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. - * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. + * - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. + * - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. + * - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * @@ -52,13 +52,13 @@ interface Routine { ( N: number, X: Float64Array, incx: number, out: Float64Array ): void; /** - * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. + * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * - * - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. - * - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. - * - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. + * - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. + * - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. + * - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * @@ -85,13 +85,13 @@ interface Routine { } /** -* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index cc214e09577d..3e3c005cfc85 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -31,13 +31,13 @@ var dlapy2 = require( '@stdlib/lapack/base/dlapy2' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * @@ -49,7 +49,7 @@ var dlapy2 = require( '@stdlib/lapack/base/dlapy2' ); * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` * @param {integer} strideOut - stride length for `out` * @param {NonNegativeInteger} offsetOut - starting index of `out` -* @returns {void} overwrites the array `X` and `out` in place +* @returns {void} * * @example * var Float64Array = require( '@stdlib/array/float64' ); @@ -72,8 +72,7 @@ function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { var i; if ( N <= 1 ) { - tau = 0.0; // tau = 0.0 - out[ offsetOut + strideOut ] = tau; + out[ offsetOut + strideOut ] = 0.0; return; } @@ -81,11 +80,10 @@ function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { alpha = out[ offsetOut ]; if ( xnorm === 0.0 ) { - tau = 0.0; // tau = 0.0 - out[ strideOut + offsetOut ] = tau; + out[ strideOut + offsetOut ] = 0.0; } else { beta = -1.0 * sign( dlapy2( alpha, xnorm ), alpha ); - safemin = dlamch( 'S' ) / dlamch( 'E' ); + safemin = dlamch( 'safemin' ) / dlamch( 'epsilon' ); knt = 0; if ( abs( beta ) < safemin ) { rsafmin = 1.0 / safemin; @@ -93,19 +91,18 @@ function dlarfg( N, X, strideX, offsetX, out, strideOut, offsetOut ) { knt += 1; dscal( N-1, rsafmin, X, strideX, offsetX ); beta *= rsafmin; - alpha *= rsafmin; // alpha *= rsafmin + alpha *= rsafmin; } xnorm = dnrm2( N - 1, X, strideX, offsetX ); beta = -1.0 * sign( dlapy2( alpha, xnorm ), alpha ); } - tau = ( beta - alpha ) / beta; // tau = (beta - alpha) / beta + tau = ( beta - alpha ) / beta; dscal( N-1, 1.0 / ( alpha - beta ), X, strideX, offsetX ); for ( i = 0; i < knt; i++ ) { beta *= safemin; } - alpha = beta; - out[ offsetOut ] = alpha; + out[ offsetOut ] = beta; out[ strideOut + offsetOut ] = tau; } } diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index b3e49191ef9d..a3a8cf6bd46d 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -26,13 +26,13 @@ var base = require( './base.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * @@ -40,7 +40,7 @@ var base = require( './base.js' ); * @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements * @param {integer} incx - stride length for `X` * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` -* @returns {void} overwrites the array `X` and `out` in place +* @returns {void} * * @example * var Float64Array = require( '@stdlib/array/float64' ); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js index beca3c2bea5f..fbcb7c94e991 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/index.js @@ -19,13 +19,13 @@ 'use strict'; /** -* LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`. +* LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index 88388dc87403..fb87fc5123fc 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -26,13 +26,13 @@ var base = require( './base.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X` using alternative indexing semantics. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X` using alternative indexing semantics. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; v] * [1, v^T]`, where `tau` is a scalar and `v` is a vector. -* - the input vector is `[alpha; x]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; x]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. +* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. +* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. +* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. * - otherwise, `1 <= tau <= 2` * @@ -43,7 +43,7 @@ var base = require( './base.js' ); * @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` * @param {integer} strideOut - stride length for `out` * @param {NonNegativeInteger} offsetOut - starting index of `out` -* @returns {void} overwrites the array `X` and `out` in place +* @returns {void} * * @example * var Float64Array = require( '@stdlib/array/float64' ); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json index 37bc3eb46dea..aa3aa3023976 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/package.json @@ -1,7 +1,7 @@ { "name": "@stdlib/lapack/base/dlarfg", "version": "0.0.0", - "description": "LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; x]` zeros out `X`.", + "description": "LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`.", "license": "Apache-2.0", "author": { "name": "The Stdlib Authors", From 1cc7d3852b083c1884d072fd6e0e577d1ed1045a Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 5 Jun 2025 06:02:08 +0000 Subject: [PATCH 15/16] docs: add tex equations --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/README.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md index 5d4ead9704fa..1fc8f1ac9d82 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md @@ -22,6 +22,56 @@ limitations under the License. > LAPACK routine to generate a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. +
+ +The `dlarfg` routine generates a **real elementary reflector** (also known as a Householder reflector) of order `N`, which can be used to zero out selected components of a vector. Specifically, it constructs a reflector matrix `H` such that: + + + + +```math +H \cdot \begin{bmatrix}\alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I +``` + + + + +Here: + +- `α` is a scalar. +- `X` is a real vector of length `N-1`. +- `β` is a scalar value. +- `H` is an orthogonal matrix known as a Householder reflector. + +The reflector `H` is constructed in the form: + + + +```math +H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} +``` + + + +Where: + +- `τ` (`tau`) is a real scalar. +- `V` is a real vector of length `N-1` that defines the Householder vector. +- The vector `[1; V]` is the Householder direction. + +The values of `τ` and `V` are chosen so that applying `H` to the vector `[α; x]` results in a new vector `[β; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is **symmetric and orthogonal**, satisfying `H^T = H` and `H^T H = I`. + +### Special Cases + +- If all elements of `x` are zero, then `τ = 0` and `H = I`, the identity matrix. +- Otherwise, `τ` satisfies `1 ≤ τ ≤ 2`, ensuring numerical stability in transformations. + +This elementary reflector is commonly used in algorithms for QR factorization and other orthogonal transformations. + +
+ + +
## Usage From 674d5551a1973dc845bd44499f438d435bd82d74 Mon Sep 17 00:00:00 2001 From: Aayush Khanna Date: Thu, 5 Jun 2025 07:19:01 +0000 Subject: [PATCH 16/16] docs: update jsdoc --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/lapack/base/dlarfg/README.md | 5 - .../lapack/base/dlarfg/docs/types/index.d.ts | 134 ++++++++++++++---- .../@stdlib/lapack/base/dlarfg/lib/base.js | 43 +++++- .../@stdlib/lapack/base/dlarfg/lib/dlarfg.js | 43 +++++- .../@stdlib/lapack/base/dlarfg/lib/ndarray.js | 46 ++++-- 5 files changed, 219 insertions(+), 52 deletions(-) diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md index 1fc8f1ac9d82..4542e3ddf5ff 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/README.md @@ -168,11 +168,6 @@ dlarfg.ndarray( 4, X, 1, 1, out, 1, 1 ); ## Notes -- `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. -- the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -- the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -- if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. -- otherwise, `1 <= tau <= 2` - `dlarfg()` corresponds to the [LAPACK][lapack] routine [`dlarfg`][lapack-dlarfg].
diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts index 644d384803da..be15eb9ccbf3 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/docs/types/index.d.ts @@ -25,19 +25,47 @@ interface Routine { /** * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * + * `H` is a Householder matrix with the form: + * + * ```tex + * H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I + * ``` + * + * where: + * + * - `tau` is a scalar + * - `X` is a vector of length `N-1` + * - `beta` is a scalar value + * - `H` is an orthogonal matrix known as a Householder reflector. + * + * The reflector `H` is constructed in the form: + * + * ```tex + * H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} + * ``` + * + * where: + * + * - `tau` is a real scalar + * - `V` is a real vector of length `N-1` that defines the Householder vector + * - The vector `[1; V]` is the Householder direction\ + * + * The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` + * + * ## Special cases + * + * - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. + * - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. + * * ## Notes * - * - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. - * - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. - * - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. - * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. - * - otherwise, `1 <= tau <= 2` + * - `X` should have `N-1` indexed elements + * - The output array contains the following two elements: `alpha` and `tau` * * @param N - number of rows/columns of the elementary reflector `H` - * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements + * @param X - input vector * @param incx - stride length for `X` - * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` - * @returns overwrites the array `X` and `out` in place + * @param out - output array * * @example * var Float64Array = require( '@stdlib/array/float64' ); @@ -52,24 +80,52 @@ interface Routine { ( N: number, X: Float64Array, incx: number, out: Float64Array ): void; /** - * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. + * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X` using alternative indexing semantics. + * + * `H` is a Householder matrix with the form: + * + * ```tex + * H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I + * ``` + * + * where: + * + * - `tau` is a scalar + * - `X` is a vector of length `N-1` + * - `beta` is a scalar value + * - `H` is an orthogonal matrix known as a Householder reflector. + * + * The reflector `H` is constructed in the form: + * + * ```tex + * H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} + * ``` + * + * where: + * + * - `tau` is a real scalar + * - `V` is a real vector of length `N-1` that defines the Householder vector + * - The vector `[1; V]` is the Householder direction\ + * + * The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` + * + * ## Special cases + * + * - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. + * - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. * * ## Notes * - * - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. - * - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. - * - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. - * - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. - * - otherwise, `1 <= tau <= 2` + * - `X` should have `N-1` indexed elements + * - The output array contains the following two elements: `alpha` and `tau` * * @param N - number of rows/columns of the elementary reflector `H` - * @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements + * @param X - input vector * @param strideX - stride length for `X` * @param offsetX - starting index of `X` - * @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` + * @param out - output array * @param strideOut - stride length for `out` * @param offsetOut - starting index of `out` - * @returns overwrites the array `X` and `out` in place * * @example * var Float64Array = require( '@stdlib/array/float64' ); @@ -87,19 +143,47 @@ interface Routine { /** * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * +* `H` is a Householder matrix with the form: +* +* ```tex +* H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I +* ``` +* +* where: +* +* - `tau` is a scalar +* - `X` is a vector of length `N-1` +* - `beta` is a scalar value +* - `H` is an orthogonal matrix known as a Householder reflector. +* +* The reflector `H` is constructed in the form: +* +* ```tex +* H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} +* ``` +* +* where: +* +* - `tau` is a real scalar +* - `V` is a real vector of length `N-1` that defines the Householder vector +* - The vector `[1; V]` is the Householder direction\ +* +* The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` +* +* ## Special cases +* +* - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. +* - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. +* * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. -* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` +* - `X` should have `N-1` indexed elements +* - The output array contains the following two elements: `alpha` and `tau` * * @param N - number of rows/columns of the elementary reflector `H` -* @param X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements +* @param X - input vector * @param incx - stride length for `X` -* @param out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` -* @returns overwrites the array `X` and `out` in place +* @param out - output array * * @example * var Float64Array = require( '@stdlib/array/float64' ); diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js index 3e3c005cfc85..da2c67ed7284 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/base.js @@ -33,20 +33,49 @@ var dlapy2 = require( '@stdlib/lapack/base/dlapy2' ); /** * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * +* `H` is a Householder matrix with the form: +* +* ```tex +* H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I +* ``` +* +* where: +* +* - `tau` is a scalar +* - `X` is a vector of length `N-1` +* - `beta` is a scalar value +* - `H` is an orthogonal matrix known as a Householder reflector. +* +* The reflector `H` is constructed in the form: +* +* ```tex +* H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} +* ``` +* +* where: +* +* - `tau` is a real scalar +* - `V` is a real vector of length `N-1` that defines the Householder vector +* - The vector `[1; V]` is the Householder direction\ +* +* The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` +* +* ## Special cases +* +* - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. +* - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. +* * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. -* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` +* - `X` should have `N-1` indexed elements +* - The output array contains the following two elements: `alpha` and `tau` * * @private * @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` -* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements +* @param {Float64Array} X - input vector * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` -* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @param {Float64Array} out - output array * @param {integer} strideOut - stride length for `out` * @param {NonNegativeInteger} offsetOut - starting index of `out` * @returns {void} diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js index a3a8cf6bd46d..de6f7a95aaa0 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/dlarfg.js @@ -28,18 +28,47 @@ var base = require( './base.js' ); /** * Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X`. * +* `H` is a Householder matrix with the form: +* +* ```tex +* H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I +* ``` +* +* where: +* +* - `tau` is a scalar +* - `X` is a vector of length `N-1` +* - `beta` is a scalar value +* - `H` is an orthogonal matrix known as a Householder reflector. +* +* The reflector `H` is constructed in the form: +* +* ```tex +* H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} +* ``` +* +* where: +* +* - `tau` is a real scalar +* - `V` is a real vector of length `N-1` that defines the Householder vector +* - The vector `[1; V]` is the Householder direction\ +* +* The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` +* +* ## Special cases +* +* - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. +* - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. +* * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. -* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` +* - `X` should have `N-1` indexed elements +* - The output array contains the following two elements: `alpha` and `tau` * * @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` -* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements +* @param {Float64Array} X - input vector * @param {integer} incx - stride length for `X` -* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @param {Float64Array} out - output array * @returns {void} * * @example diff --git a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js index fb87fc5123fc..dd77b892074f 100644 --- a/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js +++ b/lib/node_modules/@stdlib/lapack/base/dlarfg/lib/ndarray.js @@ -26,21 +26,51 @@ var base = require( './base.js' ); // MAIN // /** -* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X` using alternative indexing semantics. +* Generates a real elementary reflector `H` of order `N` such that applying `H` to a vector `[alpha; X]` zeros out `X` usinig alternative indexing semantics. +* +* `H` is a Householder matrix with the form: +* +* ```tex +* H \cdot \begin{bmatrix} \alpha \\ x \end{bmatrix} = \begin{bmatrix} \beta \\ 0 \end{bmatrix}, \quad \text{and} \quad H^T H = I +* ``` +* +* where: +* +* - `tau` is a scalar +* - `X` is a vector of length `N-1` +* - `beta` is a scalar value +* - `H` is an orthogonal matrix known as a Householder reflector. +* +* The reflector `H` is constructed in the form: +* +* ```tex +* H = I - \tau \begin{bmatrix}1 \\ v \end{bmatrix} \begin{bmatrix}1 & v^T \end{bmatrix} +* ``` +* +* where: +* +* - `tau` is a real scalar +* - `V` is a real vector of length `N-1` that defines the Householder vector +* - The vector `[1; V]` is the Householder direction\ +* +* The values of `tau` and `V` are chosen so that applying `H` to the vector `[alpha; X]` results in a new vector `[beta; 0]`, i.e., only the first component remains nonzero. The reflector matrix `H` is symmetric and orthogonal, satisfying `H^T = H` and `H^T H = I` +* +* ## Special cases +* +* - If all elements of `X` are zero, then `tau = 0` and `H = I`, the identity matrix. +* - Otherwise, `tau` satisfies `1 ≤ tau ≤ 2`, ensuring numerical stability in transformations. * * ## Notes * -* - `H` is a Householder matrix with the form `H = I - tau * [1; V] * [1, V^T]`, where `tau` is a scalar and `V` is a vector. -* - the input vector is `[alpha; X]`, where `alpha` is a scalar and `X` is a real `(n-1)`-element vector. -* - the result of applying `H` to `[alpha; X]` is `[beta; 0]`, with `beta` being a scalar and the rest of the vector zeroed. -* - if all elements of `X` are zero, then `tau = 0` and `H` is the identity matrix. -* - otherwise, `1 <= tau <= 2` +* - `X` should have `N-1` indexed elements +* - The output array contains the following two elements: `alpha` and `tau` + * * @param {NonNegativeInteger} N - number of rows/columns of the elementary reflector `H` -* @param {Float64Array} X - overwritten by the vector `V` on exit, expects `N - 1` indexed elements +* @param {Float64Array} X - input vector * @param {integer} strideX - stride length for `X` * @param {NonNegativeInteger} offsetX - starting index of `X` -* @param {Float64Array} out - array to store `alpha` and `tau`, first indexed element stores `alpha` and the second indexed element stores `tau` +* @param {Float64Array} out - output array * @param {integer} strideOut - stride length for `out` * @param {NonNegativeInteger} offsetOut - starting index of `out` * @returns {void}