README.md (5170B)
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 # snrm2 22 23 > Calculate the L2-norm of a single-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@247c6b352fc1002f11ba3e7ed389f067380a8a87/lib/node_modules/@stdlib/blas/base/snrm2/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 snrm2 = require( '@stdlib/blas/base/snrm2' ); 48 ``` 49 50 #### snrm2( N, x, stride ) 51 52 Computes the [L2-norm][l2-norm] of a single-precision floating-point vector `x`. 53 54 ```javascript 55 var Float32Array = require( '@stdlib/array/float32' ); 56 57 var x = new Float32Array( [ 1.0, -2.0, 2.0 ] ); 58 var N = 3; 59 60 var z = snrm2( 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 [`Float32Array`][@stdlib/array/float32]. 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 Float32Array = require( '@stdlib/array/float32' ); 74 var floor = require( '@stdlib/math/base/special/floor' ); 75 76 var x = new Float32Array( [ 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 = snrm2( 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 Float32Array = require( '@stdlib/array/float32' ); 89 var floor = require( '@stdlib/math/base/special/floor' ); 90 91 var x0 = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 92 var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 93 94 var N = floor( x0.length / 2 ); 95 96 var z = snrm2( N, x1, 2 ); 97 // returns 5.0 98 ``` 99 100 If either `N` or `stride` is less than or equal to `0`, the function returns `0`. 101 102 #### snrm2.ndarray( N, x, stride, offset ) 103 104 Computes the [L2-norm][l2-norm] of a single-precision floating-point vector using alternative indexing semantics. 105 106 ```javascript 107 var Float32Array = require( '@stdlib/array/float32' ); 108 109 var x = new Float32Array( [ 1.0, -2.0, 2.0 ] ); 110 var N = 3; 111 112 var z = snrm2.ndarray( N, x, 1, 0 ); 113 // returns 3.0 114 ``` 115 116 The function has the following additional parameters: 117 118 - **offset**: starting index for `x`. 119 120 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 121 122 ```javascript 123 var Float32Array = require( '@stdlib/array/float32' ); 124 var floor = require( '@stdlib/math/base/special/floor' ); 125 126 var x = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); 127 var N = floor( x.length / 2 ); 128 129 var z = snrm2.ndarray( N, x, 2, 1 ); 130 // returns 5.0 131 ``` 132 133 </section> 134 135 <!-- /.usage --> 136 137 <section class="notes"> 138 139 ## Notes 140 141 - If `N <= 0`, both functions return `0.0`. 142 - `snrm2()` corresponds to the [BLAS][blas] level 1 function [`snrm2`][snrm2]. 143 144 </section> 145 146 <!-- /.notes --> 147 148 <section class="examples"> 149 150 ## Examples 151 152 <!-- eslint no-undef: "error" --> 153 154 ```javascript 155 var randu = require( '@stdlib/random/base/randu' ); 156 var round = require( '@stdlib/math/base/special/round' ); 157 var Float32Array = require( '@stdlib/array/float32' ); 158 var snrm2 = require( '@stdlib/blas/base/snrm2' ); 159 160 var x; 161 var i; 162 163 x = new Float32Array( 10 ); 164 for ( i = 0; i < x.length; i++ ) { 165 x[ i ] = round( randu()*100.0 ); 166 } 167 console.log( x ); 168 169 var z = snrm2( x.length, x, 1 ); 170 console.log( z ); 171 ``` 172 173 </section> 174 175 <!-- /.examples --> 176 177 <section class="links"> 178 179 [l2-norm]: https://en.wikipedia.org/wiki/Euclidean_distance 180 181 [blas]: http://www.netlib.org/blas 182 183 [snrm2]: http://www.netlib.org/lapack/explore-html/df/d28/group__single__blas__level1.html 184 185 [@stdlib/array/float32]: https://www.npmjs.com/package/@stdlib/array-float32 186 187 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 188 189 </section> 190 191 <!-- /.links -->