feat: add blas/base/ctrsm

lib/node_modules/@stdlib/blas/base/ctrsm/README.md

@@ -0,0 +1,158 @@
+<!--
+
+@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.
+
+-->
+
+# ctrsm
+
+> Solve one of the matrix equations `op(A)*X = alpha*B` or `X*op(A) = alpha*B`.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var ctrsm = require( '@stdlib/blas/base/ctrsm' );
+```
+
+#### ctrsm( order, side, uplo, transa, diag, M, N, alpha, A, LDA, B, LDB )
+
+Solves one of the matrix equations `op(A)*X = alpha*B` or `X*op(A) = alpha*B` where `alpha` is a scalar, `X` and `B` are `M` by `N` matrices, `A` is a unit or non-unit upper or lower triangular matrix, and `op(A)` is one of `op(A) = A`, `op(A) = A^T`, or `op(A) = A^H`. The matrix `X` is overwritten on `B`.
+
+```javascript
+var Complex64Array = require( '@stdlib/array/complex64' );
+var Complex64 = require( '@stdlib/complex/float32/ctor' );
+
+var A = new Complex64Array( [ 2.0, 0.0, 1.0, 0.0, 0.0, 0.0, 2.0, 0.0 ] );
+var B = new Complex64Array( [ 4.0, 0.0, 2.0, 0.0 ] );
+var alpha = new Complex64( 1.0, 0.0 );
+
+ctrsm( 'row-major', 'left', 'upper', 'no-transpose', 'non-unit', 2, 1, alpha, A, 2, B, 1 );
+// B => <Complex64Array>[ 1.5, 0.0, 1.0, 0.0 ]
+```
+
+The function has the following parameters:
+
+-   **order**: storage layout.
+-   **side**: specifies whether `A` appears on the `'left'` or `'right'` of `X`.
+-   **uplo**: specifies whether the `'upper'` or `'lower'` triangular part of `A` is used.
+-   **transa**: transpose operation applied to `A` (`'no-transpose'`, `'transpose'`, or `'conjugate-transpose'`).
+-   **diag**: specifies whether `A` is `'unit'` or `'non-unit'` triangular.
+-   **M**: number of rows in `B`.
+-   **N**: number of columns in `B`.
+-   **alpha**: scalar constant of type `Complex64`.
+-   **A**: input triangular matrix stored in a `Complex64Array`.
+-   **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of `A`).
+-   **B**: input/output matrix stored in a `Complex64Array`. On exit, overwritten with solution `X`.
+-   **LDB**: stride of the first dimension of `B` (a.k.a., leading dimension of `B`).
+
+#### ctrsm.ndarray( ord, sd, ul, ta, dg, M, N, aRe, aIm, A, sa1, oa, B, sb1, ob )
+
+Solves one of the matrix equations using alternative indexing semantics.
+
+```javascript
+var Complex64Array = require( '@stdlib/array/complex64' );
+
+var A = new Complex64Array( [ 2.0, 0.0, 1.0, 0.0, 0.0, 0.0, 2.0, 0.0 ] );
+var B = new Complex64Array( [ 4.0, 0.0, 2.0, 0.0 ] );
+
+ctrsm.ndarray( 'row-major', 'left', 'upper', 'no-transpose', 'non-unit', 2, 1, 1.0, 0.0, A, 2, 0, B, 1, 0 );
+// B => <Complex64Array>[ 1.5, 0.0, 1.0, 0.0 ]
+```
+
+The function accepts the following additional parameters:
+
+-   **aRe**: real part of scalar constant `alpha`.
+-   **aIm**: imaginary part of scalar constant `alpha`.
+-   **sa1**: stride of the first dimension of `A`.
+-   **oa**: starting index for `A`.
+-   **sb1**: stride of the first dimension of `B`.
+-   **ob**: starting index for `B`.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   `ctrsm()` corresponds to the [BLAS][blas] level 3 function [`ctrsm`][blas-ctrsm].
+-   Neither routine tests for singularity or near-singularity of `A`. Such tests must be performed before calling these routines.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+var Complex64 = require( '@stdlib/complex/float32/ctor' );
+var ctrsm = require( '@stdlib/blas/base/ctrsm' );
+
+var N = 3;
+
+var opts = {
+    'dtype': 'complex64'
+};
+var A = discreteUniform( N * N, -10, 10, opts );
+var B = discreteUniform( N * N, -10, 10, opts );
+var alpha = new Complex64( 1.0, 0.0 );
+
+ctrsm( 'row-major', 'left', 'upper', 'no-transpose', 'non-unit', N, N, alpha, A, N, B, N );
+console.log( B );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/blas/base/strsm`][@stdlib/blas/base/strsm]</span><span class="delimiter">: </span><span class="description">solve one of the matrix equations `op(A)*X = alpha*B` or `X*op(A) = alpha*B` where `A` is a real single-precision triangular matrix.</span>
+-   <span class="package-name">[`@stdlib/blas/base/dtrsm`][@stdlib/blas/base/dtrsm]</span><span class="delimiter">: </span><span class="description">solve one of the matrix equations `op(A)*X = alpha*B` or `X*op(A) = alpha*B` where `A` is a real double-precision triangular matrix.</span>
+-   <span class="package-name">[`@stdlib/blas/base/ztrsm`][@stdlib/blas/base/ztrsm]</span><span class="delimiter">: </span><span class="description">solve one of the matrix equations `op(A)*X = alpha*B` or `X*op(A) = alpha*B` where `A` is a complex double-precision triangular matrix.</span>
+
+</section>
+
+<!-- /.related -->
+
+<section class="links">
+
+[blas]: http://www.netlib.org/blas
+
+[blas-ctrsm]: https://www.netlib.org/lapack/explore-html/d1/d54/group__complex__blas__level3_ga7dbc51a6f35e10bc3c63dfc62c1d6db8.html
+
+[@stdlib/blas/base/strsm]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/strsm
+
+[@stdlib/blas/base/dtrsm]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/dtrsm
+
+[@stdlib/blas/base/ztrsm]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/ztrsm
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/blas/base/ctrsm/benchmark/benchmark.js

