Skip to content

Commit

Permalink
feat: add C ndarray API and refactor blas/ext/base/dsumpw
Browse files Browse the repository at this point in the history 
PR-URL: #4329
Reviewed-by: Athan Reines <[email protected]>
  • Loading branch information
@headlessNode
headlessNode authored Jan 8, 2025
1 parent 4fae05a commit 074b9a1
Show file tree
Hide file tree
Showing 23 changed files with 372 additions and 206 deletions.
140 changes: 127 additions & 13 deletions lib/node_modules/@stdlib/blas/ext/base/dsumpw/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,27 +36,26 @@ limitations under the License.
var dsumpw = require( '@stdlib/blas/ext/base/dsumpw' );
```

#### dsumpw( N, x, stride )
#### dsumpw( N, x, strideX )

Computes the sum of double-precision floating-point strided array elements using pairwise summation.

```javascript
var Float64Array = require( '@stdlib/array/float64' );

var x = new Float64Array( [ 1.0, -2.0, 2.0 ] );
var N = x.length;

var v = dsumpw( N, x, 1 );
var v = dsumpw( x.length, x, 1 );
// returns 1.0
```

The function has the following parameters:

- **N**: number of indexed elements.
- **x**: input [`Float64Array`][@stdlib/array/float64].
- **stride**: index increment for `x`.
- **strideX**: stride length for `x`.

The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element in `x`,
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element:

```javascript
var Float64Array = require( '@stdlib/array/float64' );
Expand All @@ -81,25 +80,24 @@ var v = dsumpw( 4, x1, 2 );
// returns 5.0
```

#### dsumpw.ndarray( N, x, stride, offset )
#### dsumpw.ndarray( N, x, strideX, offsetX )

Computes the sum of double-precision floating-point strided array elements using pairwise summation and alternative indexing semantics.

```javascript
var Float64Array = require( '@stdlib/array/float64' );

var x = new Float64Array( [ 1.0, -2.0, 2.0 ] );
var N = x.length;

var v = dsumpw.ndarray( N, x, 1, 0 );
var v = dsumpw.ndarray( x.length, x, 1, 0 );
// returns 1.0
```

The function has the following additional parameters:

- **offset**: starting index for `x`.
- **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 calculate the sum of every other value in `x` starting from the second value
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 calculate the sum of every other element starting from the second element:

```javascript
var Float64Array = require( '@stdlib/array/float64' );
Expand Down Expand Up @@ -132,11 +130,12 @@ var v = dsumpw.ndarray( 4, x, 2, 1 );
<!-- eslint no-undef: "error" -->

```javascript
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
var filledarrayBy = require( '@stdlib/array/filled-by' );
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var dsumpw = require( '@stdlib/blas/ext/base/dsumpw' );

var x = filledarrayBy( 10, 'float64', discreteUniform( 0, 100 ) );
var x = discreteUniform( 10, -100, 100, {
'dtype': 'float64'
});
console.log( x );

var v = dsumpw( x.length, x, 1 );
Expand All @@ -147,8 +146,123 @@ console.log( v );

<!-- /.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/dsumpw.h"
```

#### stdlib_strided_dsumpw( N, \*X, strideX )

Computes the sum of double-precision floating-point strided array elements using pairwise summation.

```c
const double x[] = { 1.0, 2.0, 3.0, 4.0 };

double v = stdlib_strided_dsumpw( 4, x, 1 );
// returns 10.0
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **X**: `[in] double*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
```c
double stdlib_strided_dsumpw( const CBLAS_INT N, const double *X, const CBLAS_INT strideX );
```

#### stdlib_strided_dsumpw_ndarray( N, \*X, strideX, offsetX )

Computes the sum of double-precision floating-point strided array elements using pairwise summation and alternative indexing semantics.

