Skip to content

Commit e863acf

Browse files
MeKaustubh07MeKaustubh07
committed
feat: add blas/ext/base/ndarray/gcusumpw
1 parent a94a26e commit e863acf

File tree

10 files changed

+972
-0
lines changed

10 files changed

+972
-0
lines changed

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

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
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+
# gcusumpw
22+
23+
> Compute the cumulative sum of 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 gcusumpw = require( '@stdlib/blas/ext/base/ndarray/gcusumpw' );
37+
```
38+
39+
#### gcusumpw( arrays )
40+
41+
Computes the cumulative sum of a one-dimensional ndarray using pairwise summation.
42+
43+
```javascript
44+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
45+
var scalar2ndarray = require( '@stdlib/ndarray/base/from-scalar' );
46+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
47+
48+
var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
49+
var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
50+
51+
var ybuf = [ 0.0, 0.0, 0.0, 0.0 ];
52+
var y = new ndarray( 'generic', ybuf, [ 4 ], [ 1 ], 0, 'row-major' );
53+
54+
var initial = scalar2ndarray( 0.0, 'generic', 'row-major' );
55+
56+
var v = gcusumpw( [ x, y, initial ] );
57+
// returns <ndarray>
58+
59+
var bool = ( v === y );
60+
// returns true
61+
62+
var arr = ndarray2array( v );
63+
// returns [ 1.0, 4.0, 8.0, 10.0 ]
64+
```
65+
66+
The function has the following parameters:
67+
68+
- **arrays**: array-like object containing a one-dimensional input ndarray, a one-dimensional output ndarray, and a zero-dimensional ndarray containing the initial sum.
69+
70+
</section>
71+
72+
<!-- /.usage -->
73+
74+
<section class="notes">
75+
76+
## Notes
77+
78+
- If provided an empty one-dimensional input ndarray, the function returns the output ndarray unchanged.
79+
- 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.
80+
81+
</section>
82+
83+
<!-- /.notes -->
84+
85+
<section class="examples">
86+
87+
## Examples
88+
89+
<!-- eslint no-undef: "error" -->
90+
91+
```javascript
92+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
93+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
94+
var zerosLike = require( '@stdlib/ndarray/zeros-like' );
95+
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
96+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
97+
var gcusumpw = require( '@stdlib/blas/ext/base/ndarray/gcusumpw' );
98+
99+
var xbuf = discreteUniform( 10, -50, 50, {
100+
'dtype': 'generic'
101+
});
102+
var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
103+
console.log( ndarray2array( x ) );
104+
105+
var y = zerosLike( x );
106+
console.log( ndarray2array( y ) );
107+
108+
var initial = scalar2ndarray( 100.0, {
109+
'dtype': 'generic'
110+
});
111+
112+
var v = gcusumpw( [ x, y, initial ] );
113+
console.log( ndarray2array( v ) );
114+
```
115+
116+
</section>
117+
118+
<!-- /.examples -->
119+
120+
<section class="references">
121+
122+
## References
123+
124+
- 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].
125+
126+
</section>
127+
128+
<!-- /.references -->
129+
130+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
131+
132+
<section class="related">
133+
134+
</section>
135+
136+
<!-- /.related -->
137+
138+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
139+
140+
<section class="links">
141+
142+
[@higham:1993a]: https://doi.org/10.1137/0914050
143+
144+
</section>
145+
146+
<!-- /.links -->

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
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 zeros = require( '@stdlib/array/zeros' );
26+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
27+
var pow = require( '@stdlib/math/base/special/pow' );
28+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
29+
var scalar2ndarray = require( '@stdlib/ndarray/base/from-scalar' );
30+
var pkg = require( './../package.json' ).name;
31+
var gcusumpw = require( './../lib' );
32+
33+
34+
// VARIABLES //
35+
36+
var options = {
37+
'dtype': 'generic'
38+
};
39+
40+
41+
// FUNCTIONS //
42+
43+
/**
44+
* Creates a benchmark function.
45+
*
46+
* @private
47+
* @param {PositiveInteger} len - array length
48+
* @returns {Function} benchmark function
49+
*/
50+
function createBenchmark( len ) {
51+
var initial;
52+
var xbuf;
53+
var ybuf;
54+
var x;
55+
var y;
56+
57+
xbuf = uniform( len, -10.0, 10.0, options );
58+
x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
59+
60+
initial = scalar2ndarray( 0.0, options.dtype, 'row-major' );
61+
62+
ybuf = zeros( len, options.dtype );
63+
y = new ndarray( options.dtype, ybuf, [ len ], [ 1 ], 0, 'row-major' );
64+
65+
return benchmark;
66+
67+
function benchmark( b ) {
68+
var v;
69+
var i;
70+
71+
b.tic();
72+
for ( i = 0; i < b.iterations; i++ ) {
73+
v = gcusumpw( [ x, y, initial ] );
74+
if ( typeof v !== 'object' ) {
75+
b.fail( 'should return an ndarray' );
76+
}
77+
}
78+
b.toc();
79+
if ( isnan( v.get( i%len ) ) ) {
80+
b.fail( 'should not return NaN' );
81+
}
82+
b.pass( 'benchmark finished' );
83+
b.end();
84+
}
85+
}
86+
87+
88+
// MAIN //
89+
90+
/**
91+
* Main execution sequence.
92+
*
93+
* @private
94+
*/
95+
function main() {
96+
var len;
97+
var min;
98+
var max;
99+
var f;
100+
var i;
101+
102+
min = 1; // 10^min
103+
max = 6; // 10^max
104+
105+
for ( i = min; i <= max; i++ ) {
106+
len = pow( 10, i );
107+
f = createBenchmark( len );
108+
bench( pkg+':len='+len, f );
109+
}
110+
}
111+
112+
main();

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
2+
{{alias}}( arrays )
3+
Computes the cumulative sum of a one-dimensional ndarray using pairwise
4+
summation.
5+
6+
If provided an empty input ndarray, the function returns the output ndarray
7+
unchanged.
8+
9+
Parameters
10+
----------
11+
arrays: ArrayLikeObject<ndarray>
12+
Array-like object containing a one-dimensional input ndarray, a one-
13+
dimensional output ndarray, and a zero-dimensional ndarray containing
14+
the initial sum.
15+
16+
Returns
17+
-------
18+
out: ndarray
19+
Output ndarray.
20+
21+
Examples
22+
--------
23+
> var xbuf = [ 1.0, -2.0, 2.0 ];
24+
> var ybuf = [ 0.0, 0.0, 0.0 ];
25+
> var dt = 'generic';
26+
> var sh = [ xbuf.length ];
27+
> var st = [ 1 ];
28+
> var oo = 0;
29+
> var ord = 'row-major';
30+
> var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, st, oo, ord );
31+
> var y = new {{alias:@stdlib/ndarray/ctor}}( dt, ybuf, sh, st, oo, ord );
32+
> var s = {{alias:@stdlib/ndarray/from-scalar}}( 0.0, { 'dtype': dt } );
33+
> {{alias}}( [ x, y, s ] );
34+
> {{alias:@stdlib/ndarray/to-array}}( y )
35+
[ 1.0, -1.0, 1.0 ]
36+
37+
See Also
38+
--------
39+

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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 cumulative sum of a one-dimensional ndarray using pairwise summation.
27+
*
28+
* @param arrays - array-like object containing an input ndarray, an output ndarray, and an ndarray containing the initial sum
29+
* @returns output ndarray
30+
*
31+
* @example
32+
* var ndarray2array = require( '@stdlib/ndarray/to-array' );
33+
* var scalar2ndarray = require( '@stdlib/ndarray/base/from-scalar' );
34+
* var ndarray = require( '@stdlib/ndarray/base/ctor' );
35+
*
36+
* var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
37+
* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
38+
*
39+
* var ybuf = [ 0.0, 0.0, 0.0, 0.0 ];
40+
* var y = new ndarray( 'generic', ybuf, [ 4 ], [ 1 ], 0, 'row-major' );
41+
*
42+
* var initial = scalar2ndarray( 0.0, 'generic', 'row-major' );
43+
*
44+
* var v = gcusumpw( [ x, y, initial ] );
45+
* // returns <ndarray>
46+
*
47+
* var bool = ( v === y );
48+
* // returns true
49+
*
50+
* var arr = ndarray2array( v );
51+
* // returns [ 1.0, 4.0, 8.0, 10.0 ]
52+
*/
53+
declare function gcusumpw<T extends typedndarray<number> = typedndarray<number>>( arrays: [ T, T, T ] ): T;
54+
55+
56+
// EXPORTS //
57+
58+
export = gcusumpw;

0 commit comments

Comments
 (0)