Skip to content

Commit 663577c

Browse files
Pranavchikukgryte
Pranavchiku
and
kgryte
authored
refactor: update add-on, examples, benchmarks, and docs
This commit is part of the work discussed in #788 and updates `@stdlib/blas/base/sdot` according to current project conventions, particularly as concerns the native add-on bridge between JavaScript and C. PR-URL: #798 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 5b98beb commit 663577c

22 files changed

+192
-310
lines changed

‎lib/node_modules/@stdlib/blas/base/sdot/README.md

Lines changed: 11 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
@license Apache-2.0
44
5-
Copyright (c) 2019 The Stdlib Authors.
5+
Copyright (c) 2023 The Stdlib Authors.
66
77
Licensed under the Apache License, Version 2.0 (the "License");
88
you may not use this file except in compliance with the License.
@@ -69,18 +69,15 @@ The function has the following parameters:
6969
- **y**: input [`Float32Array`][@stdlib/array/float32].
7070
- **strideY**: index increment for `y`.
7171

72-
The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to calculate the dot product of every other value in `x` and the first `N` elements of `y` in reverse order,
72+
The `N` and stride parameters determine which elements in `x` and `y` are accessed at runtime. For example, to calculate the dot product of every other value in `x` and the first `N` elements of `y` in reverse order,
7373

7474
```javascript
7575
var Float32Array = require( '@stdlib/array/float32' );
76-
var floor = require( '@stdlib/math/base/special/floor' );
7776

7877
var x = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
7978
var y = new Float32Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
8079

81-
var N = floor( x.length / 2 );
82-
83-
var z = sdot( N, x, 2, y, -1 );
80+
var z = sdot( 3, x, 2, y, -1 );
8481
// returns 9.0
8582
```
8683

