time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (6005B)

      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 # ddot
     22 
     23 > Calculate the dot product of two double-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@929657146427564b61e3e6bdda76949ebe2ce923/lib/node_modules/@stdlib/blas/base/ddot/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 ddot = require( '@stdlib/blas/base/ddot' );
     48 ```
     49 
     50 #### ddot( N, x, strideX, y, strideY )
     51 
     52 Calculates the dot product of vectors `x` and `y`.
     53 
     54 ```javascript
     55 var Float64Array = require( '@stdlib/array/float64' );
     56 
     57 var x = new Float64Array( [ 4.0, 2.0, -3.0, 5.0, -1.0 ] );
     58 var y = new Float64Array( [ 2.0, 6.0, -1.0, -4.0, 8.0 ] );
     59 
     60 var z = ddot( 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 [`Float64Array`][@stdlib/array/float64].
     68 -   **strideX**: index increment for `x`.
     69 -   **y**: input [`Float64Array`][@stdlib/array/float64].
     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 Float64Array = require( '@stdlib/array/float64' );
     76 var floor = require( '@stdlib/math/base/special/floor' );
     77 
     78 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
     79 var y = new Float64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
     80 
     81 var N = floor( x.length / 2 );
     82 
     83 var z = ddot( 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 Float64Array = require( '@stdlib/array/float64' );
     93 var floor = require( '@stdlib/math/base/special/floor' );
     94 
     95 // Initial arrays...
     96 var x0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
     97 var y0 = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
     98 
     99 // Create offset views...
    100 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
    101 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element
    102 
    103 var N = floor( x0.length / 2 );
    104 
    105 var z = ddot( N, x1, -2, y1, 1 );
    106 // returns 128.0
    107 ```
    108 
    109 #### ddot.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 Float64Array = require( '@stdlib/array/float64' );
    115 
    116 var x = new Float64Array( [ 4.0, 2.0, -3.0, 5.0, -1.0 ] );
    117 var y = new Float64Array( [ 2.0, 6.0, -1.0, -4.0, 8.0 ] );
    118 
    119 var z = ddot.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 Float64Array = require( '@stdlib/array/float64' );
    132 var floor = require( '@stdlib/math/base/special/floor' );
    133 
    134 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
    135 var y = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
    136 
    137 var N = floor( x.length / 2 );
    138 
    139 var z = ddot.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 -   `ddot()` corresponds to the [BLAS][blas] level 1 function [`ddot`][ddot].
    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 Float64Array = require( '@stdlib/array/float64' );
    168 var ddot = require( '@stdlib/blas/base/ddot' );
    169 
    170 var x;
    171 var y;
    172 var i;
    173 
    174 x = new Float64Array( 10 );
    175 y = new Float64Array( 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 = ddot( 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 [ddot]: http://www.netlib.org/lapack/explore-html/de/da4/group__double__blas__level1.html
    198 
    199 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64
    200 
    201 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    202 
    203 </section>
    204 
    205 <!-- /.links -->