README.md (5284B)
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 # gnannsumkbn 22 23 > Calculate the sum of strided array elements, ignoring `NaN` values and 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 gnannsumkbn = require( '@stdlib/blas/ext/base/gnannsumkbn' ); 37 ``` 38 39 #### gnannsumkbn( N, x, strideX, out, strideOut ) 40 41 Computes the sum of strided array elements, ignoring `NaN` values and using an improved Kahan–Babuška algorithm. 42 43 ```javascript 44 var x = [ 1.0, -2.0, NaN, 2.0 ]; 45 var out = [ 0.0, 0 ]; 46 47 var v = gnannsumkbn( x.length, x, 1, out, 1 ); 48 // returns [ 1.0, 3 ] 49 ``` 50 51 The function has the following parameters: 52 53 - **N**: number of indexed elements. 54 - **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array]. 55 - **strideX**: index increment for `x`. 56 - **out**: output [`Array`][mdn-array] or [`typed array`][mdn-typed-array] whose first element is the sum and whose second element is the number of non-NaN elements. 57 - **strideOut**: index increment for `out`. 58 59 The `N` and `stride` parameters determine which elements are accessed at runtime. For example, to compute the sum of every other element in `x`, 60 61 ```javascript 62 var floor = require( '@stdlib/math/base/special/floor' ); 63 64 var x = [ 1.0, 2.0, NaN, -7.0, NaN, 3.0, 4.0, 2.0 ]; 65 var out = [ 0.0, 0 ]; 66 var N = floor( x.length / 2 ); 67 68 var v = gnannsumkbn( N, x, 2, out, 1 ); 69 // returns [ 5.0, 2 ] 70 ``` 71 72 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 73 74 <!-- eslint-disable stdlib/capitalized-comments --> 75 76 ```javascript 77 var Float64Array = require( '@stdlib/array/float64' ); 78 var floor = require( '@stdlib/math/base/special/floor' ); 79 80 var x0 = new Float64Array( [ 2.0, 1.0, NaN, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 81 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 82 83 var out0 = new Float64Array( 4 ); 84 var out1 = new Float64Array( out0.buffer, out0.BYTES_PER_ELEMENT*2 ); // start at 3rd element 85 86 var N = floor( x0.length / 2 ); 87 88 var v = gnannsumkbn( N, x1, 2, out1, 1 ); 89 // returns <Float64Array>[ 5.0, 4 ] 90 ``` 91 92 #### gnannsumkbn.ndarray( N, x, strideX, offsetX, out, strideOut, offsetOut ) 93 94 Computes the sum of strided array elements, ignoring `NaN` values and using an improved Kahan–Babuška algorithm and alternative indexing semantics. 95 96 ```javascript 97 var x = [ 1.0, -2.0, NaN, 2.0 ]; 98 var out = [ 0.0, 0 ]; 99 100 var v = gnannsumkbn.ndarray( x.length, x, 1, 0, out, 1, 0 ); 101 // returns [ 1.0, 3 ] 102 ``` 103 104 The function has the following additional parameters: 105 106 - **offsetX**: starting index for `x`. 107 - **offsetOut**: starting index for `out`. 108 109 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other value in `x` starting from the second value 110 111 ```javascript 112 var floor = require( '@stdlib/math/base/special/floor' ); 113 114 var x = [ 2.0, 1.0, NaN, -2.0, -2.0, 2.0, 3.0, 4.0 ]; 115 var out = [ 0.0, 0.0, 0.0, 0 ]; 116 var N = floor( x.length / 2 ); 117 118 var v = gnannsumkbn.ndarray( N, x, 2, 1, out, 2, 1 ); 119 // returns <Float64Array>[ 0.0, 5.0, 0.0, 4 ] 120 ``` 121 122 </section> 123 124 <!-- /.usage --> 125 126 <section class="notes"> 127 128 ## Notes 129 130 - If `N <= 0`, both functions return a sum equal to `0.0`. 131 132 </section> 133 134 <!-- /.notes --> 135 136 <section class="examples"> 137 138 ## Examples 139 140 <!-- eslint no-undef: "error" --> 141 142 ```javascript 143 var randu = require( '@stdlib/random/base/randu' ); 144 var round = require( '@stdlib/math/base/special/round' ); 145 var Float64Array = require( '@stdlib/array/float64' ); 146 var gnannsumkbn = require( '@stdlib/blas/ext/base/gnannsumkbn' ); 147 148 var x; 149 var i; 150 151 x = new Float64Array( 10 ); 152 for ( i = 0; i < x.length; i++ ) { 153 if ( randu() < 0.2 ) { 154 x[ i ] = NaN; 155 } else { 156 x[ i ] = round( randu()*100.0 ); 157 } 158 } 159 console.log( x ); 160 161 var out = new Float64Array( 2 ); 162 gnannsumkbn( x.length, x, 1, out, 1 ); 163 console.log( out ); 164 ``` 165 166 </section> 167 168 <!-- /.examples --> 169 170 * * * 171 172 <section class="references"> 173 174 ## References 175 176 - 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]. 177 178 </section> 179 180 <!-- /.references --> 181 182 <section class="links"> 183 184 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 185 186 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 187 188 [@neumaier:1974a]: https://doi.org/10.1002/zamm.19740540106 189 190 </section> 191 192 <!-- /.links -->