@@ -90,7 +87,6 @@ Note that indexing is relative to the first index. To introduce an offset, use [
9087

9188
```javascript
9289
var Float32Array = require( '@stdlib/array/float32' );
93-
var floor = require( '@stdlib/math/base/special/floor' );
9490

9591
// Initial arrays...
9692
var x0 = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
@@ -100,9 +96,7 @@ var y0 = new Float32Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
10096
var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
10197
var y1 = new Float32Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element
10298

103-
var N = floor( x0.length / 2 );
104-
105-
var z = sdot( N, x1, -2, y1, 1 );
99+
var z = sdot( 3, x1, -2, y1, 1 );
106100
// returns 128.0
107101
```
108102

@@ -125,18 +119,15 @@ The function has the following additional parameters:
125119
- **offsetX**: starting index for `x`.
126120
- **offsetY**: starting index for `y`.
127121

128-
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to calculate the dot product of every other value in `x` starting from the second value with the last 3 elements in `y` in reverse order
122+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the offset parameters support indexing semantics based on starting indices. For example, to calculate the dot product of every other value in `x` starting from the second value with the last 3 elements in `y` in reverse order
129123

130124
```javascript
131125
var Float32Array = require( '@stdlib/array/float32' );
132-
var floor = require( '@stdlib/math/base/special/floor' );
133126

134127
var x = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
135128
var y = new Float32Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
136129

137-
var N = floor( x.length / 2 );
138-
139-
var z = sdot.ndarray( N, x, 2, 1, y, -1, y.length-1 );
130+
var z = sdot.ndarray( 3, x, 2, 1, y, -1, y.length-1 );
140131
// returns 128.0
141132
```
142133

@@ -162,22 +153,14 @@ var z = sdot.ndarray( N, x, 2, 1, y, -1, y.length-1 );
162153
<!-- eslint no-undef: "error" -->
163154

164155
```javascript
165-
var randu = require( '@stdlib/random/base/randu' );
166-
var round = require( '@stdlib/math/base/special/round' );
167-
var Float32Array = require( '@stdlib/array/float32' );
156+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
157+
var filledarrayBy = require( '@stdlib/array/filled-by' );
168158
var sdot = require( '@stdlib/blas/base/sdot' );
169159

170-
var x;
171-
var y;
172-
var i;
173-
174-
x = new Float32Array( 10 );
175-
y = new Float32Array( 10 );
176-
for ( i = 0; i < x.length; i++ ) {
177-
x[ i ] = round( randu()*100.0 );
178-
y[ i ] = round( randu()*10.0 );
179-
}
160+
var x = filledarrayBy( 10, 'float32', discreteUniform( 0, 100 ) );
180161
console.log( x );
162+
163+
var y = filledarrayBy( x.length, 'float32', discreteUniform( 0, 10 ) );
181164
console.log( y );
182165

183166
var z = sdot( x.length, x, 1, y, -1 );

‎lib/node_modules/@stdlib/blas/base/sdot/benchmark/benchmark.js

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2019 The Stdlib Authors.
4+
* Copyright (c) 2023 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -21,14 +21,19 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/base/uniform' ).factory;
25+
var filledarrayBy = require( '@stdlib/array/filled-by' );
2526
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2627
var pow = require( '@stdlib/math/base/special/pow' );
27-
var Float32Array = require( '@stdlib/array/float32' );
2828
var pkg = require( './../package.json' ).name;
2929
var sdot = require( './../lib/sdot.js' );
3030

3131

32+
// VARIABLES //
33+
34+
var rand = uniform( -100.0, 100.0 );
35+
36+
3237
// FUNCTIONS //
3338

3439
/**
@@ -39,16 +44,8 @@ var sdot = require( './../lib/sdot.js' );
3944
* @returns {Function} benchmark function
4045
*/
4146
function createBenchmark( len ) {
42-
var x;
43-
var y;
44-
var i;
45-
46-
x = new Float32Array( len );
47-
y = new Float32Array( len );
48-
for ( i = 0; i < x.length; i++ ) {
49-
x[ i ] = ( randu()*20.0 ) - 10.0;
50-
y[ i ] = ( randu()*20.0 ) - 10.0;
51-
}
47+
var x = filledarrayBy( len, 'float32', rand );
48+
var y = filledarrayBy( len, 'float32', rand );
5249
return benchmark;
5350

5451
function benchmark( b ) {

‎lib/node_modules/@stdlib/blas/base/sdot/benchmark/benchmark.native.js

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2020 The Stdlib Authors.
4+
* Copyright (c) 2023 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -22,10 +22,10 @@
2222

2323
var resolve = require( 'path' ).resolve;
2424
var bench = require( '@stdlib/bench' );
25-
var randu = require( '@stdlib/random/base/randu' );
25+
var uniform = require( '@stdlib/random/base/uniform' ).factory;
26+
var filledarrayBy = require( '@stdlib/array/filled-by' );
2627
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2728
var pow = require( '@stdlib/math/base/special/pow' );
28-
var Float32Array = require( '@stdlib/array/float32' );
2929
var tryRequire = require( '@stdlib/utils/try-require' );
3030
var pkg = require( './../package.json' ).name;
3131

@@ -36,6 +36,7 @@ var sdot = tryRequire( resolve( __dirname, './../lib/sdot.native.js' ) );
3636
var opts = {
3737
'skip': ( sdot instanceof Error )
3838
};
39+
var rand = uniform( -100.0, 100.0 );
3940

4041

4142
// FUNCTIONS //
@@ -48,16 +49,8 @@ var opts = {
4849
* @returns {Function} benchmark function
4950
*/
5051
function createBenchmark( len ) {
51-
var x;
52-
var y;
53-
var i;
54-
55-
x = new Float32Array( len );
56-
y = new Float32Array( len );
57-
for ( i = 0; i < x.length; i++ ) {
58-
x[ i ] = ( randu()*20.0 ) - 10.0;
59-
y[ i ] = ( randu()*20.0 ) - 10.0;
60-
}
52+
var x = filledarrayBy( len, 'float32', rand );
53+
var y = filledarrayBy( len, 'float32', rand );
6154
return benchmark;
6255

6356
function benchmark( b ) {

‎lib/node_modules/@stdlib/blas/base/sdot/benchmark/benchmark.ndarray.js

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2019 The Stdlib Authors.
4+
* Copyright (c) 2023 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -21,14 +21,19 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/base/uniform' ).factory;
25+
var filledarrayBy = require( '@stdlib/array/filled-by' );
2526
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2627
var pow = require( '@stdlib/math/base/special/pow' );
27-
var Float32Array = require( '@stdlib/array/float32' );
2828
var pkg = require( './../package.json' ).name;
2929
var sdot = require( './../lib/ndarray.js' );
3030

3131

32+
// VARIABLES //
33+
34+
var rand = uniform( -100.0, 100.0 );
35+
36+
3237
// FUNCTIONS //
3338

3439
/**
@@ -39,16 +44,8 @@ var sdot = require( './../lib/ndarray.js' );
3944
* @returns {Function} benchmark function
4045
*/
4146
function createBenchmark( len ) {
42-
var x;
43-
var y;
44-
var i;
45-
46-
x = new Float32Array( len );
47-
y = new Float32Array( len );
48-
for ( i = 0; i < x.length; i++ ) {
49-
x[ i ] = ( randu()*20.0 ) - 10.0;
50-
y[ i ] = ( randu()*20.0 ) - 10.0;
51-
}
47+
var x = filledarrayBy( len, 'float32', rand );
48+
var y = filledarrayBy( len, 'float32', rand );
5249
return benchmark;
5350

5451
function benchmark( b ) {

‎lib/node_modules/@stdlib/blas/base/sdot/benchmark/benchmark.ndarray.native.js

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @license Apache-2.0
33
*
4-
* Copyright (c) 2020 The Stdlib Authors.
4+
* Copyright (c) 2023 The Stdlib Authors.
55
*
66
* Licensed under the Apache License, Version 2.0 (the "License");
77
* you may not use this file except in compliance with the License.
@@ -22,10 +22,10 @@
2222

2323
var resolve = require( 'path' ).resolve;
2424
var bench = require( '@stdlib/bench' );
25-
var randu = require( '@stdlib/random/base/randu' );
25+
var uniform = require( '@stdlib/random/base/uniform' ).factory;
26+
var filledarrayBy = require( '@stdlib/array/filled-by' );
2627
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2728
var pow = require( '@stdlib/math/base/special/pow' );
28-
var Float32Array = require( '@stdlib/array/float32' );
2929
var tryRequire = require( '@stdlib/utils/try-require' );
3030
var pkg = require( './../package.json' ).name;
3131

@@ -36,6 +36,7 @@ var sdot = tryRequire( resolve( __dirname, './../lib/ndarray.native.js' ) );
3636
var opts = {
3737
'skip': ( sdot instanceof Error )
3838
};
39+
var rand = uniform( -100.0, 100.0 );
3940

4041

4142
// FUNCTIONS //
@@ -48,16 +49,8 @@ var opts = {
4849
* @returns {Function} benchmark function
4950
*/
5051
function createBenchmark( len ) {
51-
var x;
52-
var y;
53-
var i;
54-
55-
x = new Float32Array( len );
56-
y = new Float32Array( len );
57-
for ( i = 0; i < x.length; i++ ) {
58-
x[ i ] = ( randu()*20.0 ) - 10.0;
59-
y[ i ] = ( randu()*20.0 ) - 10.0;
60-
}
52+
var x = filledarrayBy( len, 'float32', rand );
53+
var y = filledarrayBy( len, 'float32', rand );
6154
return benchmark;
6255

6356
function benchmark( b ) {

‎lib/node_modules/@stdlib/blas/base/sdot/docs/repl.txt

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
{{alias}}( N, x, strideX, y, strideY )
33
Computes the dot product of two single-precision floating-point vectors.
44

5-
The `N`, `strideX`, and `strideY` parameters determine which elements in `x`
6-
and `y` are accessed at runtime.
5+
The `N` and stride parameters determine which elements in the strided arrays
6+
are accessed at runtime.
77

88
Indexing is relative to the first index. To introduce an offset, use a typed
99
array view.
@@ -30,7 +30,7 @@
3030
Returns
3131
-------
3232
dot: float
33-
The dot product of `x` and `y`.
33+
The dot product.
3434

3535
Examples
3636
--------
@@ -43,26 +43,24 @@
4343
// Strides:
4444
> x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
4545
> y = new {{alias:@stdlib/array/float32}}( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
46-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
47-
> dot = {{alias}}( N, x, 2, y, -1 )
46+
> dot = {{alias}}( 3, x, 2, y, -1 )
4847
9.0
4948

5049
// Using view offsets:
5150
> x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
5251
> y = new {{alias:@stdlib/array/float32}}( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
5352
> var x1 = new {{alias:@stdlib/array/float32}}( x.buffer, x.BYTES_PER_ELEMENT*1 );
5453
> var y1 = new {{alias:@stdlib/array/float32}}( y.buffer, y.BYTES_PER_ELEMENT*3 );
55-
> N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
56-
> dot = {{alias}}( N, x1, -2, y1, 1 )
54+
> dot = {{alias}}( 3, x1, -2, y1, 1 )
5755
128.0
5856

57+
5958
{{alias}}.ndarray( N, x, strideX, offsetX, y, strideY, offsetY )
6059
Computes the dot product of two single-precision floating-point vectors
6160
using alternative indexing semantics.
6261

6362
While typed array views mandate a view offset based on the underlying
64-
buffer, the `offsetX` and `offsetY` parameters support indexing based on a
65-
starting index.
63+
buffer, the offset parameters support indexing based on a starting index.
6664

6765
Parameters
6866
----------
@@ -90,7 +88,7 @@
9088
Returns
9189
-------
9290
dot: float
93-
The dot product of `x` and `y`.
91+
The dot product.
9492

9593
Examples
9694
--------
@@ -103,15 +101,13 @@
103101
// Strides:
104102
> x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
105103
> y = new {{alias:@stdlib/array/float32}}( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
106-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
107-
> dot = {{alias}}.ndarray( N, x, 2, 0, y, 2, 0 )
104+
> dot = {{alias}}.ndarray( 3, x, 2, 0, y, 2, 0 )
108105
9.0
109106

110107
// Using offset indices:
111108
> x = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
112109
> y = new {{alias:@stdlib/array/float32}}( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
113-
> N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
114-
> dot = {{alias}}.ndarray( N, x, -2, x.length-1, y, 1, 3 )
110+
> dot = {{alias}}.ndarray( 3, x, -2, x.length-1, y, 1, 3 )
115111
128.0
116112

117113
See Also

0 commit comments

Comments
 (0)