README.md (8924B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # Normal Random Numbers 22 23 > [Normally][normal] distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var normal = require( '@stdlib/random/base/normal' ); 31 ``` 32 33 #### normal( mu, sigma ) 34 35 Returns a pseudorandom number drawn from a [normal][normal] distribution with parameters `mu` (mean) and `sigma` (standard deviation). 36 37 ```javascript 38 var r = normal( 2.0, 5.0 ); 39 // returns <number> 40 ``` 41 42 If `mu` or `sigma` is `NaN` or `sigma <= 0`, the function returns `NaN`. 43 44 ```javascript 45 var r = normal( 2.0, -2.0 ); 46 // returns NaN 47 48 r = normal( NaN, 5.0 ); 49 // returns NaN 50 51 r = normal( 2.0, NaN ); 52 // returns NaN 53 ``` 54 55 #### normal.factory( \[mu, sigma, ]\[options] ) 56 57 Returns a pseudorandom number generator (PRNG) for generating pseudorandom numbers drawn from a [normal][normal] distribution. 58 59 ```javascript 60 var rand = normal.factory(); 61 62 var r = rand( 0.1, 1.5 ); 63 // returns <number> 64 ``` 65 66 If provided `mu` and `sigma`, the returned generator returns random variates from the specified distribution. 67 68 ```javascript 69 // Draw from normal( 10.0, 2.0 ) distribution: 70 var rand = normal.factory( 10.0, 2.0 ); 71 72 var r = rand(); 73 // returns <number> 74 75 r = rand(); 76 // returns <number> 77 ``` 78 79 If not provided `mu` and `sigma`, the returned generator requires that both parameters be provided at each invocation. 80 81 ```javascript 82 var rand = normal.factory(); 83 84 var r = rand( 0.0, 1.0 ); 85 // returns <number> 86 87 r = rand( -2.0, 2.0 ); 88 // returns <number> 89 ``` 90 91 The function accepts the following `options`: 92 93 - **prng**: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval `[0,1)`. If provided, the function **ignores** both the `state` and `seed` options. In order to seed the returned pseudorandom number generator, one must seed the provided `prng` (assuming the provided `prng` is seedable). 94 - **seed**: pseudorandom number generator seed. 95 - **state**: a [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option. 96 - **copy**: `boolean` indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that a returned generator has exclusive control over its internal state. Default: `true`. 97 98 To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option. 99 100 ```javascript 101 var minstd = require( '@stdlib/random/base/minstd' ); 102 103 var rand = normal.factory({ 104 'prng': minstd.normalized 105 }); 106 107 var r = rand( 1.0, 2.0 ); 108 // returns <number> 109 ``` 110 111 To seed a pseudorandom number generator, set the `seed` option. 112 113 ```javascript 114 var rand1 = normal.factory({ 115 'seed': 12345 116 }); 117 118 var r1 = rand1( 1.0, 2.0 ); 119 // returns <number> 120 121 var rand2 = normal.factory( 1.0, 2.0, { 122 'seed': 12345 123 }); 124 125 var r2 = rand2(); 126 // returns <number> 127 128 var bool = ( r1 === r2 ); 129 // returns true 130 ``` 131 132 To return a generator having a specific initial state, set the generator `state` option. 133 134 ```javascript 135 var rand; 136 var bool; 137 var r; 138 var i; 139 140 // Generate pseudorandom numbers, thus progressing the generator state: 141 for ( i = 0; i < 1000; i++ ) { 142 r = normal( 1.0, 2.0 ); 143 } 144 145 // Create a new PRNG initialized to the current state of `normal`: 146 rand = normal.factory({ 147 'state': normal.state 148 }); 149 150 // Test that the generated pseudorandom numbers are the same: 151 bool = ( rand( 1.0, 2.0 ) === normal( 1.0, 2.0 ) ); 152 // returns true 153 ``` 154 155 #### normal.NAME 156 157 The generator name. 158 159 ```javascript 160 var str = normal.NAME; 161 // returns 'normal' 162 ``` 163 164 #### normal.PRNG 165 166 The underlying pseudorandom number generator. 167 168 ```javascript 169 var prng = normal.PRNG; 170 // returns <Function> 171 ``` 172 173 #### normal.seed 174 175 The value used to seed `normal()`. 176 177 ```javascript 178 var rand; 179 var r; 180 var i; 181 182 // Generate pseudorandom values... 183 for ( i = 0; i < 100; i++ ) { 184 r = normal( 2.0, 2.0 ); 185 } 186 187 // Generate the same pseudorandom values... 188 rand = normal.factory( 2.0, 2.0, { 189 'seed': normal.seed 190 }); 191 for ( i = 0; i < 100; i++ ) { 192 r = rand(); 193 } 194 ``` 195 196 If provided a PRNG for uniformly distributed numbers, this value is `null`. 197 198 <!-- eslint-disable stdlib/no-builtin-math --> 199 200 ```javascript 201 var rand = normal.factory({ 202 'prng': Math.random 203 }); 204 205 var seed = rand.seed; 206 // returns null 207 ``` 208 209 #### normal.seedLength 210 211 Length of generator seed. 212 213 ```javascript 214 var len = normal.seedLength; 215 // returns <number> 216 ``` 217 218 If provided a PRNG for uniformly distributed numbers, this value is `null`. 219 220 <!-- eslint-disable stdlib/no-builtin-math --> 221 222 ```javascript 223 var rand = normal.factory({ 224 'prng': Math.random 225 }); 226 227 var len = rand.seedLength; 228 // returns null 229 ``` 230 231 #### normal.state 232 233 Writable property for getting and setting the generator state. 234 235 ```javascript 236 var r = normal( 2.0, 5.0 ); 237 // returns <number> 238 239 r = normal( 2.0, 5.0 ); 240 // returns <number> 241 242 // ... 243 244 // Get a copy of the current state: 245 var state = normal.state; 246 // returns <Uint32Array> 247 248 r = normal( 2.0, 5.0 ); 249 // returns <number> 250 251 r = normal( 2.0, 5.0 ); 252 // returns <number> 253 254 // Reset the state: 255 normal.state = state; 256 257 // Replay the last two pseudorandom numbers: 258 r = normal( 2.0, 5.0 ); 259 // returns <number> 260 261 r = normal( 2.0, 5.0 ); 262 // returns <number> 263 264 // ... 265 ``` 266 267 If provided a PRNG for uniformly distributed numbers, this value is `null`. 268 269 <!-- eslint-disable stdlib/no-builtin-math --> 270 271 ```javascript 272 var rand = normal.factory({ 273 'prng': Math.random 274 }); 275 276 var state = rand.state; 277 // returns null 278 ``` 279 280 #### normal.stateLength 281 282 Length of generator state. 283 284 ```javascript 285 var len = normal.stateLength; 286 // returns <number> 287 ``` 288 289 If provided a PRNG for uniformly distributed numbers, this value is `null`. 290 291 <!-- eslint-disable stdlib/no-builtin-math --> 292 293 ```javascript 294 var rand = normal.factory({ 295 'prng': Math.random 296 }); 297 298 var len = rand.stateLength; 299 // returns null 300 ``` 301 302 #### normal.byteLength 303 304 Size of generator state. 305 306 ```javascript 307 var sz = normal.byteLength; 308 // returns <number> 309 ``` 310 311 If provided a PRNG for uniformly distributed numbers, this value is `null`. 312 313 <!-- eslint-disable stdlib/no-builtin-math --> 314 315 ```javascript 316 var rand = normal.factory({ 317 'prng': Math.random 318 }); 319 320 var sz = rand.byteLength; 321 // returns null 322 ``` 323 324 #### normal.toJSON() 325 326 Serializes the pseudorandom number generator as a JSON object. 327 328 ```javascript 329 var o = normal.toJSON(); 330 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 331 ``` 332 333 If provided a PRNG for uniformly distributed numbers, this method returns `null`. 334 335 <!-- eslint-disable stdlib/no-builtin-math --> 336 337 ```javascript 338 var rand = normal.factory({ 339 'prng': Math.random 340 }); 341 342 var o = rand.toJSON(); 343 // returns null 344 ``` 345 346 </section> 347 348 <!-- /.usage --> 349 350 <section class="notes"> 351 352 ## Notes 353 354 - If PRNG state is "shared" (meaning a state array was provided during PRNG creation and **not** copied) and one sets the generator state to a state array having a different length, the PRNG does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for **each** relevant PRNG must be **explicitly** set. 355 - If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array). 356 357 </section> 358 359 <!-- /.notes --> 360 361 <section class="examples"> 362 363 ## Examples 364 365 <!-- eslint no-undef: "error" --> 366 367 ```javascript 368 var normal = require( '@stdlib/random/base/normal' ); 369 370 var seed; 371 var rand; 372 var i; 373 374 // Generate pseudorandom numbers... 375 for ( i = 0; i < 100; i++ ) { 376 console.log( normal( 0.0, 1.0 ) ); 377 } 378 379 // Create a new pseudorandom number generator... 380 seed = 1234; 381 rand = normal.factory( 5.0, 2.0, { 382 'seed': seed 383 }); 384 for ( i = 0; i < 100; i++ ) { 385 console.log( rand() ); 386 } 387 388 // Create another pseudorandom number generator using a previous seed... 389 rand = normal.factory( 0.0, 1.0, { 390 'seed': normal.seed 391 }); 392 for ( i = 0; i < 100; i++ ) { 393 console.log( rand() ); 394 } 395 ``` 396 397 </section> 398 399 <!-- /.examples --> 400 401 <section class="links"> 402 403 [normal]: https://en.wikipedia.org/wiki/Normal_distribution 404 405 [@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32 406 407 </section> 408 409 <!-- /.links -->