feat: add lapack/base/dlagts

lib/node_modules/@stdlib/lapack/base/dlagts/README.md

@@ -0,0 +1,323 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2026 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# dlagts
+
+> Solve a system of equations with a tridiagonal matrix `T` following a precomputed factorization.
+
+<section class="intro">
+
+```math
+(T - \lambda I) x = y \quad \textrm{or} \quad (T - \lambda I)^T x = y,
+```
+
+where `T` is an `N` by `N` tridiagonal matrix, following the factorization of `T - \lambda I` as
+
+```math
+T - \lambda I = P L U,
+```
+
+computed beforehand. The choice of equation to be solved is controlled by the `job` argument, and in each case there is an option to perturb zero or very small diagonal elements of `U`, this option being intended for use in applications such as inverse iteration.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var dlagts = require( '@stdlib/lapack/base/dlagts' );
+```
+
+#### dlagts( job, N, A, B, C, D, IN, Y, TOL )
+
+Solves a system of equations with a tridiagonal matrix `T` following a precomputed factorization of `T - lambda*I`.
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var Int32Array = require( '@stdlib/array/int32' );
+
+// Factorization of the symmetric matrix `T`:
+var A = new Float64Array( [ 4.0, 3.75, 3.7333333333333334 ] );
+var B = new Float64Array( [ 1.0, 1.0 ] );
+var C = new Float64Array( [ 0.25, 0.26666666666666666 ] );
+var D = new Float64Array( [ 0.0 ] );
+var IN = new Int32Array( [ 0, 0, 0 ] );
+
+// Right-hand side vector:
+var Y = new Float64Array( [ 1.0, 2.0, 3.0 ] );
+
+// Tolerance (only referenced when `job` is negative):
+var TOL = new Float64Array( [ 0.0 ] );
+
+dlagts( 1, 3, A, B, C, D, IN, Y, TOL );
+// Y => <Float64Array>[ ~0.179, ~0.286, ~0.679 ]
+```
+
+The function has the following parameters:
+
+-   **job**: specifies the system to solve. If `job` is `1`, solve `(T - lambda*I)*x = y`. If `job` is `2`, solve `(T - lambda*I)^T*x = y`. When `job` is positive, very small diagonal elements of `U` are not perturbed. When `job` is negative (`-1` or `-2`), very small diagonal elements of `U` are perturbed if overflow would otherwise occur.
+-   **N**: order of the matrix `T`.
+-   **A**: diagonal elements of `U`, as a [`Float64Array`][mdn-float64array]. Should have `N` indexed elements.
+-   **B**: first super-diagonal elements of `U`, as a [`Float64Array`][mdn-float64array]. Should have `N-1` indexed elements.
+-   **C**: sub-diagonal elements of `L`, as a [`Float64Array`][mdn-float64array]. Should have `N-1` indexed elements.
+-   **D**: second super-diagonal elements of `U`, as a [`Float64Array`][mdn-float64array]. Should have `N-2` indexed elements.
+-   **IN**: details of the matrix `P`, as an [`Int32Array`][mdn-int32array]. Should have `N` indexed elements.
+-   **Y**: right-hand side vector as a [`Float64Array`][mdn-float64array]. Should have `N` indexed elements. On exit, `Y` is overwritten by the solution vector `x`.
+-   **TOL**: tolerance as a [`Float64Array`][mdn-float64array]. When `job` is negative and `TOL` is non-positive on entry, `TOL` is reset to `eps*max(abs(u(i,j)))` (where `eps` is the relative machine precision) and, on exit, `TOL` is overwritten by the tolerance actually used. When `job` is positive, `TOL` is not referenced.
+
+Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
+
+<!-- eslint-disable stdlib/capitalized-comments -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var Int32Array = require( '@stdlib/array/int32' );
+
+// Initial arrays...
+var A0 = new Float64Array( [ 0.0, 4.0, 3.75, 3.7333333333333334 ] );
+var B0 = new Float64Array( [ 0.0, 1.0, 1.0 ] );
+var C0 = new Float64Array( [ 0.0, 0.25, 0.26666666666666666 ] );
+var D0 = new Float64Array( [ 0.0, 0.0 ] );
+var IN0 = new Int32Array( [ 0, 0, 0, 0 ] );
+var Y0 = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
+
+// Create offset views...
+var A = new Float64Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var B = new Float64Array( B0.buffer, B0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var C = new Float64Array( C0.buffer, C0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var D = new Float64Array( D0.buffer, D0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var IN = new Int32Array( IN0.buffer, IN0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var Y = new Float64Array( Y0.buffer, Y0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+
+var TOL = new Float64Array( [ 0.0 ] );
+
+dlagts( 1, 3, A, B, C, D, IN, Y, TOL );
+// Y0 => <Float64Array>[ 0.0, ~0.179, ~0.286, ~0.679 ]
+```
+
+<!-- lint disable maximum-heading-length -->
+
+#### dlagts.ndarray( job, N, A, sa, oa, B, sb, ob, C, sc, oc, D, sd, od, IN, si, oi, Y, sy, oy, TOL, ot )
+
+Solves a system of equations with a tridiagonal matrix `T` following a precomputed factorization of `T - lambda*I` and using alternative indexing semantics.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var Int32Array = require( '@stdlib/array/int32' );
+
+var A = new Float64Array( [ 4.0, 3.75, 3.7333333333333334 ] );
+var B = new Float64Array( [ 1.0, 1.0 ] );
+var C = new Float64Array( [ 0.25, 0.26666666666666666 ] );
+var D = new Float64Array( [ 0.0 ] );
+var IN = new Int32Array( [ 0, 0, 0 ] );
+var Y = new Float64Array( [ 1.0, 2.0, 3.0 ] );
+var TOL = new Float64Array( [ 0.0 ] );
+
+dlagts.ndarray( 1, 3, A, 1, 0, B, 1, 0, C, 1, 0, D, 1, 0, IN, 1, 0, Y, 1, 0, TOL, 0 );
+// Y => <Float64Array>[ ~0.179, ~0.286, ~0.679 ]
+```
+
+The function has the following additional parameters:
+
+-   **sa**: stride length for `A`.
+-   **oa**: starting index for `A`.
+-   **sb**: stride length for `B`.
+-   **ob**: starting index for `B`.
+-   **sc**: stride length for `C`.
+-   **oc**: starting index for `C`.
+-   **sd**: stride length for `D`.
+-   **od**: starting index for `D`.
+-   **si**: stride length for `IN`.
+-   **oi**: starting index for `IN`.
+-   **sy**: stride length for `Y`.
+-   **oy**: starting index for `Y`.
+-   **ot**: index for `TOL`.
+
+While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example,
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var Int32Array = require( '@stdlib/array/int32' );
+
+var A = new Float64Array( [ 0.0, 4.0, 3.75, 3.7333333333333334 ] );
+var B = new Float64Array( [ 0.0, 1.0, 1.0 ] );
+var C = new Float64Array( [ 0.0, 0.25, 0.26666666666666666 ] );
+var D = new Float64Array( [ 0.0, 0.0 ] );
+var IN = new Int32Array( [ 0, 0, 0, 0 ] );
+var Y = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
+var TOL = new Float64Array( [ 0.0 ] );
+
+dlagts.ndarray( 1, 3, A, 1, 1, B, 1, 1, C, 1, 1, D, 1, 1, IN, 1, 1, Y, 1, 1, TOL, 0 );
+// Y => <Float64Array>[ 0.0, ~0.179, ~0.286, ~0.679 ]
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   Both functions mutate the input array `Y`. When `job` is negative and `TOL` is non-positive on entry, both functions also mutate the input array `TOL`. In all other cases, `TOL` is left unchanged.
+
+-   Both functions return a status code indicating success or failure. The status code indicates the following conditions:
+
+    -   `0`: the routine completed successfully.
+    -   `>0`: overflow would occur when computing the `k`-th element of the solution vector `x`, where `k` equals the status code value. This can only occur when `job` is positive and either means that a diagonal element of `U` is very small, or that the elements of the right-hand side vector `y` are very large.
+
+-   `dlagts()` corresponds to the [LAPACK][lapack] routine [`dlagts`][lapack-dlagts].
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error", max-len: "off" -->
+
+```javascript
+var Int32Array = require( '@stdlib/array/int32' );
+var Float64Array = require( '@stdlib/array/float64' );
+var dlagts = require( '@stdlib/lapack/base/dlagts' );
+
+var A = new Float64Array( [ 4.0, 3.75, 3.7333333333333334, 3.732142857142857, 3.7320574162679425 ] );
+var B = new Float64Array( [ 1.0, 1.0, 1.0, 1.0 ] );
+var C = new Float64Array( [ 0.25, 0.26666666666666666, 0.26785714285714285, 0.2679425837320574 ] );
+var D = new Float64Array( [ 0.0, 0.0, 0.0 ] );
+var IN = new Int32Array( [ 0, 0, 0, 0, 0 ] );
+
+var Y = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+var TOL = new Float64Array( [ 0.0 ] );
+
+var info = dlagts( 1, 5, A, B, C, D, IN, Y, TOL );
+
+console.log( Y );
+console.log( info );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- C interface documentation. -->
+
+* * *
+
+<section class="c">
+
+## C APIs
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- C usage documentation. -->
+
+<section class="usage">
+
+### Usage
+
+```c
+TODO
+```
+
+#### TODO
+
+TODO.
+
+```c
+TODO
+```
+
+TODO
+
+```c
+TODO
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+</section>
+
+<!-- /.notes -->
+
+<!-- C API usage examples. -->
+
+<section class="examples">
+
+### Examples
+
+```c
+TODO
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.c -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[lapack]: https://www.netlib.org/lapack/explore-html/
+
+[lapack-dlagts]: https://www.netlib.org/lapack/explore-html/d3/d06/group__lagts_gae549d3c611a2af3ca272095fafb9f5b3.html
+
+[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
+
+[mdn-int32array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
+
+[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+
+</section>
+
+<!-- /.links -->