Skip to content

Commit

Permalink
feat!: add C ndarray API and refactor blas/ext/base/sapx
Browse files Browse the repository at this point in the history 
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: #4696
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]>
  • Loading branch information
@headlessNode @kgryte
headlessNode and kgryte authored Jan 19, 2025
1 parent 036fccd commit 2ea4452
Show file tree
Hide file tree
Showing 21 changed files with 401 additions and 237 deletions.
144 changes: 132 additions & 12 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">

Expand All @@ -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' );
Expand All @@ -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' );
Expand All @@ -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' );
Expand All @@ -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' );
Expand Down Expand Up @@ -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 );
Expand All @@ -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">
Expand Down
9 changes: 5 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -31,7 +30,9 @@ var sapx = require( './../lib/sapx.js' );

// VARIABLES //

var rand = uniform( -100.0, 100.0 );
var options = {
'dtype': 'float32'
};


// FUNCTIONS //
Expand All @@ -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 ) {
Expand Down
9 changes: 5 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.native.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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' );
Expand All @@ -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 //
Expand All @@ -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 ) {
Expand Down
9 changes: 5 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.ndarray.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -31,7 +30,9 @@ var sapx = require( './../lib/ndarray.js' );

// VARIABLES //

var rand = uniform( -100.0, 100.0 );
var options = {
'dtype': 'float32'
};


// FUNCTIONS //
Expand All @@ -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 ) {
Expand Down
9 changes: 5 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/benchmark.ndarray.native.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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' );
Expand All @@ -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 //
Expand All @@ -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 ) {
Expand Down
50 changes: 47 additions & 3 deletions lib/node_modules/@stdlib/blas/ext/base/sapx/benchmark/c/benchmark.length.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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 );
}
Expand Down
Loading

1 comment on commit 2ea4452

@stdlib-bot
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coverage Report

Package Statements Branches Functions Lines
blas/ext/base/sapx $\color{green}388/388$
$\color{green}+100.00\%$ 		$\color{green}26/26$
$\color{green}+100.00\%$ 		$\color{green}4/4$
$\color{green}+100.00\%$ 		$\color{green}388/388$
$\color{green}+100.00\%$

The above coverage report was generated for the changes in this push.

Please sign in to comment.