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