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 # dcusumpw 22 23 > Calculate the cumulative sum of double-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 dcusumpw = require( '@stdlib/blas/ext/base/dcusumpw' ); 37 ``` 38 39 #### dcusumpw( N, sum, x, strideX, y, strideY ) 40 41 Computes the cumulative sum of double-precision floating-point strided array elements using pairwise summation. 42 43 ```javascript 44 var Float64Array = require( '@stdlib/array/float64' ); 45 46 var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); 47 var y = new Float64Array( x.length ); 48 49 dcusumpw( x.length, 0.0, x, 1, y, 1 ); 50 // y => <Float64Array>[ 1.0, -1.0, 1.0 ] 51 52 x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); 53 y = new Float64Array( x.length ); 54 55 dcusumpw( x.length, 10.0, x, 1, y, 1 ); 56 // y => <Float64Array>[ 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 [`Float64Array`][@stdlib/array/float64]. 64 - **strideX**: index increment for `x`. 65 - **y**: output [`Float64Array`][@stdlib/array/float64]. 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 Float64Array = require( '@stdlib/array/float64' ); 72 var floor = require( '@stdlib/math/base/special/floor' ); 73 74 var x = new Float64Array( [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ] ); 75 var y = new Float64Array( x.length ); 76 77 var N = floor( x.length / 2 ); 78 79 var v = dcusumpw( N, 0.0, x, 2, y, 1 ); 80 // y => <Float64Array>[ 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 Float64Array = require( '@stdlib/array/float64' ); 89 var floor = require( '@stdlib/math/base/special/floor' ); 90 91 // Initial arrays... 92 var x0 = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 93 var y0 = new Float64Array( x0.length ); 94 95 // Create offset views... 96 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 97 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 98 99 var N = floor( x0.length / 2 ); 100 101 dcusumpw( N, 0.0, x1, -2, y1, 1 ); 102 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 4.0, 6.0, 4.0, 5.0, 0.0 ] 103 ``` 104 105 #### dcusumpw.ndarray( N, sum, x, strideX, offsetX, y, strideY, offsetY ) 106 107 Computes the cumulative sum of double-precision floating-point strided array elements using pairwise summation and alternative indexing semantics. 108 109 ```javascript 110 var Float64Array = require( '@stdlib/array/float64' ); 111 112 var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); 113 var y = new Float64Array( x.length ); 114 115 dcusumpw.ndarray( x.length, 0.0, x, 1, 0, y, 1, 0 ); 116 // y => <Float64Array>[ 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 Float64Array = require( '@stdlib/array/float64' ); 128 var floor = require( '@stdlib/math/base/special/floor' ); 129 130 var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 131 var y = new Float64Array( x.length ); 132 133 var N = floor( x.length / 2 ); 134 135 dcusumpw.ndarray( N, 0.0, x, 2, 1, y, -1, y.length-1 ); 136 // y => <Float64Array>[ 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 Float64Array = require( '@stdlib/array/float64' ); 164 var dcusumpw = require( '@stdlib/blas/ext/base/dcusumpw' ); 165 166 var y; 167 var x; 168 var i; 169 170 x = new Float64Array( 10 ); 171 y = new Float64Array( 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 dcusumpw( 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/float64]: https://www.npmjs.com/package/@stdlib/array-float64 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 -->