Skip to content

feat: add C ndarray interface and refactor implementation for stats/base/dnanminabs #4238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 25, 2024
Merged

feat: add C ndarray interface and refactor implementation for stats/base/dnanminabs #4238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d5eae50
feat: add C ndarray interface and refactor implementation
aayush0325 Dec 25, 2024
5d05626
refactor: update tests
aayush0325 Dec 25, 2024
d7f2772
refactor: update docs, examples and benchmarks
aayush0325 Dec 25, 2024
01d5280
docs: update README.md
aayush0325 Dec 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 128 additions & 20 deletions lib/node_modules/@stdlib/stats/base/dnanminabs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,36 +36,33 @@ limitations under the License.
var dnanminabs = require( '@stdlib/stats/base/dnanminabs' );
```

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

Computes the minimum absolute value of a double-precision floating-point strided array `x`, 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 = dnanminabs( N, x, 1 );
var v = dnanminabs( 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 `x` are accessed at runtime. For example, to compute the minimum absolute value 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 minimum absolute value of every other element in `x`,

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var floor = require( '@stdlib/math/base/special/floor' );

var x = new Float64Array( [ 1.0, 2.0, -7.0, -2.0, 4.0, 3.0, NaN, NaN ] );
var N = floor( x.length / 2 );

var v = dnanminabs( N, x, 2 );
var v = dnanminabs( 4, x, 2 );
// returns 1.0
```

Expand All @@ -75,45 +72,39 @@ Note that indexing is relative to the first index. To introduce an offset, use [

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var floor = require( '@stdlib/math/base/special/floor' );

var x0 = new Float64Array( [ 2.0, 1.0, -2.0, -2.0, 3.0, 4.0, NaN, NaN ] );
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

var N = floor( x0.length / 2 );

var v = dnanminabs( N, x1, 2 );
var v = dnanminabs( 4, x1, 2 );
// returns 1.0
```

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

Computes the minimum absolute value of a double-precision floating-point strided array, ignoring `NaN` values and using alternative indexing semantics.

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

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

var v = dnanminabs.ndarray( N, x, 1, 0 );
var v = dnanminabs.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 minimum absolute value for 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 minimum absolute value for every other element in `x` starting from the second element

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var floor = require( '@stdlib/math/base/special/floor' );

var x = new Float64Array( [ 2.0, 1.0, -2.0, -2.0, 3.0, 4.0, NaN, NaN ] );
var N = floor( x.length / 2 );

var v = dnanminabs.ndarray( N, x, 2, 1 );
var v = dnanminabs.ndarray( 4, x, 2, 1 );
// returns 1.0
```

Expand Down Expand Up @@ -164,6 +155,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/stats/base/dnanminabs.h"
```

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

Calculate the minimum absolute value of a double-precision floating-point strided array, ignoring `NaN` values.

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

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

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

Computes the minimum absolute value of a double-precision floating-point strided array, 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_dnanminabs_ndarray( 4, x, 1, 0 );
// returns 1.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_dnanminabs_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/stats/base/dnanminabs.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 minimum absolute value:
double v = stdlib_strided_dnanminabs( N, x, strideX );

// Print the result:
printf( "minabs: %lf\n", v );
}
```

</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
54 changes: 52 additions & 2 deletions lib/node_modules/@stdlib/stats/base/dnanminabs/benchmark/c/benchmark.length.c
View file
Open in desktop
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 @@ -111,6 +111,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_dnanminabs( len, x, 1 );
if ( v != v ) {
printf( "should not return NaN\n" );
Expand All @@ -124,6 +125,44 @@ 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++ ) {
if ( rand_double() < 0.2 ) {
x[ i ] = 0.0 / 0.0; // NaN
} else {
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_dnanminabs_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 @@ -146,7 +185,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
32 changes: 14 additions & 18 deletions lib/node_modules/@stdlib/stats/base/dnanminabs/docs/repl.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@

{{alias}}( N, x, stride )
{{alias}}( N, x, strideX )
Computes the minimum absolute value of a double-precision floating-point
strided array, ignoring `NaN` values.

The `N` and `stride` parameters determine which elements in `x` are accessed
at runtime.
The `N` and stride parameters determine which elements in the strided array
are accessed at runtime.

Indexing is relative to the first index. To introduce an offset, use a typed
array view.
Expand All @@ -19,8 +19,8 @@
x: Float64Array
Input array.

stride: integer
Index increment.
strideX: integer
Stride Length.

Returns
-------
Expand All @@ -34,22 +34,19 @@
> {{alias}}( x.length, x, 1 )
1.0

// Using `N` and `stride` parameters:
// Using `N` and stride parameters:
> x = new {{alias:@stdlib/array/float64}}( [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0, NaN ] );
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
> var stride = 2;
> {{alias}}( N, x, stride )
> {{alias}}( 3, x, 2 )
1.0

// Using view offsets:
> var x0 = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0, NaN ] );
> var x1 = new {{alias:@stdlib/array/float64}}( x0.buffer, x0.BYTES_PER_ELEMENT*1 );
> N = {{alias:@stdlib/math/base/special/floor}}( x0.length / 2 );
> stride = 2;
> {{alias}}( N, x1, stride )
> {{alias}}( 3, x1, 2 )
1.0

{{alias}}.ndarray( N, x, stride, offset )

{{alias}}.ndarray( N, x, strideX, offsetX )
Computes the minimum absolute value of a double-precision floating-point
strided array, ignoring `NaN` values and using alternative indexing
semantics.
Expand All @@ -66,10 +63,10 @@
x: Float64Array
Input array.

stride: integer
Index increment.
strideX: integer
Stride Length.

offset: integer
offsetX: integer
Starting index.

Returns
Expand All @@ -86,8 +83,7 @@

// Using offset parameter:
> var x = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0, NaN ] );
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
> {{alias}}.ndarray( N, x, 2, 1 )
> {{alias}}.ndarray( 3, x, 2, 1 )
1.0

See Also
Expand Down
Loading
Loading