feat!: add C ndarray API and refactor blas/ext/base/sapx

This PR renames `c_sapx` to `stdlib_strided_sapx`. The original naming convention stemmed from early construction of the `blas/ext/base` namespace in which it was not known whether to follow BLAS conventions (e.g., `c_*`) or stdlib's strided naming conventions (e.g., `stdlib_strided_`). Ultimately, we've opted to only use BLAS and LAPACK conventions for the known symbols in those respective libraries in order to avoid future naming collisions and explicitly distinguish stdlib's extensions from that of symbols whose origins are found elsewhere.

BREAKING CHANGE: rename `c_sapx` to `stdlib_strided_sapx`

To migrate, users should replace all instances of `c_sapx` with `stdlib_strided_sapx`.

PR-URL: stdlib-js#4696
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]>

Author: 2 people

lib/node_modules/@stdlib/blas/ext/base/sapx/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # sapx
 
-> Add a constant to each element in a single-precision floating-point strided array.
+> Add a scalar constant to each element in a single-precision floating-point strided array.
 
 <section class="usage">
 
@@ -30,9 +30,9 @@ limitations under the License.
 var sapx = require( '@stdlib/blas/ext/base/sapx' );
 ```
 
-#### sapx( N, alpha, x, stride )
+#### sapx( N, alpha, x, strideX )
 
-Adds a constant `alpha` to each element in a single-precision floating-point strided array `x`.
+Adds a scalar constant to each element in a single-precision floating-point strided array.
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
@@ -48,9 +48,9 @@ The function has the following parameters:
 -   **N**: number of indexed elements.
 -   **alpha**: scalar constant.
 -   **x**: input [`Float32Array`][@stdlib/array/float32].
--   **stride**: index increment.
+-   **strideX**: stride length.
 
-The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to add a constant to every other element
+The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to add a constant to every other element:
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
@@ -77,9 +77,9 @@ sapx( 3, 5.0, x1, 2 );
 // x0 => <Float32Array>[ 1.0, 3.0, 3.0, 1.0, 5.0, -1.0 ]
 ```
 
-#### sapx.ndarray( N, alpha, x, stride, offset )
+#### sapx.ndarray( N, alpha, x, strideX, offsetX )
 
-Adds a constant `alpha` to each element in a single-precision floating-point strided array `x` using alternative indexing semantics.
+Adds a scalar constant to each element in a single-precision floating-point strided array using alternative indexing semantics.
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
@@ -92,9 +92,9 @@ sapx.ndarray( x.length, 5.0, x, 1, 0 );
 
 The function has the following additional parameters:
 
--   **offset**: starting index.
+-   **offsetX**: starting index.
 