@@ -0,0 +1,115 @@
+/**
+* @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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
+var pow = require( '@stdlib/math/base/special/pow' );
+var Complex64Array = require( '@stdlib/array/complex64' );
+var Complex64 = require( '@stdlib/complex/float32/ctor' );
+var format = require( '@stdlib/string/format' );
+var pkg = require( './../package.json' ).name;
+var ctrsm = require( './../lib' );
+
+
+// VARIABLES //
+
+var options = {
+	'dtype': 'float32'
+};
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} N - matrix dimension
+* @returns {Function} benchmark function
+*/
+function createBenchmark( N ) {
+	var alpha;
+	var abuf;
+	var bbuf;
+	var A;
+	var B;
+
+	abuf = uniform( N*N*2, -100.0, 100.0, options );
+	bbuf = uniform( N*N*2, -100.0, 100.0, options );
+	A = new Complex64Array( abuf.buffer );
+	B = new Complex64Array( bbuf.buffer );
+	alpha = new Complex64( 1.0, 0.0 );
+
+	return benchmark;
+
+	/**
+	* Benchmark function.
+	*
+	* @private
+	* @param {Benchmark} b - benchmark instance
+	*/
+	function benchmark( b ) {
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			ctrsm( 'row-major', 'left', 'upper', 'no-transpose', 'non-unit', N, N, alpha, A, N, B, N );
+			if ( isnanf( bbuf[ i%(N*N*2) ] ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnanf( bbuf[ i%(N*N*2) ] ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+*/
+function main() {
+	var len;
+	var min;
+	var max;
+	var f;
+	var i;
+
+	min = 1; // 10^min
+	max = 3; // 10^max
+
+	for ( i = min; i <= max; i++ ) {
+		len = pow( 10, i );
+		f = createBenchmark( len );
+		bench( format( '%s:order=row-major,side=left,uplo=upper,trans=no-transpose,diag=non-unit,M=%d,N=%d', pkg, len, len ), f );
+	}
+}
+
+main();

lib/node_modules/@stdlib/blas/base/ctrsm/benchmark/benchmark.native.js

@@ -0,0 +1,120 @@
+/**
+* @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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var resolve = require( 'path' ).resolve;
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
+var pow = require( '@stdlib/math/base/special/pow' );
+var Complex64Array = require( '@stdlib/array/complex64' );
+var Complex64 = require( '@stdlib/complex/float32/ctor' );
+var tryRequire = require( '@stdlib/utils/try-require' );
+var format = require( '@stdlib/string/format' );
+var pkg = require( './../package.json' ).name;
+
+
+// VARIABLES //
+
+var ctrsm = tryRequire( resolve( __dirname, './../lib/ctrsm.native.js' ) );
+var opts = {
+	'skip': ( ctrsm instanceof Error )
+};
+var options = {
+	'dtype': 'float32'
+};
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} N - matrix dimension
+* @returns {Function} benchmark function
+*/
+function createBenchmark( N ) {
+	var alpha;
+	var abuf;
+	var bbuf;
+	var A;
+	var B;
+
+	abuf = uniform( N*N*2, -100.0, 100.0, options );
+	bbuf = uniform( N*N*2, -100.0, 100.0, options );
+	A = new Complex64Array( abuf.buffer );
+	B = new Complex64Array( bbuf.buffer );
+	alpha = new Complex64( 1.0, 0.0 );
+
+	return benchmark;
+
+	/**
+	* Benchmark function.
+	*
+	* @private
+	* @param {Benchmark} b - benchmark instance
+	*/
+	function benchmark( b ) {
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			ctrsm( 'row-major', 'left', 'upper', 'no-transpose', 'non-unit', N, N, alpha, A, N, B, N );
+			if ( isnanf( bbuf[ i%(N*N*2) ] ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnanf( bbuf[ i%(N*N*2) ] ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+*/
+function main() {
+	var len;
+	var min;
+	var max;
+	var f;
+	var i;
+
+	min = 1; // 10^min
+	max = 3; // 10^max
+
+	for ( i = min; i <= max; i++ ) {
+		len = pow( 10, i );
+		f = createBenchmark( len );
+		bench( format( '%s::native:order=row-major,side=left,uplo=upper,trans=no-transpose,diag=non-unit,M=%d,N=%d', pkg, len, len ), opts, f );
+	}
+}
+
+main();