Skip to content

Commit 553b27c

Browse files
MeKaustubh07kgryte
MeKaustubh07
and
kgryte
authored
feat: add blas/ext/base/ndarray/gsumpw
PR-URL: #9080 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 95c53cf commit 553b27c

File tree

10 files changed

+729
-0
lines changed

10 files changed

+729
-0
lines changed

‎lib/node_modules/@stdlib/blas/ext/base/ndarray/gsumpw/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# gsumpw
22+
23+
> Compute the sum of all elements in a one-dimensional ndarray using pairwise summation.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var gsumpw = require( '@stdlib/blas/ext/base/ndarray/gsumpw' );
37+
```
38+
39+
#### gsumpw( arrays )
40+
41+
Computes the sum of all elements in a one-dimensional ndarray using pairwise summation.
42+
43+
```javascript
44+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
45+
46+
var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
47+
var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
48+
49+
var v = gsumpw( [ x ] );
50+
// returns 10.0
51+
```
52+
53+
The function has the following parameters:
54+
55+
- **arrays**: array-like object containing a one-dimensional input ndarray.
56+
57+
</section>
58+
59+
<!-- /.usage -->
60+
61+
<section class="notes">
62+
63+
## Notes
64+
65+
- If provided an empty real-valued one-dimensional ndarray, the function returns `0.0`.
66+
- In general, pairwise summation is more numerically stable than ordinary recursive summation (i.e., "simple" summation), with slightly worse performance. While not the most numerically stable summation technique (e.g., compensated summation techniques such as the Kahan–Babuška-Neumaier algorithm are generally more numerically stable), pairwise summation strikes a reasonable balance between numerical stability and performance. If either numerical stability or performance is more desirable for your use case, consider alternative summation techniques.
67+
68+
</section>
69+
70+
<!-- /.notes -->
71+
72+
<section class="examples">
73+
74+
## Examples
75+
76+
<!-- eslint no-undef: "error" -->
77+
78+
```javascript
79+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
80+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
81+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
82+
var gsumpw = require( '@stdlib/blas/ext/base/ndarray/gsumpw' );
83+
84+
var xbuf = discreteUniform( 10, -50, 50, {
85+
'dtype': 'generic'
86+
});
87+
var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
88+
console.log( ndarray2array( x ) );
89+
90+
var v = gsumpw( [ x ] );
91+
console.log( v );
92+
```
93+
94+
</section>
95+
96+
<!-- /.examples -->
97+
98+
<section class="references">
99+
100+
- Higham, Nicholas J. 1993. "The Accuracy of Floating Point Summation." _SIAM Journal on Scientific Computing_ 14 (4): 783–99. doi:[10.1137/0914050][@higham:1993a].
101+
102+
</section>
103+
104+
<!-- /.references -->
105+
106+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
107+
108+
<section class="related">
109+
110+
</section>
111+
112+
<!-- /.related -->
113+
114+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
115+
116+
<section class="links">
117+
118+
[@higham:1993a]: https://doi.org/10.1137/0914050
119+
120+
</section>
121+
122+
<!-- /.links -->

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
25+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
26+
var pow = require( '@stdlib/math/base/special/pow' );
27+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
28+
var pkg = require( './../package.json' ).name;
29+
var gsumpw = require( './../lib' );
30+
31+
32+
// VARIABLES //
33+
34+
var options = {
35+
'dtype': 'generic'
36+
};
37+
38+
39+
// FUNCTIONS //
40+
41+
/**
42+
* Creates a benchmark function.
43+
*
44+
* @private
45+
* @param {PositiveInteger} len - array length
46+
* @returns {Function} benchmark function
47+
*/
48+
function createBenchmark( len ) {
49+
var xbuf;
50+
var x;
51+
52+
xbuf = uniform( len, -10.0, 10.0, options );
53+
x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
54+
55+
return benchmark;
56+
57+
function benchmark( b ) {
58+
var v;
59+
var i;
60+
61+
b.tic();
62+
for ( i = 0; i < b.iterations; i++ ) {
63+
v = gsumpw( [ x ] );
64+
if ( isnan( v ) ) {
65+
b.fail( 'should not return NaN' );
66+
}
67+
}
68+
b.toc();
69+
if ( isnan( v ) ) {
70+
b.fail( 'should not return NaN' );
71+
}
72+
b.pass( 'benchmark finished' );
73+
b.end();
74+
}
75+
}
76+
77+
78+
// MAIN //
79+
80+
/**
81+
* Main execution sequence.
82+
*
83+
* @private
84+
*/
85+
function main() {
86+
var len;
87+
var min;
88+
var max;
89+
var f;
90+
var i;
91+
92+
min = 1; // 10^min
93+
max = 6; // 10^max
94+
95+
for ( i = min; i <= max; i++ ) {
96+
len = pow( 10, i );
97+
f = createBenchmark( len );
98+
bench( pkg+':len='+len, f );
99+
}
100+
}
101+
102+
main();

‎lib/node_modules/@stdlib/blas/ext/base/ndarray/gsumpw/docs/repl.txt‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
{{alias}}( arrays )
3+
Computes the sum of all elements in a one-dimensional ndarray using pairwise
4+
summation.
5+
6+
If provided an empty ndarray, the function returns `0.0`.
7+
8+
Parameters
9+
----------
10+
arrays: ArrayLikeObject<ndarray>
11+
Array-like object containing a one-dimensional input ndarray.
12+
13+
Returns
14+
-------
15+
out: number
16+
Sum.
17+
18+
Examples
19+
--------
20+
> var xbuf = [ 1.0, 2.0, 3.0 ];
21+
> var dt = 'generic';
22+
> var sh = [ xbuf.length ];
23+
> var sx = [ 1 ];
24+
> var ox = 0;
25+
> var ord = 'row-major';
26+
> var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, ox, ord );
27+
> {{alias}}( [ x ] )
28+
6.0
29+
30+
See Also
31+
--------
32+

‎lib/node_modules/@stdlib/blas/ext/base/ndarray/gsumpw/docs/types/index.d.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { typedndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Computes the sum of all elements in a one-dimensional ndarray using pairwise summation.
27+
*
28+
* @param arrays - array-like object containing an input ndarray
29+
* @returns sum
30+
*
31+
* @example
32+
* var ndarray = require( '@stdlib/ndarray/base/ctor' );
33+
*
34+
* var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
35+
* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
36+
*
37+
* var v = gsumpw( [ x ] );
38+
* // returns 10.0
39+
*/
40+
declare function gsumpw<T extends typedndarray<number> = typedndarray<number>>( arrays: [ T ] ): number;
41+
42+
43+
// EXPORTS //
44+
45+
export = gsumpw;

‎lib/node_modules/@stdlib/blas/ext/base/ndarray/gsumpw/docs/types/test.ts‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
/* eslint-disable space-in-parens */
20+
21+
import zeros = require( '@stdlib/ndarray/zeros' );
22+
import gsumpw = require( './index' );
23+
24+
25+
// TESTS //
26+
27+
// The function returns a sum...
28+
{
29+
const x = zeros( [ 10 ], {
30+
'dtype': 'float64'
31+
});
32+
33+
gsumpw( [ x ] ); // $ExpectType number
34+
}
35+
36+
// The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
37+
{
38+
gsumpw( '10' ); // $ExpectError
39+
gsumpw( 10 ); // $ExpectError
40+
gsumpw( true ); // $ExpectError
41+
gsumpw( false ); // $ExpectError
42+
gsumpw( null ); // $ExpectError
43+
gsumpw( undefined ); // $ExpectError
44+
gsumpw( [] ); // $ExpectError
45+
gsumpw( {} ); // $ExpectError
46+
gsumpw( ( x: number ): number => x ); // $ExpectError
47+
}
48+
49+
// The compiler throws an error if the function is provided an unsupported number of arguments...
50+
{
51+
const x = zeros( [ 10 ], {
52+
'dtype': 'float64'
53+
});
54+
55+
gsumpw(); // $ExpectError
56+
gsumpw( [ x ], {} ); // $ExpectError
57+
}

‎lib/node_modules/@stdlib/blas/ext/base/ndarray/gsumpw/examples/index.js‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
22+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
23+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
24+
var gsumpw = require( './../lib' );
25+
26+
var xbuf = discreteUniform( 10, -50, 50, {
27+
'dtype': 'generic'
28+
});
29+
var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
30+
console.log( ndarray2array( x ) );
31+
32+
var v = gsumpw( [ x ] );
33+
console.log( v );

0 commit comments

Comments
 (0)