README.md (4825B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2019 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 # sscal 22 23 > Multiply a single-precision floating-point vector `x` by a constant `alpha`. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var sscal = require( '@stdlib/blas/base/sscal' ); 31 ``` 32 33 #### sscal( N, alpha, x, stride ) 34 35 Multiplies a single-precision floating-point vector `x` by a constant `alpha`. 36 37 ```javascript 38 var Float32Array = require( '@stdlib/array/float32' ); 39 40 var x = new Float32Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 41 42 sscal( x.length, 5.0, x, 1 ); 43 // x => <Float32Array>[ -10.0, 5.0, 15.0, -25.0, 20.0, 0.0, -5.0, -15.0 ] 44 ``` 45 46 The function has the following parameters: 47 48 - **N**: number of indexed elements. 49 - **alpha**: scalar constant. 50 - **x**: input [`Float32Array`][@stdlib/array/float32]. 51 - **stride**: index increment. 52 53 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to multiply every other value by a constant 54 55 ```javascript 56 var Float32Array = require( '@stdlib/array/float32' ); 57 var floor = require( '@stdlib/math/base/special/floor' ); 58 59 var x = new Float32Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 60 61 var N = floor( x.length / 2 ); 62 63 sscal( N, 5.0, x, 2 ); 64 // x => <Float32Array>[ -10.0, 1.0, 15.0, -5.0, 20.0, 0.0, -5.0, -3.0 ] 65 ``` 66 67 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 68 69 ```javascript 70 var Float32Array = require( '@stdlib/array/float32' ); 71 var floor = require( '@stdlib/math/base/special/floor' ); 72 73 // Initial array... 74 var x0 = new Float32Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); 75 76 // Create an offset view... 77 var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 78 var N = 3; 79 80 // Scale every other value... 81 sscal( N, 5.0, x1, 2 ); 82 // x0 => <Float32Array>[ 1.0, -10.0, 3.0, -20.0, 5.0, -30.0 ] 83 ``` 84 85 If either `N` or `stride` is less than or equal to `0`, the function returns `x` unchanged. 86 87 #### sscal.ndarray( N, alpha, x, stride, offset ) 88 89 Multiplies a single-precision floating-point vector `x` by a constant `alpha` using alternative indexing semantics. 90 91 ```javascript 92 var Float32Array = require( '@stdlib/array/float32' ); 93 94 var x = new Float32Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 95 96 sscal.ndarray( x.length, 5.0, x, 1, 0 ); 97 // x => <Float32Array>[ -10.0, 5.0, 15.0, -25.0, 20.0, 0.0, -5.0, -15.0 ] 98 ``` 99 100 The function has the following additional parameters: 101 102 - **offset**: starting index. 103 104 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 multiply the last three elements of `x` by a constant 105 106 ```javascript 107 var Float32Array = require( '@stdlib/array/float32' ); 108 109 var x = new Float32Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); 110 111 sscal.ndarray( 3, 5.0, x, 1, x.length-3 ); 112 // x => <Float32Array>[ 1.0, -2.0, 3.0, -20.0, 25.0, -30.0 ] 113 ``` 114 115 </section> 116 117 <!-- /.usage --> 118 119 <section class="notes"> 120 121 ## Notes 122 123 - If `N <= 0`, both functions return `x` unchanged. 124 - `sscal()` corresponds to the [BLAS][blas] level 1 function [`sscal`][sscal]. 125 126 </section> 127 128 <!-- /.notes --> 129 130 <section class="examples"> 131 132 ## Examples 133 134 <!-- eslint no-undef: "error" --> 135 136 ```javascript 137 var round = require( '@stdlib/math/base/special/round' ); 138 var randu = require( '@stdlib/random/base/randu' ); 139 var Float32Array = require( '@stdlib/array/float32' ); 140 var sscal = require( '@stdlib/blas/base/sscal' ); 141 142 var rand; 143 var sign; 144 var x; 145 var i; 146 147 x = new Float32Array( 10 ); 148 for ( i = 0; i < x.length; i++ ) { 149 rand = round( randu()*100.0 ); 150 sign = randu(); 151 if ( sign < 0.5 ) { 152 sign = -1.0; 153 } else { 154 sign = 1.0; 155 } 156 x[ i ] = sign * rand; 157 } 158 console.log( x ); 159 160 sscal( x.length, 5.0, x, 1 ); 161 console.log( x ); 162 ``` 163 164 </section> 165 166 <!-- /.examples --> 167 168 <section class="links"> 169 170 [blas]: http://www.netlib.org/blas 171 172 [sscal]: http://www.netlib.org/lapack/explore-html/df/d28/group__single__blas__level1.html 173 174 [@stdlib/array/float32]: https://www.npmjs.com/package/@stdlib/array-float32 175 176 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 177 178 </section> 179 180 <!-- /.links -->