feat: add lapack/base/dlarfb

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

@@ -0,0 +1,270 @@
+<!--
+
+@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.
+
+-->
+
+# dlarfb
+
+> LAPACK routine to apply a real block reflector `H` or its transpose `H ^ T` to a real `M` by `N` matrix `C`, from either the left or the right.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var dlarfb = require( '@stdlib/lapack/base/dlarfb' );
+```
+
+<!-- lint disable maximum-heading-length -->
+
+#### dlarfb( order, side, trans, direct, storev, M, N, K, V, LDV, T, LDT, C, LDC, work, LDWORK )
+
+Applies a real block reflector `H` or its transpose `H ^ T` to a real `M` by `N` matrix `C`, from either the left or the right.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+
+var V = new Float64Array( [ 10.0, 40.0, 70.0, 20.0, 50.0, 80.0, 30.0, 60.0, 90.0 ] );
+var T = new Float64Array( [ 1.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 0.0, 3.0 ] );
+var C = new Float64Array( [ 11.0, 12.0, 13.0, 21.0, 22.0, 23.0, 31.0, 32.0, 33.0 ] );
+var work = new Float64Array( 9 );
+
+dlarfb( 'row-major', 'left', 'transpose', 'forward', 'columns', 3, 3, 3, V, 3, T, 3, C, 3, work, 3 );
+// C => <Float64Array>[ -1350.00, -1400.00, -1450.00, -30961.00, -32102.00, -33243.00, -266612.00, -275464.00, -284316.00 ]
+```
+
+The function has the following parameters:
+
+-   **order**: storage layout (`'row-major'` or `'column-major'`).
+-   **side**: specifies whether `H` or `H ^ T` is applied from the left or right (`'left'` or `'right'`).
+-   **trans**: specifies whether to apply `H` or `H ^ T` (`'no-transpose'` or `'transpose'`).
+-   **direct**: indicates how `H` is formed from a product of elementary reflectors (`'forward'` or `'backward'`).
+-   **storev**: indicates how the vectors which define the elementary reflectors are stored (`'column-major'` or `'row-major'`).
+-   **M**: number of rows of the matrix `C`.
+-   **N**: number of columns of the matrix `C`.
+-   **K**: order of the matrix `T`.
+-   **V**: input matrix stored as a [`Float64Array`][mdn-float64array].
+-   **LDV**: leading dimension of `V`.
+-   **T**: input matrix (upper/lower triangular as dictated by `direct`/`storev`) stored as a [`Float64Array`][mdn-float64array].
+-   **LDT**: leading dimension of `T` (must be ≥ max(1,K)).
+-   **C**: input/output matrix stored as a [`Float64Array`][mdn-float64array].
+-   **LDC**: leading dimension of `C`.
+-   **work**: work array stored as a [`Float64Array`][mdn-float64array].
+-   **LDWORK**: leading dimension of `work`.
+
+The function applies the block reflector `H` to matrix `C` according to the specified parameters. The `side` parameter determines whether the transformation is applied from the left (`C = H*C` or `C = H^T*C`) or from the right (`C = C*H` or `C = C*H^T`).
+
+#### dlarfb.ndarray( side, trans, direct, storev, M, N, K, V, strideV1, strideV2, offsetV, T, strideT1, strideT2, offsetT, C, strideC1, strideC2, offsetC, work, strideWork1, strideWork2, offsetWork )
+
+Applies a real block reflector `H` or its transpose `H ^ T` to a real `M` by `N` matrix `C`, from either the left or the right, using alternative indexing semantics.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+
+var V = new Float64Array( [ 10.0, 40.0, 70.0, 20.0, 50.0, 80.0, 30.0, 60.0, 90.0 ] );
+var T = new Float64Array( [ 1.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 0.0, 3.0 ] );
+var C = new Float64Array( [ 11.0, 12.0, 13.0, 21.0, 22.0, 23.0, 31.0, 32.0, 33.0 ] );
+var work = new Float64Array( 9 );
+
+dlarfb.ndarray( 'left', 'transpose', 'forward', 'columns', 3, 3, 3, V, 3, 1, 0, T, 3, 1, 0, C, 3, 1, 0, work, 3, 1, 0 );
+// C => <Float64Array>[ -1350.00, -1400.00, -1450.00, -30961.00, -32102.00, -33243.00, -266612.00, -275464.00, -284316.00 ]
+```
+
+The function has the following additional parameters:
+
+-   **side**: specifies whether `H` or `H ^ T` is applied from the left or right (`'left'` or `'right'`).
+-   **trans**: specifies whether to apply `H` or `H ^ T` (`'no-transpose'` or `'transpose'`).
+-   **direct**: indicates how `H` is formed from a product of elementary reflectors (`'forward'` or `'backward'`).
+-   **storev**: indicates how the vectors which define the elementary reflectors are stored (`'columns'` or `'rows'`).
+-   **M**: number of rows of the matrix `C`.
+-   **N**: number of columns of the matrix `C`.
+-   **K**: order of the matrix `T`.
+-   **V**: input matrix stored as a [`Float64Array`][mdn-float64array].
+-   **strideV1**: stride of the first dimension of `V`.
+-   **strideV2**: stride of the second dimension of `V`.
+-   **offsetV**: index offset for `V`.
+-   **T**: input matrix stored as a [`Float64Array`][mdn-float64array].
+-   **strideT1**: stride of the first dimension of `T`.
+-   **strideT2**: stride of the second dimension of `T`.
+-   **offsetT**: index offset for `T`.
+-   **C**: input/output matrix stored as a [`Float64Array`][mdn-float64array].
+-   **strideC1**: stride of the first dimension of `C`.
+-   **strideC2**: stride of the second dimension of `C`.
+-   **offsetC**: index offset for `C`.
+-   **work**: work array stored as a [`Float64Array`][mdn-float64array].
+-   **strideWork1**: stride of the first dimension of `work`.
+-   **strideWork2**: stride of the second dimension of `work`.
+-   **offsetWork**: index offset for `work`.
+
+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.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   Both functions apply the block reflector `H` to matrix `C` according to the specified parameters.
+-   The `side` parameter determines whether the transformation is applied from the left or right.
+-   The `trans` parameter determines whether to apply `H` or its transpose `H^T`.
+-   The `direct` parameter indicates the order in which elementary reflectors are applied.
+-   The `storev` parameter indicates how the elementary reflector vectors are stored.
+-   `dlarfb()` corresponds to the [LAPACK][LAPACK] function [`dlarfb`][lapack-dlarfb].
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint-disable max-len -->
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var dlarfb = require( '@stdlib/lapack/base/dlarfb' );
+
+// Specify matrix meta data:
+var shape = [ 3, 3 ];
+var strides = [ 1, 3 ];
+var offset = 0;
+var order = 'row-major';
+
+// Create matrices stored in linear memory:
+var V = new Float64Array( [ 10.0, 40.0, 70.0, 20.0, 50.0, 80.0, 30.0, 60.0, 90.0 ] );
+var T = new Float64Array( [ 1.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 0.0, 3.0 ] );
+var C = new Float64Array( [ 11.0, 12.0, 13.0, 21.0, 22.0, 23.0, 31.0, 32.0, 33.0 ] );
+var work = new Float64Array( 9 );
+
+console.log( 'Original matrix C:' );
+console.log( ndarray2array( C, shape, strides, offset, order ) );
+
+// Apply block reflector from the left:
+dlarfb( order, 'left', 'transpose', 'forward', 'columns', 3, 3, 3, V, 3, T, 3, C, 3, work, 3 );
+
+console.log( 'Matrix C after applying block reflector:' );
+console.log( ndarray2array( C, shape, strides, offset, order ) );
+```
+
+</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-dlarfb]: https://www.netlib.org/lapack/explore-html-3.6.1/db/df4/dlarfb_8f_a74a89b426b40fa4fff93d2f7cc4b5aa7.html
+
+[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
+
+[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+
+</section>
+
+<!-- /.links -->