README.md (6001B)
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 # sdot 22 23 > Calculate the dot product of two single-precision floating-point vectors. 24 25 <section class="intro"> 26 27 The [dot product][dot-product] (or scalar product) is defined as 28 29 <!-- <equation class="equation" label="eq:dot_product" align="center" raw="\mathbf{x}\cdot\mathbf{y} = \sum_{i=0}^{N-1} x_i y_i = x_0 y_0 + x_1 y_1 + \ldots + x_{N-1} y_{N-1}" alt="Dot product definition."> --> 30 31 <div class="equation" align="center" data-raw-text="\mathbf{x}\cdot\mathbf{y} = \sum_{i=0}^{N-1} x_i y_i = x_0 y_0 + x_1 y_1 + \ldots + x_{N-1} y_{N-1}" data-equation="eq:dot_product"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@bbd8a9cd5e54e99d210d9bb51a897445752dcc93/lib/node_modules/@stdlib/blas/base/sdot/docs/img/equation_dot_product.svg" alt="Dot product definition."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 </section> 39 40 <!-- /.intro --> 41 42 <section class="usage"> 43 44 ## Usage 45 46 ```javascript 47 var sdot = require( '@stdlib/blas/base/sdot' ); 48 ``` 49 50 #### sdot( N, x, strideX, y, strideY ) 51 52 Calculates the dot product of vectors `x` and `y`. 53 54 ```javascript 55 var Float32Array = require( '@stdlib/array/float32' ); 56 57 var x = new Float32Array( [ 4.0, 2.0, -3.0, 5.0, -1.0 ] ); 58 var y = new Float32Array( [ 2.0, 6.0, -1.0, -4.0, 8.0 ] ); 59 60 var z = sdot( x.length, x, 1, y, 1 ); 61 // returns -5.0 62 ``` 63 64 The function has the following parameters: 65 66 - **N**: number of indexed elements. 67 - **x**: input [`Float32Array`][@stdlib/array/float32]. 68 - **strideX**: index increment for `x`. 69 - **y**: input [`Float32Array`][@stdlib/array/float32]. 70 - **strideY**: index increment for `y`. 71 72 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to calculate the dot product of every other value in `x` and the first `N` elements of `y` in reverse order, 73 74 ```javascript 75 var Float32Array = require( '@stdlib/array/float32' ); 76 var floor = require( '@stdlib/math/base/special/floor' ); 77 78 var x = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 79 var y = new Float32Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] ); 80 81 var N = floor( x.length / 2 ); 82 83 var z = sdot( N, x, 2, y, -1 ); 84 // returns 9.0 85 ``` 86 87 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 88 89 <!-- eslint-disable stdlib/capitalized-comments --> 90 91 ```javascript 92 var Float32Array = require( '@stdlib/array/float32' ); 93 var floor = require( '@stdlib/math/base/special/floor' ); 94 95 // Initial arrays... 96 var x0 = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 97 var y0 = new Float32Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); 98 99 // Create offset views... 100 var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 101 var y1 = new Float32Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 102 103 var N = floor( x0.length / 2 ); 104 105 var z = sdot( N, x1, -2, y1, 1 ); 106 // returns 128.0 107 ``` 108 109 #### sdot.ndarray( N, x, strideX, offsetX, y, strideY, offsetY ) 110 111 Calculates the dot product of `x` and `y` using alternative indexing semantics. 112 113 ```javascript 114 var Float32Array = require( '@stdlib/array/float32' ); 115 116 var x = new Float32Array( [ 4.0, 2.0, -3.0, 5.0, -1.0 ] ); 117 var y = new Float32Array( [ 2.0, 6.0, -1.0, -4.0, 8.0 ] ); 118 119 var z = sdot.ndarray( x.length, x, 1, 0, y, 1, 0 ); 120 // returns -5.0 121 ``` 122 123 The function has the following additional parameters: 124 125 - **offsetX**: starting index for `x`. 126 - **offsetY**: starting index for `y`. 127 128 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 calculate the dot product of every other value in `x` starting from the second value with the last 3 elements in `y` in reverse order 129 130 ```javascript 131 var Float32Array = require( '@stdlib/array/float32' ); 132 var floor = require( '@stdlib/math/base/special/floor' ); 133 134 var x = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 135 var y = new Float32Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); 136 137 var N = floor( x.length / 2 ); 138 139 var z = sdot.ndarray( N, x, 2, 1, y, -1, y.length-1 ); 140 // returns 128.0 141 ``` 142 143 </section> 144 145 <!-- /.usage --> 146 147 <section class="notes"> 148 149 ## Notes 150 151 - If `N <= 0`, both functions return `0.0`. 152 - `sdot()` corresponds to the [BLAS][blas] level 1 function [`sdot`][sdot]. 153 154 </section> 155 156 <!-- /.notes --> 157 158 <section class="examples"> 159 160 ## Examples 161 162 <!-- eslint no-undef: "error" --> 163 164 ```javascript 165 var randu = require( '@stdlib/random/base/randu' ); 166 var round = require( '@stdlib/math/base/special/round' ); 167 var Float32Array = require( '@stdlib/array/float32' ); 168 var sdot = require( '@stdlib/blas/base/sdot' ); 169 170 var x; 171 var y; 172 var i; 173 174 x = new Float32Array( 10 ); 175 y = new Float32Array( 10 ); 176 for ( i = 0; i < x.length; i++ ) { 177 x[ i ] = round( randu()*100.0 ); 178 y[ i ] = round( randu()*10.0 ); 179 } 180 console.log( x ); 181 console.log( y ); 182 183 var z = sdot( x.length, x, 1, y, -1 ); 184 console.log( z ); 185 ``` 186 187 </section> 188 189 <!-- /.examples --> 190 191 <section class="links"> 192 193 [dot-product]: https://en.wikipedia.org/wiki/Dot_product 194 195 [blas]: http://www.netlib.org/blas 196 197 [sdot]: http://www.netlib.org/lapack/explore-html/df/d28/group__single__blas__level1.html 198 199 [@stdlib/array/float32]: https://www.npmjs.com/package/@stdlib/array-float32 200 201 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 202 203 </section> 204 205 <!-- /.links -->