README.md (5460B)
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 # scusum 22 23 > Calculate the cumulative sum of single-precision floating-point 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 scusum = require( '@stdlib/blas/ext/base/scusum' ); 37 ``` 38 39 #### scusum( N, sum, x, strideX, y, strideY ) 40 41 Computes the cumulative sum of single-precision floating-point strided array elements. 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 scusum( 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 scusum( 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 = scusum( 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 scusum( 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 #### scusum.ndarray( N, sum, x, strideX, offsetX, y, strideY, offsetY ) 106 107 Computes the cumulative sum of single-precision floating-point strided array elements using 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 scusum.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 scusum.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 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 Float32Array = require( '@stdlib/array/float32' ); 163 var scusum = require( '@stdlib/blas/ext/base/scusum' ); 164 165 var y; 166 var x; 167 var i; 168 169 x = new Float32Array( 10 ); 170 y = new Float32Array( 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 scusum( x.length, 0.0, x, 1, y, -1 ); 178 console.log( y ); 179 ``` 180 181 </section> 182 183 <!-- /.examples --> 184 185 <section class="references"> 186 187 </section> 188 189 <!-- /.references --> 190 191 <section class="links"> 192 193 [@stdlib/array/float32]: https://www.npmjs.com/package/@stdlib/array-float32 194 195 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 196 197 </section> 198 199 <!-- /.links -->