README.md (5934B)
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 # dcusumkbn 22 23 > Calculate the cumulative sum of double-precision floating-point strided array elements using an improved Kahan–Babuška algorithm. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var dcusumkbn = require( '@stdlib/blas/ext/base/dcusumkbn' ); 37 ``` 38 39 #### dcusumkbn( N, sum, x, strideX, y, strideY ) 40 41 Computes the cumulative sum of double-precision floating-point strided array elements using an improved Kahan–Babuška algorithm. 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 dcusumkbn( 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 dcusumkbn( 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 = dcusumkbn( 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 dcusumkbn( 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 #### dcusumkbn.ndarray( N, sum, x, strideX, offsetX, y, strideY, offsetY ) 106 107 Computes the cumulative sum of double-precision floating-point strided array elements using an improved Kahan–Babuška algorithm 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 dcusumkbn.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 dcusumkbn.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 149 </section> 150 151 <!-- /.notes --> 152 153 <section class="examples"> 154 155 ## Examples 156 157 <!-- eslint no-undef: "error" --> 158 159 ```javascript 160 var randu = require( '@stdlib/random/base/randu' ); 161 var round = require( '@stdlib/math/base/special/round' ); 162 var Float64Array = require( '@stdlib/array/float64' ); 163 var dcusumkbn = require( '@stdlib/blas/ext/base/dcusumkbn' ); 164 165 var y; 166 var x; 167 var i; 168 169 x = new Float64Array( 10 ); 170 y = new Float64Array( x.length ); 171 for ( i = 0; i < x.length; i++ ) { 172 x[ i ] = round( randu()*100.0 ); 173 } 174 console.log( x ); 175 console.log( y ); 176 177 dcusumkbn( x.length, 0.0, x, 1, y, -1 ); 178 console.log( y ); 179 ``` 180 181 </section> 182 183 <!-- /.examples --> 184 185 * * * 186 187 <section class="references"> 188 189 ## References 190 191 - Neumaier, Arnold. 1974. "Rounding Error Analysis of Some Methods for Summing Finite Sums." _Zeitschrift Für Angewandte Mathematik Und Mechanik_ 54 (1): 39–51. doi:[10.1002/zamm.19740540106][@neumaier:1974a]. 192 193 </section> 194 195 <!-- /.references --> 196 197 <section class="links"> 198 199 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64 200 201 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 202 203 [@neumaier:1974a]: https://doi.org/10.1002/zamm.19740540106 204 205 </section> 206 207 <!-- /.links -->