feat: add examples and benchmarks

--- 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 ---
stdlib-js · aayush0325 · Jun 21, 2025 · Jun 21, 2025 · Jun 22, 2025 · Jun 22, 2025
commit dba2eeff5d3d3c20a10040d003becda7115eaa4d
diff --git a/lib/node_modules/@stdlib/lapack/base/dlacn2/benchmark/benchmark.js b/lib/node_modules/@stdlib/lapack/base/dlacn2/benchmark/benchmark.js
@@ -0,0 +1,116 @@
+/**
+* @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 discreteUniform = require( '@stdlib/random/array/discrete-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 dlacn2 = require( './../lib/dlacn2.js' );
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} N - number of elements along each dimension
+* @returns {Function} benchmark function
+*/
+function createBenchmark( N ) {
+	var intOpts;
+	var ISAVE;
+	var KASE;
+	var opts;
+	var ISGN;
+	var EST;
+	var X;
+	var V;
+
+	opts = {
+		'dtype': 'float64'
+	};
+	intOpts = {
+		'dtype': 'int32'
+	};
+
+	X = uniform( N, 0.0, 100.0, opts );
+	V = uniform( N, 0.0, 100.0, opts );
+	ISAVE = discreteUniform( 3, 0, N, intOpts );
+	KASE = discreteUniform( 1, 0, 2, intOpts );
+	EST = uniform( 1, 0.0, 1000.0, opts );
+	ISGN = discreteUniform( N, 1, 1, intOpts );
+	return benchmark;
+
+	/**
+	* Benchmark function.
+	*
+	* @private
+	* @param {Benchmark} b - benchmark instance
+	*/
+	function benchmark( b ) {
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			dlacn2( N, V, X, ISGN, EST, KASE, ISAVE );
+			if ( isnan( EST[ 0 ] ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( EST[ 0 ] ) ) {
+			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+':order=column-major,size='+(N*N), f );
+	}
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/lapack/base/dlacn2/benchmark/benchmark.ndarray.js b/lib/node_modules/@stdlib/lapack/base/dlacn2/benchmark/benchmark.ndarray.js
@@ -0,0 +1,116 @@
+/**
+* @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 discreteUniform = require( '@stdlib/random/array/discrete-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 dlacn2 = 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 intOpts;
+	var ISAVE;
+	var KASE;
+	var opts;
+	var ISGN;
+	var EST;
+	var X;
+	var V;
+
+	opts = {
+		'dtype': 'float64'
+	};
+	intOpts = {
+		'dtype': 'int32'
+	};
+
+	X = uniform( N, 0.0, 100.0, opts );
+	V = uniform( N, 0.0, 100.0, opts );
+	ISAVE = discreteUniform( 3, 0, N, intOpts );
+	KASE = discreteUniform( 1, 0, 2, intOpts );
+	EST = uniform( 1, 0.0, 1000.0, opts );
+	ISGN = discreteUniform( N, 1, 1, intOpts );
+	return benchmark;
+
+	/**
+	* Benchmark function.
+	*
+	* @private
+	* @param {Benchmark} b - benchmark instance
+	*/
+	function benchmark( b ) {
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			dlacn2( N, V, 1, 0, X, 1, 0, ISGN, 1, 0, EST, 0, KASE, 0, ISAVE, 1, 0 ); // eslint-disable-line max-len
+			if ( isnan( EST[ 0 ] ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( EST[ 0 ] ) ) {
+			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+':order=column-major,size='+(N*N), f );
+	}
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/lapack/base/dlacn2/examples/index.js b/lib/node_modules/@stdlib/lapack/base/dlacn2/examples/index.js
@@ -0,0 +1,71 @@
+/**
+* @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';
+
+/* eslint-disable array-element-newline */
+
+var Float64Array = require( '@stdlib/array/float64' );
+var Int32Array = require( '@stdlib/array/int32' );
+var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var dgemv = require( '@stdlib/blas/base/dgemv' );
+var dcopy = require( '@stdlib/blas/base/dcopy' );
+var dlacn2 = require( './../lib' );
+
+// Specify matrix meta data:
+var shape = [ 4, 4 ];
+var strides = [ 4, 1 ];
+var offset = 0;
+var order = 'row-major';
+
+// Create a matrix stored in linear memory:
+var A = new Float64Array([
+	1.0, -2.0, 0.0, 0.0,
+	3.0, 4.0, -5.0, 0.0,
+	0.0, 6.0, 7.0, -8.0,
+	0.0, 0.0, 9.0, 10.0
+]);
+
+console.log( ndarray2array( A, shape, strides, offset, order ) );
+
+var KASE = new Int32Array( 1 );
+var EST = new Float64Array( 1 );
+var ISGN = new Int32Array( 4 );
+var ISAVE = new Int32Array( 3 );
+var X = new Float64Array( 4 );
+var V = new Float64Array( 4 );
+
+var work = new Float64Array( 4 );
+    
+while ( true ) {
+	dlacn2( 4, V, X, ISGN, EST, KASE, ISAVE );
+
+	if ( KASE[ 0 ] === 0 ) {
+		break;
+	}
+	else if ( KASE[ 0 ] === 1 ) {
+		dgemv( 'row-major', 'no-transpose', shape[ 0 ], shape[ 1 ], 1.0, A, strides[ 0 ], X, 1, 0, work, 1 );
+		dcopy( shape[ 0 ], work, 1, X, 1 );
+	} else if ( KASE[ 0 ] === 2 ) {
+		dgemv( 'row-major', 'transpose', shape[ 0 ], shape[ 1 ], 1.0, A, strides[ 0 ], X, 1, 0, work, 1 );
+		dcopy( shape[ 0 ], work, 1, X, 1 );
+	}
+}
+
+console.log( 'estimated norm: ', EST[ 0 ] );
+console.log( 'V: ', V );
diff --git a/lib/node_modules/@stdlib/lapack/base/dlacn2/package.json b/lib/node_modules/@stdlib/lapack/base/dlacn2/package.json
@@ -0,0 +1,69 @@
+{
+  "name": "@stdlib/lapack/base/dlacn2",
+  "version": "0.0.0",
+  "description": "LAPACK routine to estimate the one-norm of a square matrix `A`, using reverse communication for evaluating matrix-vector products.",
+  "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",
+    "dlacn2",
+    "norm",
+    "linear",
+    "algebra",
+    "subroutines",
+    "array",
+    "ndarray",
+    "matrix",
+    "float64",
+    "double",
+    "float64array"
+  ]
+}