-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 access only the last three elements of the strided array
+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 access only the last three elements of the strided array:
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
@@ -126,11 +126,12 @@ sapx.ndarray( 3, 5.0, x, 1, x.length-3 );
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var uniform = require( '@stdlib/random/base/uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var sapx = require( '@stdlib/blas/ext/base/sapx' );
 
-var x = filledarrayBy( 10, 'float32', uniform( -100.0, 100.0 ) );
+var x = discreteUniform( 10, -100, 100, {
+    'dtype': 'float32'
+});
 console.log( x );
 
 sapx( x.length, 5.0, x, 1 );
@@ -141,6 +142,125 @@ console.log( x );
 
 <!-- /.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
+#include "stdlib/blas/ext/base/sapx.h"
+```
+
+#### stdlib_strided_sapx( N, alpha, \*X, strideX )
+
+Adds a scalar constant to each element in a single-precision floating-point strided array.
+
+```c
+float x[] = { 1.0f, 2.0f, 3.0f, 4.0f };
+
+stdlib_strided_sapx( 4, 5.0f, x, 1 );
+```
+
+The function accepts the following arguments:
+
+-   **N**: `[in] CBLAS_INT` number of indexed elements.
+-   **alpha**: `[in] float` scalar constant.
+-   **X**: `[inout] float*` input array.
+-   **strideX**: `[in] CBLAS_INT` stride length.
+
+```c
+void stdlib_strided_sapx( const CBLAS_INT N, const float alpha, float *X, const CBLAS_INT strideX );
+```
+
+#### stdlib_strided_sapx_ndarray( N, alpha, \*X, strideX, offsetX )
+
+Adds a scalar constant to each element in a single-precision floating-point strided array using alternative indexing semantics.
+
+```c
+float x[] = { 1.0f, 2.0f, 3.0f, 4.0f };
+
+stdlib_strided_sapx_ndarray( 4, 5.0f, x, 1, 0 );
+```
+
+The function accepts the following arguments:
+
+-   **N**: `[in] CBLAS_INT` number of indexed elements.
+-   **alpha**: `[in] float` scalar constant.
+-   **X**: `[inout] float*` input array.
+-   **strideX**: `[in] CBLAS_INT` stride length.
+-   **offsetX**: `[in] CBLAS_INT` starting index.
+
+```c
+void stdlib_strided_sapx_ndarray( const CBLAS_INT N, const float alpha, float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
+```
+
+</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
+#include "stdlib/blas/ext/base/sapx.h"
+#include <stdio.h>
+
+int main( void ) {
+    // Create a strided array:
+    float x[] = { 1.0f, -2.0f, 3.0f, -4.0f, 5.0f, -6.0f, 7.0f, -8.0f };
+
+    // Specify the number of indexed elements:
+    const int N = 8;
+
+    // Specify a stride:
+    const int strideX = 1;
+
+    // Add a constant to each element:
+    stdlib_strided_sapx( N, 5.0f, x, strideX );
+
+    // Print the result:
+    for ( int i = 0; i < 8; i++ ) {
+        printf( "x[ %i ] = %f\n", i, x[ i ] );
+    }
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.c -->
+
 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
 
 <section class="related">

lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.js

@@ -21,8 +21,7 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var uniform = require( '@stdlib/random/base/uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var pkg = require( './../package.json' ).name;
@@ -31,7 +30,9 @@ var sapx = require( './../lib/sapx.js' );
 
 // VARIABLES //
 
-var rand = uniform( -100.0, 100.0 );
+var options = {
+	'dtype': 'float32'
+};
 
 
 // FUNCTIONS //
@@ -44,7 +45,7 @@ var rand = uniform( -100.0, 100.0 );
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = filledarrayBy( len, 'float32', rand );
+	var x = uniform( len, -100, 100, options );
 	return benchmark;
 
 	function benchmark( b ) {

lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.native.js

@@ -22,8 +22,7 @@
 
 var resolve = require( 'path' ).resolve;
 var bench = require( '@stdlib/bench' );
-var uniform = require( '@stdlib/random/base/uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var tryRequire = require( '@stdlib/utils/try-require' );
@@ -36,7 +35,9 @@ var sapx = tryRequire( resolve( __dirname, './../lib/sapx.native.js' ) );
 var opts = {
 	'skip': ( sapx instanceof Error )
 };
-var rand = uniform( -100.0, 100.0 );
+var options = {
+	'dtype': 'float32'
+};
 
 
 // FUNCTIONS //
@@ -49,7 +50,7 @@ var rand = uniform( -100.0, 100.0 );
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = filledarrayBy( len, 'float32', rand );
+	var x = uniform( len, -100, 100, options );
 	return benchmark;
 
 	function benchmark( b ) {

lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.ndarray.js

@@ -21,8 +21,7 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var uniform = require( '@stdlib/random/base/uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var pkg = require( './../package.json' ).name;
@@ -31,7 +30,9 @@ var sapx = require( './../lib/ndarray.js' );
 
 // VARIABLES //
 
-var rand = uniform( -100.0, 100.0 );
+var options = {
+	'dtype': 'float32'
+};
 
 
 // FUNCTIONS //
@@ -44,7 +45,7 @@ var rand = uniform( -100.0, 100.0 );
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = filledarrayBy( len, 'float32', rand );
+	var x = uniform( len, -100, 100, options );
 	return benchmark;
 
 	function benchmark( b ) {

lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.ndarray.native.js

@@ -22,8 +22,7 @@
 
 var resolve = require( 'path' ).resolve;
 var bench = require( '@stdlib/bench' );
-var uniform = require( '@stdlib/random/base/uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var tryRequire = require( '@stdlib/utils/try-require' );
@@ -36,7 +35,9 @@ var sapx = tryRequire( resolve( __dirname, './../lib/ndarray.native.js' ) );
 var opts = {
 	'skip': ( sapx instanceof Error )
 };
-var rand = uniform( -100.0, 100.0 );
+var options = {
+	'dtype': 'float32'
+};
 
 
 // FUNCTIONS //
@@ -49,7 +50,7 @@ var rand = uniform( -100.0, 100.0 );
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
-	var x = filledarrayBy( len, 'float32', rand );
+	var x = uniform( len, -100, 100, options );
 	return benchmark;
 
 	function benchmark( b ) {

lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/c/benchmark.length.c

@@ -94,7 +94,7 @@ static float rand_float( void ) {
 * @param len          array length
 * @return             elapsed time in seconds
 */
-static double benchmark( int iterations, int len ) {
+static double benchmark1( int iterations, int len ) {
 	double elapsed;
 	float x[ len ];
 	double t;
@@ -105,7 +105,40 @@ static double benchmark( int iterations, int len ) {
 	}
 	t = tic();
 	for ( i = 0; i < iterations; i++ ) {
-		c_sapx( len, 5.0f, x, 1 );
+		// cppcheck-suppress uninitvar
+		stdlib_strided_sapx( len, 5.0f, x, 1 );
+		if ( x[ 0 ] != x[ 0 ] ) {
+			printf( "should not return NaN\n" );
+			break;
+		}
+	}
+	elapsed = tic() - t;
+	if ( x[ 0 ] != x[ 0 ] ) {
+		printf( "should not return NaN\n" );
+	}
+	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 ) {
+	double elapsed;
+	float x[ len ];
+	double t;
+	int i;
+
+	for ( i = 0; i < len; i++ ) {
+		x[ i ] = ( rand_float()*200.0f ) - 100.0f;
+	}
+	t = tic();
+	for ( i = 0; i < iterations; i++ ) {
+		// cppcheck-suppress uninitvar
+		stdlib_strided_sapx_ndarray( len, 5.0f, x, 1, 0 );
 		if ( x[ 0 ] != x[ 0 ] ) {
 			printf( "should not return NaN\n" );
 			break;
@@ -140,7 +173,18 @@ 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 ( i = MIN; i <= MAX; i++ ) {
+		len = pow( 10, i );
+		iter = ITERATIONS / pow( 10, i-1 );
+		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 );
 		}