README.md (6340B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 > Calculate the cumulative sum of strided array elements 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/gcusumpw' ); 37 ``` 38 39 #### gcusumpw( N, sum, x, strideX, y, strideY ) 40 41 Computes the cumulative sum of strided array elements using pairwise summation. 42 43 ```javascript 44 var x = [ 1.0, -2.0, 2.0 ]; 45 var y = [ 0.0, 0.0, 0.0 ]; 46 47 gcusumpw( x.length, 0.0, x, 1, y, 1 ); 48 // y => [ 1.0, -1.0, 1.0 ] 49 50 x = [ 1.0, -2.0, 2.0 ]; 51 y = [ 0.0, 0.0, 0.0 ]; 52 53 gcusumpw( x.length, 10.0, x, 1, y, 1 ); 54 // y => [ 11.0, 9.0, 11.0 ] 55 ``` 56 57 The function has the following parameters: 58 59 - **N**: number of indexed elements. 60 - **sum**: initial sum. 61 - **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array]. 62 - **strideX**: index increment for `x`. 63 - **y**: output [`Array`][mdn-array] or [`typed array`][mdn-typed-array]. 64 - **strideY**: index increment for `y`. 65 66 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to compute the cumulative sum of every other element in `x`, 67 68 ```javascript 69 var floor = require( '@stdlib/math/base/special/floor' ); 70 71 var x = [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ]; 72 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 73 74 var N = floor( x.length / 2 ); 75 76 var v = gcusumpw( N, 0.0, x, 2, y, 1 ); 77 // y => [ 1.0, 3.0, 1.0, 5.0, 0.0, 0.0, 0.0, 0.0 ] 78 ``` 79 80 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 81 82 <!-- eslint-disable stdlib/capitalized-comments --> 83 84 ```javascript 85 var Float64Array = require( '@stdlib/array/float64' ); 86 var floor = require( '@stdlib/math/base/special/floor' ); 87 88 // Initial arrays... 89 var x0 = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 90 var y0 = new Float64Array( x0.length ); 91 92 // Create offset views... 93 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 94 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 95 96 var N = floor( x0.length / 2 ); 97 98 gcusumpw( N, 0.0, x1, -2, y1, 1 ); 99 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 4.0, 6.0, 4.0, 5.0, 0.0 ] 100 ``` 101 102 #### gcusumpw.ndarray( N, sum, x, strideX, offsetX, y, strideY, offsetY ) 103 104 Computes the cumulative sum of strided array elements using pairwise summation and alternative indexing semantics. 105 106 ```javascript 107 var x = [ 1.0, -2.0, 2.0 ]; 108 var y = [ 0.0, 0.0, 0.0 ]; 109 110 gcusumpw.ndarray( x.length, 0.0, x, 1, 0, y, 1, 0 ); 111 // y => [ 1.0, -1.0, 1.0 ] 112 ``` 113 114 The function has the following additional parameters: 115 116 - **offsetX**: starting index for `x`. 117 - **offsetY**: starting index for `y`. 118 119 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, `offsetX` and `offsetY` parameters support indexing semantics based on a starting indices. For example, to calculate the cumulative sum of every other value in `x` starting from the second value and to store in the last `N` elements of `y` starting from the last element 120 121 ```javascript 122 var floor = require( '@stdlib/math/base/special/floor' ); 123 124 var x = [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ]; 125 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 126 127 var N = floor( x.length / 2 ); 128 129 gcusumpw.ndarray( N, 0.0, x, 2, 1, y, -1, y.length-1 ); 130 // y => [ 0.0, 0.0, 0.0, 0.0, 5.0, 1.0, -1.0, 1.0 ] 131 ``` 132 133 </section> 134 135 <!-- /.usage --> 136 137 <section class="notes"> 138 139 ## Notes 140 141 - If `N <= 0`, both functions return `y` unchanged. 142 - 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. 143 - Depending on the environment, the typed versions ([`dcusumpw`][@stdlib/blas/ext/base/dcusumpw], [`scusumpw`][@stdlib/blas/ext/base/scusumpw], etc.) are likely to be significantly more performant. 144 145 </section> 146 147 <!-- /.notes --> 148 149 <section class="examples"> 150 151 ## Examples 152 153 <!-- eslint no-undef: "error" --> 154 155 ```javascript 156 var randu = require( '@stdlib/random/base/randu' ); 157 var round = require( '@stdlib/math/base/special/round' ); 158 var Float64Array = require( '@stdlib/array/float64' ); 159 var gcusumpw = require( '@stdlib/blas/ext/base/gcusumpw' ); 160 161 var y; 162 var x; 163 var i; 164 165 x = new Float64Array( 10 ); 166 y = new Float64Array( x.length ); 167 for ( i = 0; i < x.length; i++ ) { 168 x[ i ] = round( randu()*100.0 ); 169 } 170 console.log( x ); 171 console.log( y ); 172 173 gcusumpw( x.length, 0.0, x, 1, y, -1 ); 174 console.log( y ); 175 ``` 176 177 </section> 178 179 <!-- /.examples --> 180 181 * * * 182 183 <section class="references"> 184 185 ## References 186 187 - 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]. 188 189 </section> 190 191 <!-- /.references --> 192 193 <section class="links"> 194 195 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 196 197 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 198 199 [@stdlib/blas/ext/base/dcusumpw]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/dcusumpw 200 201 [@stdlib/blas/ext/base/scusumpw]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/scusumpw 202 203 [@higham:1993a]: https://doi.org/10.1137/0914050 204 205 </section> 206 207 <!-- /.links -->