README.md (5420B)
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 # gcusum 22 23 > Calculate the cumulative sum of strided array elements. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var gcusum = require( '@stdlib/blas/ext/base/gcusum' ); 37 ``` 38 39 #### gcusum( N, sum, x, strideX, y, strideY ) 40 41 Computes the cumulative sum of strided array elements. 42 43 ```javascript 44 var x = [ 1.0, -2.0, 2.0 ]; 45 var y = [ 0.0, 0.0, 0.0 ]; 46 47 gcusum( 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 gcusum( 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 = gcusum( 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 gcusum( 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 #### gcusum.ndarray( N, sum, x, strideX, offsetX, y, strideY, offsetY ) 103 104 Computes the cumulative sum of strided array elements using 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 gcusum.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 gcusum.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 - Depending on the environment, the typed versions ([`dcusum`][@stdlib/blas/ext/base/dcusum], [`scusum`][@stdlib/blas/ext/base/scusum], etc.) are likely to be significantly more performant. 143 144 </section> 145 146 <!-- /.notes --> 147 148 <section class="examples"> 149 150 ## Examples 151 152 <!-- eslint no-undef: "error" --> 153 154 ```javascript 155 var randu = require( '@stdlib/random/base/randu' ); 156 var round = require( '@stdlib/math/base/special/round' ); 157 var Float64Array = require( '@stdlib/array/float64' ); 158 var gcusum = require( '@stdlib/blas/ext/base/gcusum' ); 159 160 var y; 161 var x; 162 var i; 163 164 x = new Float64Array( 10 ); 165 y = new Float64Array( x.length ); 166 for ( i = 0; i < x.length; i++ ) { 167 x[ i ] = round( randu()*100.0 ); 168 } 169 console.log( x ); 170 console.log( y ); 171 172 gcusum( x.length, 0.0, x, 1, y, -1 ); 173 console.log( y ); 174 ``` 175 176 </section> 177 178 <!-- /.examples --> 179 180 <section class="references"> 181 182 </section> 183 184 <!-- /.references --> 185 186 <section class="links"> 187 188 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 189 190 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 191 192 [@stdlib/blas/ext/base/dcusum]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/dcusum 193 194 [@stdlib/blas/ext/base/scusum]: https://www.npmjs.com/package/@stdlib/blas/tree/main/ext/base/scusum 195 196 </section> 197 198 <!-- /.links -->