Skip to content

Commit

Permalink
feat: add C ndarray API and refactor blas/ext/base/dnansum
Browse files Browse the repository at this point in the history
PR-URL: #3052

Reviewed-by: Philipp Burckhardt <pburckhardt@outlook.com>
  • Loading branch information
headlessNode authored Nov 11, 2024
1 parent d9a93be commit 796d76a
Show file tree
Hide file tree
Showing 23 changed files with 366 additions and 141 deletions.
134 changes: 125 additions & 9 deletions lib/node_modules/@stdlib/blas/ext/base/dnansum/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,27 +36,26 @@ limitations under the License.
var dnansum = require( '@stdlib/blas/ext/base/dnansum' );
```

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

Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values.

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

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

var v = dnansum( N, x, 1 );
var v = dnansum( 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 the strided array,
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 the strided array,

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

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

Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values and using alternative indexing semantics.

Expand All @@ -90,15 +89,15 @@ var Float64Array = require( '@stdlib/array/float64' );

var x = new Float64Array( [ 1.0, -2.0, NaN, 2.0 ] );

var v = dnansum.ndarray( 4, x, 1, 0 );
var v = dnansum.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 the strided array 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 @@ -154,6 +153,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/dnansum.h"
```

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

Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values.

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

double v = stdlib_strided_dnansum( 4, x, 1 );
// returns 7.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_dnansum( const CBLAS_INT N, const double *X, const CBLAS_INT strideX );
```

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

Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values and using alternative indexing semantics.

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

double v = stdlib_strided_dnansum_ndarray( 4, x, 1, 0 );
// returns 7.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_dnansum_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/dnansum.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, 0.0/0.0, 0.0/0.0 };

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

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

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

// Print the result:
printf( "sum: %lf\n", v );
}
```
</section>
<!-- /.examples -->
</section>
<!-- /.c -->
<section class="references">
</section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,19 @@ var dnansum = require( './../lib/dnansum.js' );

// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10.0, 10.0 );
}
return NaN;
}

/**
* Creates a benchmark function.
*
Expand All @@ -40,16 +53,9 @@ var dnansum = require( './../lib/dnansum.js' );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', clbk );
var x = filledarrayBy( len, 'float64', rand );
return benchmark;

function clbk() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10, 10 );
}
return NaN;
}

function benchmark( b ) {
var v;
var i;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@ var opts = {

// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10.0, 10.0 );
}
return NaN;
}

/**
* Creates a benchmark function.
*
Expand All @@ -49,16 +62,9 @@ var opts = {
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', clbk );
var x = filledarrayBy( len, 'float64', rand );
return benchmark;

function clbk() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10, 10 );
}
return NaN;
}

function benchmark( b ) {
var v;
var i;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,19 @@ var dnansum = require( './../lib/ndarray.js' );

// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10.0, 10.0 );
}
return NaN;
}

/**
* Creates a benchmark function.
*
Expand All @@ -40,16 +53,9 @@ var dnansum = require( './../lib/ndarray.js' );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', clbk );
var x = filledarrayBy( len, 'float64', rand );
return benchmark;

function clbk() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10, 10 );
}
return NaN;
}

function benchmark( b ) {
var v;
var i;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@ var opts = {

// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10.0, 10.0 );
}
return NaN;
}

/**
* Creates a benchmark function.
*
Expand All @@ -49,16 +62,9 @@ var opts = {
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x = filledarrayBy( len, 'float64', clbk );
var x = filledarrayBy( len, 'float64', rand );
return benchmark;

function clbk() {
if ( bernoulli( 0.7 ) > 0 ) {
return discreteUniform( -10, 10 );
}
return NaN;
}

function benchmark( b ) {
var v;
var i;
Expand Down
Loading

1 comment on commit 796d76a

@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/dnansum $\color{green}345/345$
$\color{green}+100.00\%$
$\color{green}13/13$
$\color{green}+100.00\%$
$\color{green}4/4$
$\color{green}+100.00\%$
$\color{green}345/345$
$\color{green}+100.00\%$

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

Please sign in to comment.