feat: add lapack/base/dgttrf

lib/node_modules/@stdlib/lapack/base/dgttrf/benchmark/benchmark.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 bench = require( '@stdlib/bench' );
+var pkg = require( './../package.json' ).name;
+var dgttrf = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var out;
+	var du;
+	var dl;
+	var d;
+	var n;
+	var i;
+
+	n = 1000;
+
+	dl = [];
+	d = [];
+	du = [];
+
+	// Fill diagonals with some values:
+	for ( i = 0; i < n - 1; i++ ) {
+		dl.push( 2.0 );
+		du.push( 1.0 );
+	}
+	for ( i = 0; i < n; i++ ) {
+		d.push( 4.0 );
+	}
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		// Use fresh copies to avoid in-place modification issues:
+		out = dgttrf( dl.slice(), d.slice(), du.slice() );
+		if ( typeof out !== 'object' || out === null ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( typeof out !== 'object' || out === null ) {
+		b.fail( 'should return an object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+} );

lib/node_modules/@stdlib/lapack/base/dgttrf/docs/repl.txt

@@ -0,0 +1,36 @@
+{{alias}}( dl, d, du )
+    Computes the LU factorization of a real tridiagonal matrix using
+    partial pivoting.
+
+    Parameters
+    ----------
+    dl: Array
+        Sub-diagonal (length n-1).
+    d: Array
+        Main diagonal (length n).
+    du: Array
+        Super-diagonal (length n-1).
+
+    Returns
+    -------
+    out: Object
+        Factorization result with fields:
+        - dl: Array, modified sub-diagonal (L multipliers).
+        - d: Array, modified main diagonal (U diagonal).
+        - du: Array, modified super-diagonal (U first super-diagonal).
+        - du2: Array, second super-diagonal (used for pivoting).
+        - ipiv: Array, pivot indices.
+        - info: Integer, 0 if successful, or the (1-based) index of
+          the first zero or NaN pivot.
+
+    Examples
+    --------
+    > var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
+    > var dl = [2.0, 3.0];
+    > var d = [4.0, 5.0, 6.0];
+    > var du = [1.0, 2.0];
+    > var out = dgttrf(dl, d, du);
+    > out;
+
+    See Also
+    --------

lib/node_modules/@stdlib/lapack/base/dgttrf/docs/types/index.d.ts

@@ -0,0 +1,56 @@
+/*
+* @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.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* LU factorization result object.
+*/
+interface DgttrfResult {
+	dl: Array<number> | Float64Array;
+	d: Array<number> | Float64Array;
+	du: Array<number> | Float64Array;
+	du2: Array<number> | Float64Array;
+	ipiv: Array<number> | Int32Array;
+	info: number;
+}
+
+/**
+* Performs LU factorization of a real tridiagonal matrix A of order n.
+*
+* @param dl - sub-diagonal array of length n-1 (will be overwritten with multipliers)
+* @param d - main diagonal array of length n (will be overwritten with U diagonal)
+* @param du - super-diagonal array of length n-1 (will be overwritten with U first super-diagonal)
+* @returns factorization result
+*
+* @example
+* var dl = [2.0, 3.0];
+* var d = [4.0, 5.0, 6.0];
+* var du = [1.0, 2.0];
+* var out = dgttrf(dl, d, du);
+* // returns { dl: [...], d: [...], du: [...], du2: [...], ipiv: [...], info: 0 }
+*/
+declare function dgttrf(
+	dl: Array<number> | Float64Array,
+	d: Array<number> | Float64Array,
+	du: Array<number> | Float64Array
+): DgttrfResult;
+
+// EXPORTS //
+
+export = dgttrf;

lib/node_modules/@stdlib/lapack/base/dgttrf/docs/types/test.ts

@@ -0,0 +1,52 @@
+/*
+* @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.
+*/
+
+import dgttrf = require('./index');
+
+// TESTS //
+
+// The function returns a DgttrfResult object...
+{
+	const dl = [2.0, 3.0];
+	const d = [4.0, 5.0, 6.0];
+	const du = [1.0, 2.0];
+	const out = dgttrf(dl, d, du);
+	// $ExpectType { dl: number[] | Float64Array; d: number[] | Float64Array; du: number[] | Float64Array; du2: number[] | Float64Array; ipiv: number[] | Int32Array; info: number; }
+}
+
+// The compiler throws an error if the function is provided arguments of invalid types...
+{
+	// $ExpectError
+	dgttrf(1, [4.0, 5.0, 6.0], [1.0, 2.0]);
+	// $ExpectError
+	dgttrf([2.0, 3.0], 'foo', [1.0, 2.0]);
+	// $ExpectError
+	dgttrf([2.0, 3.0], [4.0, 5.0, 6.0], {});
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+	// $ExpectError
+	dgttrf();
+	// $ExpectError
+	dgttrf([2.0, 3.0]);
+	// $ExpectError
+	dgttrf([2.0, 3.0], [4.0, 5.0, 6.0]);
+	// $ExpectError
+	dgttrf([2.0, 3.0], [4.0, 5.0, 6.0], [1.0, 2.0], [0.0]);
+}

lib/node_modules/@stdlib/lapack/base/dgttrf/examples/index.js

@@ -0,0 +1,28 @@
+/**
+* @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';
+
+var dgttrf = require( './../lib' );
+
+var dl = [2.0, 3.0];
+var d = [4.0, 5.0, 6.0];
+var du = [1.0, 2.0];
+
+var out = dgttrf( dl, d, du );
+console.log( out );

lib/node_modules/@stdlib/lapack/base/dgttrf/lib/index.js

@@ -0,0 +1,42 @@
+/**
+* @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';
+
+/**
+* LU factorization of a real tridiagonal matrix (DGTTRF, LAPACK).
+*
+* @module @stdlib/lapack/base/dgttrf
+*
+* @example
+* var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
+* var dl = [2.0, 3.0];
+* var d = [4.0, 5.0, 6.0];
+* var du = [1.0, 2.0];
+* var out = dgttrf( dl, d, du );
+* // returns { dl: [...], d: [...], du: [...], du2: [...], ipiv: [...], info: 0 }
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;