feat: add C ndarray implementation for blas/base/zscal

PR-URL: stdlib-js#4864
Ref: stdlib-js#2039
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]> 
Co-authored-by: stdlib-bot <[email protected]>

Author: 3 people

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

@@ -2,7 +2,7 @@
 
 @license Apache-2.0
 
-Copyright (c) 2024 The Stdlib Authors.
+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.
@@ -30,39 +30,39 @@ limitations under the License.
 var zscal = require( '@stdlib/blas/base/zscal' );
 ```
 
-#### zscal( N, za, zx, strideX )
+#### zscal( N, alpha, x, strideX )
 
-Scales values from `zx` by `za`.
+Scales values from `x` by `alpha`.
 
 ```javascript
 var Complex128Array = require( '@stdlib/array/complex128' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 
-var zx = new Complex128Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
-var za = new Complex128( 2.0, 0.0 );
+var x = new Complex128Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
+var alpha = new Complex128( 2.0, 0.0 );
 
-zscal( 3, za, zx, 1 );
-// zx => <Complex128Array>[ 2.0, 2.0, 2.0, 2.0, 2.0, 2.0 ]
+zscal( 3, alpha, x, 1 );
+// x => <Complex128Array>[ 2.0, 2.0, 2.0, 2.0, 2.0, 2.0 ]
 ```
 
 The function has the following parameters:
 
 -   **N**: number of indexed elements.
--   **za**: scalar [`Complex128`][@stdlib/complex/float64/ctor] constant.
--   **zx**: input [`Complex128Array`][@stdlib/array/complex128].
--   **strideX**: index increment for `zx`.
+-   **alpha**: scalar [`Complex128`][@stdlib/complex/float64/ctor] constant.
+-   **x**: input [`Complex128Array`][@stdlib/array/complex128].
+-   **strideX**: index increment for `x`.
 
-The `N` and stride parameters determine how values from `zx` are scaled by `za`. For example, to scale every other value in `zx` by `za`,
+The `N` and stride parameters determine how values from `x` are scaled by `alpha`. For example, to scale every other value in `x` by `alpha`,
 
 ```javascript
 var Complex128Array = require( '@stdlib/array/complex128' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 
-var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
-var za = new Complex128( 2.0, 0.0 );
+var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
+var alpha = new Complex128( 2.0, 0.0 );
 
-zscal( 2, za, zx, 2 );
-// zx => <Complex128Array>[ 2.0, 4.0, 3.0, 4.0, 10.0, 12.0, 7.0, 8.0 ]
+zscal( 2, alpha, x, 2 );
+// x => <Complex128Array>[ 2.0, 4.0, 3.0, 4.0, 10.0, 12.0, 7.0, 8.0 ]
 ```
 
 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
@@ -74,49 +74,49 @@ var Complex128Array = require( '@stdlib/array/complex128' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 
 // Initial array:
-var zx0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
+var x0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
 
 // Define a scalar constant:
-var za = new Complex128( 2.0, 2.0 );
+var alpha = new Complex128( 2.0, 2.0 );
 
 // Create an offset view:
-var zx1 = new Complex128Array( zx0.buffer, zx0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
+var x1 = new Complex128Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
 
 // Scales every other value from `zx1` by `za`...
-zscal( 3, za, zx1, 1 );
-// zx0 => <Complex128Array>[ 1.0, 2.0, -2.0, 14.0, -2.0, 22.0, -2.0, 30.0 ]
+zscal( 3, alpha, x1, 1 );
+// x0 => <Complex128Array>[ 1.0, 2.0, -2.0, 14.0, -2.0, 22.0, -2.0, 30.0 ]
 ```
 
-#### zscal.ndarray( N, za, zx, strideX, offsetX )
+#### zscal.ndarray( N, alpha, x, strideX, offsetX )
 
-Scales values from `zx` by `za` using alternative indexing semantics.
+Scales values from `x` by `alpha` using alternative indexing semantics.
 
 ```javascript
 var Complex128Array = require( '@stdlib/array/complex128' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 
-var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
-var za = new Complex128( 2.0, 2.0 );
+var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+var alpha = new Complex128( 2.0, 2.0 );
 
-zscal.ndarray( 3, za, zx, 1, 0 );
-// zx => <Complex128Array>[ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ]
+zscal.ndarray( 3, alpha, x, 1, 0 );
+// x => <Complex128Array>[ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ]
 ```
 
 The function has the following additional parameters:
 
--   **offsetX**: starting index for `zx`.
+-   **offsetX**: starting index for `x`.
 
 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to scale every other value in the input strided array starting from the second element,
 
 ```javascript
 var Complex128Array = require( '@stdlib/array/complex128' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 
-var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
-var za = new Complex128( 2.0, 2.0 );
+var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
+var alpha = new Complex128( 2.0, 2.0 );
 
-zscal.ndarray( 2, za, zx, 2, 1 );
-// zx => <Complex128Array>[ 1.0, 2.0, -2.0, 14.0, 5.0, 6.0, -2.0, 30.0 ]
+zscal.ndarray( 2, alpha, x, 2, 1 );
+// x => <Complex128Array>[ 1.0, 2.0, -2.0, 14.0, 5.0, 6.0, -2.0, 30.0 ]
 ```
 
 </section>
@@ -127,7 +127,7 @@ zscal.ndarray( 2, za, zx, 2, 1 );
 
 ## Notes
 
--   If `N <= 0` or `strideX <= 0` , both functions return `zx` unchanged.
+-   If `N <= 0` , both functions return `x` unchanged.
 -   `zscal()` corresponds to the [BLAS][blas] level 1 function [`zscal`][zscal].
 
 </section>
@@ -150,15 +150,15 @@ function rand() {
     return new Complex128( discreteUniform( 0, 10 ), discreteUniform( -5, 5 ) );
 }
 
-var zx = filledarrayBy( 10, 'complex128', rand );
-console.log( zx.toString() );
+var x = filledarrayBy( 10, 'complex128', rand );
+console.log( x.toString() );
 
-var za = new Complex128( 2.0, 2.0 );
-console.log( za.toString() );
+var alpha = new Complex128( 2.0, 2.0 );
+console.log( alpha.toString() );
 
-// Scales elements from `zx` by `za`:
-zscal( zx.length, za, zx, 1 );
-console.log( zx.get( zx.length-1 ).toString() );
+// Scales elements from `x` by `alpha`:
+zscal( x.length, alpha, x, 1 );
+console.log( x.get( x.length-1 ).toString() );
 ```
 
 </section>
@@ -191,28 +191,53 @@ console.log( zx.get( zx.length-1 ).toString() );
 #include "stdlib/blas/base/zscal.h"
 ```
 
-#### c_zscal( N, za, \*ZX, strideX )
+#### c_zscal( N, alpha, \*X, strideX )
 
-Scales values from `ZX` by `za`.
+Scales values from `X` by `alpha`.
 
 ```c
 #include "stdlib/complex/float64/ctor.h"
 
-double zx[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
-const stdlib_complex128_t za = stdlib_complex128( 2.0, 2.0 );
+double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
+const stdlib_complex128_t alpha = stdlib_complex128( 2.0, 2.0 );
 
-c_zscal( 4, za, (void *)zx, 1 );
+c_zscal( 4, alpha, (void *)x, 1 );
 ```
 
 The function accepts the following arguments:
 
 -   **N**: `[in] CBLAS_INT` number of indexed elements.
--   **za**: `[in] stdlib_complex128_t` scalar constant.
--   **ZX**: `[inout] void*` input array.
--   **strideX**: `[in] CBLAS_INT` index increment for `ZX`.
+-   **alpha**: `[in] stdlib_complex128_t` scalar constant.
+-   **X**: `[inout] void*` input array.
+-   **strideX**: `[in] CBLAS_INT` index increment for `X`.
 
 ```c
-void c_zscal( const CBLAS_INT N, const stdlib_complex128_t za, void *ZX, const CBLAS_INT strideX );
+void c_zscal( const CBLAS_INT N, const stdlib_complex128_t alpha, void *X, const CBLAS_INT strideX );
+```
+
+#### c_zscal_ndarray( N, alpha, \*X, strideX, offsetX )
+
+Scales values from `X` by `alpha` using alternative indexing semantics.
+
+```c
+#include "stdlib/complex/float64/ctor.h"
+
+double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
+const stdlib_complex128_t alpha = stdlib_complex128( 2.0, 2.0 );
+
+c_zscal_ndarray( 4, alpha, (void *)x, 1, 0 );
+```
+
+The function accepts the following arguments:
+
+-   **N**: `[in] CBLAS_INT` number of indexed elements.
+-   **alpha**: `[in] stdlib_complex128_t` scalar constant.
+-   **X**: `[inout] void*` input array.
+-   **strideX**: `[in] CBLAS_INT` index increment for `X`.
+-   **offsetX**: `[in] CBLAS_INT` starting index for `X`.
+
+```c
+void c_zscal_ndarray( const CBLAS_INT N, const stdlib_complex128_t alpha, void *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
 ```
 
 </section>
@@ -240,10 +265,10 @@ void c_zscal( const CBLAS_INT N, const stdlib_complex128_t za, void *ZX, const C
 
 int main( void ) {
     // Create a strided array of interleaved real and imaginary components:
-    double zx[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
+    double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
 
     // Create a complex scalar:
-    const stdlib_complex128_t ca = stdlib_complex128( 2.0, 2.0 );
+    const stdlib_complex128_t alpha = stdlib_complex128( 2.0, 2.0 );
 
     // Specify the number of elements:
     const int N = 4;
@@ -252,11 +277,19 @@ int main( void ) {
     const int strideX = 1;
 
     // Scale the elements of the array:
-    c_zscal( N, za, (void *)zx, strideX );
+    c_zscal( N, alpha, (void *)x, strideX );
+
+    // Print the result:
+    for ( int i = 0; i < N; i++ ) {
+        printf( "x[ %i ] = %lf + %lfj\n", i, x[ i*2 ], x[ (i*2)+1 ] );
+    }
+
+    // Scale the elements of the array using alternative indexing semantics:
+    c_zscal_ndarray( N, alpha, (void *)x, -strideX, N-1 );
 
     // Print the result:
     for ( int i = 0; i < N; i++ ) {
-        printf( "zx[ %i ] = %f + %fj\n", i, zx[ i*2 ], zx[ (i*2)+1 ] );
+        printf( "x[ %i ] = %lf + %lfj\n", i, x[ i*2 ], x[ (i*2)+1 ] );
     }
 }
 ```

lib/node_modules/@stdlib/blas/base/zscal/benchmark/c/benchmark.length.c

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2024 The Stdlib Authors.
+* 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.
@@ -95,7 +95,7 @@ static double rand_double( void ) {
 * @param len          array length
 * @return             elapsed time in seconds
 */
-static double benchmark( int iterations, int len ) {
+static double benchmark1( int iterations, int len ) {
 	stdlib_complex128_t za;
 	double zx[ len*2 ];
 	double elapsed;
@@ -122,6 +122,40 @@ static double benchmark( int iterations, int len ) {
 	return elapsed;
 }
 
+/**
+* Runs a benchmark.
+*
+* @param iterations   number of iterations
+* @param len          array length
+* @return             elapsed time in seconds
+*/
+static double benchmark2( int iterations, int len ) {
+	stdlib_complex128_t za;
+	double zx[ len*2 ];
+	double elapsed;
+	double t;
+	int i;
+
+	za = stdlib_complex128( 1.0, 0.0 );
+	for ( i = 0; i < len*2; i+=2 ) {
+		zx[ i ] = ( rand_double()*2.0 ) - 1.0;
+		zx[ i+1 ] = ( rand_double()*2.0 ) - 1.0;
+	}
+	t = tic();
+	for ( i = 0; i < iterations; i++ ) {
+		c_zscal_ndarray( len, za, (void *)zx, 1, 0 );
+		if ( zx[ 0 ] != zx[ 0 ] ) {
+			printf( "should not return NaN\n" );
+			break;
+		}
+	}
+	elapsed = tic() - t;
+	if ( zx[ 0 ] != zx[ 0 ] ) {
+		printf( "should not return NaN\n" );
+	}
+	return elapsed;
+}
+
 /**
 * Main execution sequence.
 */
@@ -144,7 +178,14 @@ int main( void ) {
 		for ( j = 0; j < REPEATS; j++ ) {
 			count += 1;
 			printf( "# c::%s:len=%d\n", NAME, len );
-			elapsed = benchmark( iter, len );
+			elapsed = benchmark1( iter, len );
+			print_results( iter, elapsed );
+			printf( "ok %d benchmark finished\n", count );
+		}
+		for ( j = 0; j < REPEATS; j++ ) {
+			count += 1;
+			printf( "# c::%s:ndarray:len=%d\n", NAME, len );
+			elapsed = benchmark2( iter, len );
 			print_results( iter, elapsed );
 			printf( "ok %d benchmark finished\n", count );
 		}