```c
const double x[] = { 1.0, 2.0, 3.0, 4.0 };

double v = stdlib_strided_dsumpw_ndarray( 4, x, 1, 0 );
// returns 10.0
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **X**: `[in] double*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
```c
double stdlib_strided_dsumpw_ndarray( const CBLAS_INT N, const double *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/dsumpw.h"
#include <stdio.h>

int main( void ) {
// Create a strided array:
const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };

// Specify the number of elements:
const int N = 4;

// Specify the stride length:
const int strideX = 2;

// Compute the sum:
double v = stdlib_strided_dsumpw( N, x, strideX );

// Print the result:
printf( "sum: %lf\n", v );
}
```
</section>
<!-- /.examples -->
</section>
<!-- /.c -->
<section class="references">
## References
Expand Down
9 changes: 5 additions & 4 deletions lib/node_modules/@stdlib/blas/ext/base/dsumpw/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 dsumpw = require( './../lib/dsumpw.js' );

// VARIABLES //

var rand = uniform( -10.0, 10.0 );
var options = {
'dtype': 'float64'
};


// FUNCTIONS //
Expand All @@ -44,7 +45,7 @@ var rand = uniform( -10.0, 10.0 );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', 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/dsumpw/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 dsumpw = tryRequire( resolve( __dirname, './../lib/dsumpw.native.js' ) );
var opts = {
'skip': ( dsumpw instanceof Error )
};
var rand = uniform( -10.0, 10.0 );
var options = {
'dtype': 'float64'
};


// FUNCTIONS //
Expand All @@ -49,7 +50,7 @@ var rand = uniform( -10.0, 10.0 );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', 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/dsumpw/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 dsumpw = require( './../lib/ndarray.js' );

// VARIABLES //

var rand = uniform( -10.0, 10.0 );
var options = {
'dtype': 'float64'
};


// FUNCTIONS //
Expand All @@ -44,7 +45,7 @@ var rand = uniform( -10.0, 10.0 );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', 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/dsumpw/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 dsumpw = tryRequire( resolve( __dirname, './../lib/ndarray.native.js' ) );
var opts = {
'skip': ( dsumpw instanceof Error )
};
var rand = uniform( -10.0, 10.0 );
var options = {
'dtype': 'float64'
};


// FUNCTIONS //
Expand All @@ -49,7 +50,7 @@ var rand = uniform( -10.0, 10.0 );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', rand );
var x = uniform( len, -100, 100, options );
return benchmark;

function benchmark( b ) {
Expand Down
50 changes: 48 additions & 2 deletions lib/node_modules/@stdlib/blas/ext/base/dsumpw/benchmark/c/benchmark.length.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,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 ) {
double elapsed;
double x[ len ];
double v;
Expand All @@ -107,6 +107,7 @@ static double benchmark( int iterations, int len ) {
v = 0.0;
t = tic();
for ( i = 0; i < iterations; i++ ) {
// cppcheck-suppress uninitvar
v = stdlib_strided_dsumpw( len, x, 1 );
if ( v != v ) {
printf( "should not return NaN\n" );
Expand All @@ -120,6 +121,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 ) {
double elapsed;
double x[ len ];
double v;
double t;
int i;

for ( i = 0; i < len; i++ ) {
x[ i ] = ( rand_double() * 20000.0 ) - 10000.0;
}
v = 0.0;
t = tic();
for ( i = 0; i < iterations; i++ ) {
// cppcheck-suppress uninitvar
v = stdlib_strided_dsumpw_ndarray( len, x, 1, 0 );
if ( v != v ) {
printf( "should not return NaN\n" );
break;
}
}
elapsed = tic() - t;
if ( v != v ) {
printf( "should not return NaN\n" );
}
return elapsed;
}

/**
* Main execution sequence.
*/
Expand All @@ -142,7 +177,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 074b9a1

@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/dsumpw $\color{green}434/434$
$\color{green}+100.00\%$ 		$\color{green}24/24$
$\color{green}+100.00\%$ 		$\color{green}4/4$
$\color{green}+100.00\%$ 		$\color{green}434/434$
$\color{green}+100.00\%$

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

Please sign in to comment.