README.md (5674B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # daxpy 22 23 > Multiply a vector `x` by a constant `alpha` and add the result to `y`. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var daxpy = require( '@stdlib/blas/base/daxpy' ); 31 ``` 32 33 #### daxpy( N, alpha, x, strideX, y, strideY ) 34 35 Multiplies a vector `x` by a constant `alpha` and adds the result to `y`. 36 37 ```javascript 38 var Float64Array = require( '@stdlib/array/float64' ); 39 40 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 41 var y = new Float64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] ); 42 var alpha = 5.0; 43 44 daxpy( x.length, alpha, x, 1, y, 1 ); 45 // y => <Float64Array>[ 6.0, 11.0, 16.0, 21.0, 26.0 ] 46 ``` 47 48 The function has the following parameters: 49 50 - **N**: number of indexed elements. 51 - **alpha**: `numeric` constant. 52 - **x**: input [`Float64Array`][mdn-float64array]. 53 - **strideX**: index increment for `x`. 54 - **y**: input [`Float64Array`][mdn-float64array]. 55 - **strideY**: index increment for `y`. 56 57 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to multiply every other value in `x` by `alpha` and add the result to the first `N` elements of `y` in reverse order, 58 59 ```javascript 60 var Float64Array = require( '@stdlib/array/float64' ); 61 var floor = require( '@stdlib/math/base/special/floor' ); 62 63 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 64 var y = new Float64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] ); 65 66 var alpha = 5.0; 67 var N = floor( x.length / 2 ); 68 69 daxpy( N, alpha, x, 2, y, -1 ); 70 // y => <Float64Array>[ 26.0, 16.0, 6.0, 1.0, 1.0, 1.0 ] 71 ``` 72 73 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 74 75 <!-- eslint-disable stdlib/capitalized-comments --> 76 77 ```javascript 78 var Float64Array = require( '@stdlib/array/float64' ); 79 var floor = require( '@stdlib/math/base/special/floor' ); 80 81 // Initial arrays... 82 var x0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 83 var y0 = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); 84 85 // Create offset views... 86 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 87 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 88 89 var N = floor( x0.length / 2 ); 90 91 daxpy( N, 5.0, x1, -2, y1, 1 ); 92 // y0 => <Float64Array>[ 7.0, 8.0, 9.0, 40.0, 31.0, 22.0 ] 93 ``` 94 95 #### daxpy.ndarray( N, alpha, x, strideX, offsetX, y, strideY, offsetY ) 96 97 Multiplies a vector `x` by a constant `alpha` and adds the result to `y` using alternative indexing semantics. 98 99 ```javascript 100 var Float64Array = require( '@stdlib/array/float64' ); 101 102 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 103 var y = new Float64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] ); 104 var alpha = 5.0; 105 106 daxpy.ndarray( x.length, alpha, x, 1, 0, y, 1, 0 ); 107 // y => <Float64Array>[ 6.0, 11.0, 16.0, 21.0, 26.0 ] 108 ``` 109 110 The function has the following additional parameters: 111 112 - **offsetX**: starting index for `x`. 113 - **offsetY**: starting index for `y`. 114 115 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to multiply every other value in `x` by a constant `alpha` starting from the second value and add to the last `N` elements in `y` where `x[i] -> y[n]`, `x[i+2] -> y[n-1]`,..., 116 117 ```javascript 118 var Float64Array = require( '@stdlib/array/float64' ); 119 var floor = require( '@stdlib/math/base/special/floor' ); 120 121 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 122 var y = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); 123 124 var alpha = 5.0; 125 var N = floor( x.length / 2 ); 126 127 daxpy.ndarray( N, alpha, x, 2, 1, y, -1, y.length-1 ); 128 // y => <Float64Array>[ 7.0, 8.0, 9.0, 40.0, 31.0, 22.0 ] 129 ``` 130 131 </section> 132 133 <!-- /.usage --> 134 135 <section class="notes"> 136 137 ## Notes 138 139 - If `N <= 0` or `alpha == 0`, both functions return `y` unchanged. 140 - `daxpy()` corresponds to the [BLAS][blas] level 1 function [`daxpy`][daxpy]. 141 142 </section> 143 144 <!-- /.notes --> 145 146 <section class="examples"> 147 148 ## Examples 149 150 <!-- eslint no-undef: "error" --> 151 152 ```javascript 153 var randu = require( '@stdlib/random/base/randu' ); 154 var round = require( '@stdlib/math/base/special/round' ); 155 var Float64Array = require( '@stdlib/array/float64' ); 156 var daxpy = require( '@stdlib/blas/base/daxpy' ); 157 158 var x; 159 var y; 160 var i; 161 162 x = new Float64Array( 10 ); 163 y = new Float64Array( 10 ); 164 for ( i = 0; i < x.length; i++ ) { 165 x[ i ] = round( randu() * 100.0 ); 166 y[ i ] = round( randu() * 10.0 ); 167 } 168 console.log( x ); 169 console.log( y ); 170 171 daxpy.ndarray( x.length, 5.0, x, 1, 0, y, -1, y.length-1 ); 172 console.log( y ); 173 ``` 174 175 </section> 176 177 <!-- /.examples --> 178 179 <section class="links"> 180 181 [blas]: http://www.netlib.org/blas 182 183 [daxpy]: http://www.netlib.org/lapack/explore-html/de/da4/group__double__blas__level1.html 184 185 [mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array 186 187 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 188 189 </section> 190 191 <!-- /.links -->