README.md (5091B)
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 # dnrm2 22 23 > Calculate the L2-norm of a double-precision floating-point vector. 24 25 <section class="intro"> 26 27 The [L2-norm][l2-norm] is defined as 28 29 <!-- <equation class="equation" label="eq:l2_norm" align="center raw="\|\mathbf{x}\|_2 = \sqrt{x_0^2 + x_1^2 + \ldots + x_{N-1}^2}" alt="L2-norm definition."> --> 30 31 <div class="equation" align="center" data-raw-text="\|\mathbf{x}\|_2 = \sqrt{x_0^2 + x_1^2 + \ldots + x_{N-1}^2}" data-equation="eq:l2_norm"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@f766d7eeb56ff14cbceeeeef03d7f7b88c467515/lib/node_modules/@stdlib/blas/base/dnrm2/docs/img/equation_l2_norm.svg" alt="L2-norm 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 dnrm2 = require( '@stdlib/blas/base/dnrm2' ); 48 ``` 49 50 #### dnrm2( N, x, stride ) 51 52 Computes the [L2-norm][l2-norm] of a double-precision floating-point vector `x`. 53 54 ```javascript 55 var Float64Array = require( '@stdlib/array/float64' ); 56 57 var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); 58 var N = 3; 59 60 var z = dnrm2( N, x, 1 ); 61 // returns 3.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 - **stride**: index increment for `x`. 69 70 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [L2-norm][l2-norm] of every other element in `x`, 71 72 ```javascript 73 var Float64Array = require( '@stdlib/array/float64' ); 74 var floor = require( '@stdlib/math/base/special/floor' ); 75 76 var x = new Float64Array( [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ] ); 77 var N = floor( x.length / 2 ); 78 79 var z = dnrm2( N, x, 2 ); 80 // returns 5.0 81 ``` 82 83 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 84 85 <!-- eslint-disable stdlib/capitalized-comments --> 86 87 ```javascript 88 var Float64Array = require( '@stdlib/array/float64' ); 89 90 var x0 = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 91 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 92 93 var N = 4; 94 95 var z = dnrm2( N, x1, 2 ); 96 // returns 5.0 97 ``` 98 99 If either `N` or `stride` is less than or equal to `0`, the function returns `0`. 100 101 #### dnrm2.ndarray( N, x, stride, offset ) 102 103 Computes the [L2-norm][l2-norm] of a double-precision floating-point vector using alternative indexing semantics. 104 105 ```javascript 106 var Float64Array = require( '@stdlib/array/float64' ); 107 108 var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); 109 var N = 3; 110 111 var z = dnrm2.ndarray( N, x, 1, 0 ); 112 // returns 3.0 113 ``` 114 115 The function has the following additional parameters: 116 117 - **offset**: starting index for `x`. 118 119 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 calculate the [L2-norm][l2-norm] for every other value in `x` starting from the second value 120 121 ```javascript 122 var Float64Array = require( '@stdlib/array/float64' ); 123 var floor = require( '@stdlib/math/base/special/floor' ); 124 125 var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 126 var N = floor( x.length / 2 ); 127 128 var z = dnrm2.ndarray( N, x, 2, 1 ); 129 // returns 5.0 130 ``` 131 132 </section> 133 134 <!-- /.usage --> 135 136 <section class="notes"> 137 138 ## Notes 139 140 - If `N <= 0`, both functions return `0.0`. 141 - `dnrm2()` corresponds to the [BLAS][blas] level 1 function [`dnrm2`][dnrm2]. 142 143 </section> 144 145 <!-- /.notes --> 146 147 <section class="examples"> 148 149 ## Examples 150 151 <!-- eslint no-undef: "error" --> 152 153 ```javascript 154 var randu = require( '@stdlib/random/base/randu' ); 155 var round = require( '@stdlib/math/base/special/round' ); 156 var Float64Array = require( '@stdlib/array/float64' ); 157 var dnrm2 = require( '@stdlib/blas/base/dnrm2' ); 158 159 var x; 160 var i; 161 162 x = new Float64Array( 10 ); 163 for ( i = 0; i < x.length; i++ ) { 164 x[ i ] = round( randu()*100.0 ); 165 } 166 console.log( x ); 167 168 var z = dnrm2( x.length, x, 1 ); 169 console.log( z ); 170 ``` 171 172 </section> 173 174 <!-- /.examples --> 175 176 <section class="links"> 177 178 [l2-norm]: https://en.wikipedia.org/wiki/Euclidean_distance 179 180 [blas]: http://www.netlib.org/blas 181 182 [dnrm2]: http://www.netlib.org/lapack/explore-html/de/da4/group__double__blas__level1.html 183 184 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64 185 186 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 187 188 </section> 189 190 <!-- /.links -->