README.md (3494B)
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 # gdot 22 23 > Calculate the dot product of two 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@b7a453f335bade718a3f48a61658d1564dc3f786/lib/node_modules/@stdlib/blas/gdot/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 gdot = require( '@stdlib/blas/gdot' ); 48 ``` 49 50 #### gdot( x, y ) 51 52 Calculates the dot product of vectors `x` and `y`. 53 54 ```javascript 55 var Int32Array = require( '@stdlib/array/int32' ); 56 var array = require( '@stdlib/ndarray/array' ); 57 58 var x = array( new Int32Array( [ 4.0, 2.0, -3.0, 5.0, -1.0 ] ) ); 59 var y = array( new Int32Array( [ 2.0, 6.0, -1.0, -4.0, 8.0 ] ) ); 60 61 var z = gdot( x, y ); 62 // returns -5.0 63 ``` 64 65 The function has the following parameters: 66 67 - **x**: a 1-dimensional [`ndarray`][@stdlib/ndarray/array] or an array-like object. 68 - **y**: a 1-dimensional [`ndarray`][@stdlib/ndarray/array] or an array-like object. 69 70 If provided empty vectors, the function returns `0.0`. 71 72 ```javascript 73 var z = gdot( [], [] ); 74 // returns 0.0 75 ``` 76 77 </section> 78 79 <!-- /.usage --> 80 81 <section class="notes"> 82 83 ## Notes 84 85 - `gdot()` corresponds to the [BLAS][blas] level 1 function [`ddot`][ddot] with the exception that this implementation works with any array type, not just Float64Arrays. 86 - In general, for best performance, especially for large vectors, provide 1-dimensional [`ndarrays`][@stdlib/ndarray/array] whose underlying data type is either `float64` or `float32`. 87 88 </section> 89 90 <!-- /.notes --> 91 92 <section class="examples"> 93 94 ## Examples 95 96 <!-- eslint no-undef: "error" --> 97 98 ```javascript 99 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); 100 var gdot = require( '@stdlib/blas/gdot' ); 101 102 var rand1 = discreteUniform.factory( 0, 100 ); 103 var rand2 = discreteUniform.factory( 0, 10 ); 104 105 var x = []; 106 var y = []; 107 var i; 108 for ( i = 0; i < 10; i++ ) { 109 x.push( rand1() ); 110 y.push( rand2() ); 111 } 112 console.log( x ); 113 console.log( y ); 114 115 var z = gdot( x, y ); 116 console.log( z ); 117 ``` 118 119 </section> 120 121 <!-- /.examples --> 122 123 <section class="links"> 124 125 [dot-product]: https://en.wikipedia.org/wiki/Dot_product 126 127 [blas]: http://www.netlib.org/blas 128 129 [ddot]: http://www.netlib.org/lapack/explore-html/df/d28/group__single__blas__level1.html 130 131 [@stdlib/ndarray/array]: https://www.npmjs.com/package/@stdlib/ndarray-array 132 133 </section> 134 135 <!-- /.links -->