README.md (8863B)
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 # randn 22 23 > Standard normally distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var randn = require( '@stdlib/random/base/randn' ); 31 ``` 32 33 #### randn() 34 35 Returns a standard normally distributed pseudorandom number. 36 37 ```javascript 38 var r = randn(); 39 // returns <number> 40 ``` 41 42 #### randn.factory( \[options] ) 43 44 Returns a pseudorandom number generator for creating standard normally distributed random numbers. 45 46 ```javascript 47 var rand = randn.factory(); 48 ``` 49 50 The function accepts the following `options`: 51 52 - **name**: name of the underlying pseudorandom number generator which samples from the standard normal distribution. 53 54 - [`improved-ziggurat`][@stdlib/random/base/improved-ziggurat]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/improved-ziggurat 55 - [`box-muller`][@stdlib/random/base/box-muller]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/box-muller 56 57 Default: [`'improved-ziggurat'`][@stdlib/random/base/improved-ziggurat]. 58 59 - **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). 60 61 - **seed**: pseudorandom number generator seed. Valid seed values vary according to the underlying PRNG. 62 63 - **state**: pseudorandom number generator state. Valid state values vary according to the underlying PRNG. If provided, the function ignores the `seed` option. 64 65 - **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`. 66 67 By default, the underlying pseudorandom number generator is [`improved-ziggurat`][@stdlib/random/base/improved-ziggurat]. To use a different PRNG, set the `name` option. 68 69 ```javascript 70 var rand = randn.factory({ 71 'name': 'box-muller' 72 }); 73 74 var r = rand(); 75 // returns <number> 76 ``` 77 78 To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option. 79 80 ```javascript 81 var minstd = require( '@stdlib/random/base/minstd' ); 82 83 var rand = randn.factory({ 84 'prng': minstd.normalized 85 }); 86 87 var r = rand(); 88 // returns <number> 89 ``` 90 91 To seed a pseudorandom number generator, set the `seed` option. 92 93 ```javascript 94 var rand1 = randn.factory({ 95 'seed': 12345 96 }); 97 98 var r1 = rand1(); 99 // returns <number> 100 101 var rand2 = randn.factory({ 102 'seed': 12345 103 }); 104 105 var r2 = rand2(); 106 // returns <number> 107 108 var bool = ( r1 === r2 ); 109 // returns true 110 ``` 111 112 To return a generator having a specific initial state, set the generator `state` option. 113 114 ```javascript 115 var rand; 116 var bool; 117 var r; 118 var i; 119 120 // Generate pseudorandom numbers, thus progressing the generator state: 121 for ( i = 0; i < 1000; i++ ) { 122 r = randn(); 123 } 124 125 // Create a new PRNG initialized to the current state of `randn`: 126 rand = randn.factory({ 127 'state': randn.state 128 }); 129 130 // Test that the generated pseudorandom numbers are the same: 131 bool = ( rand() === randn() ); 132 // returns true 133 ``` 134 135 #### randn.NAME 136 137 The generator name. 138 139 ```javascript 140 var str = randn.NAME; 141 // returns 'randn' 142 ``` 143 144 #### randn.PRNG 145 146 The underlying pseudorandom number generator. 147 148 ```javascript 149 var prng = randn.PRNG; 150 // returns <Function> 151 ``` 152 153 #### randn.seed 154 155 The value used to seed `randn()`. 156 157 ```javascript 158 var rand; 159 var r; 160 var i; 161 162 // Generate pseudorandom values... 163 for ( i = 0; i < 100; i++ ) { 164 r = randn(); 165 } 166 167 // Generate the same pseudorandom values... 168 rand = randn.factory({ 169 'seed': randn.seed 170 }); 171 for ( i = 0; i < 100; i++ ) { 172 r = rand(); 173 } 174 ``` 175 176 If provided a PRNG for uniformly distributed numbers, this value is `null`. 177 178 <!-- eslint-disable stdlib/no-builtin-math --> 179 180 ```javascript 181 var rand = randn.factory({ 182 'prng': Math.random 183 }); 184 185 var seed = rand.seed; 186 // returns null 187 ``` 188 189 #### randn.seedLength 190 191 Length of generator seed. 192 193 ```javascript 194 var len = randn.seedLength; 195 // returns <number> 196 ``` 197 198 If provided a PRNG for uniformly distributed numbers, this value is `null`. 199 200 <!-- eslint-disable stdlib/no-builtin-math --> 201 202 ```javascript 203 var rand = randn.factory({ 204 'prng': Math.random 205 }); 206 207 var len = rand.seedLength; 208 // returns null 209 ``` 210 211 #### randn.state 212 213 Writable property for getting and setting the generator state. 214 215 ```javascript 216 var r = randn(); 217 // returns <number> 218 219 r = randn(); 220 // returns <number> 221 222 // ... 223 224 // Get a copy of the current state: 225 var state = randn.state; 226 227 r = randn(); 228 // returns <number> 229 230 r = randn(); 231 // returns <number> 232 233 // Reset the state: 234 randn.state = state; 235 236 // Replay the last two pseudorandom numbers: 237 r = randn(); 238 // returns <number> 239 240 r = randn(); 241 // returns <number> 242 243 // ... 244 ``` 245 246 If provided a PRNG for uniformly distributed numbers, this value is `null`. 247 248 <!-- eslint-disable stdlib/no-builtin-math --> 249 250 ```javascript 251 var rand = randn.factory({ 252 'prng': Math.random 253 }); 254 255 var state = rand.state; 256 // returns null 257 ``` 258 259 #### randn.stateLength 260 261 Length of generator state. 262 263 ```javascript 264 var len = randn.stateLength; 265 // returns <number> 266 ``` 267 268 If provided a PRNG for uniformly distributed numbers, this value is `null`. 269 270 <!-- eslint-disable stdlib/no-builtin-math --> 271 272 ```javascript 273 var rand = randn.factory({ 274 'prng': Math.random 275 }); 276 277 var len = rand.stateLength; 278 // returns null 279 ``` 280 281 #### randn.byteLength 282 283 Size (in bytes) of generator state. 284 285 ```javascript 286 var sz = randn.byteLength; 287 // returns <number> 288 ``` 289 290 If provided a PRNG for uniformly distributed numbers, this value is `null`. 291 292 <!-- eslint-disable stdlib/no-builtin-math --> 293 294 ```javascript 295 var rand = randn.factory({ 296 'prng': Math.random 297 }); 298 299 var sz = rand.byteLength; 300 // returns null 301 ``` 302 303 #### randn.toJSON() 304 305 Serializes the pseudorandom number generator as a JSON object. 306 307 ```javascript 308 var o = randn.toJSON(); 309 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 310 ``` 311 312 If provided a PRNG for uniformly distributed numbers, this method returns `null`. 313 314 <!-- eslint-disable stdlib/no-builtin-math --> 315 316 ```javascript 317 var rand = randn.factory({ 318 'prng': Math.random 319 }); 320 321 var o = rand.toJSON(); 322 // returns null 323 ``` 324 325 </section> 326 327 <!-- /.usage --> 328 329 <section class="notes"> 330 331 ## Notes 332 333 - **Warning**: the default underlying source of pseudorandom numbers may **change** in the future. If exact reproducibility is required, either explicitly specify a PRNG via the `name` option or use an underlying PRNG directly. 334 - 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. 335 - 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). 336 337 </section> 338 339 <!-- /.notes --> 340 341 <section class="examples"> 342 343 ## Examples 344 345 <!-- eslint no-undef: "error" --> 346 347 ```javascript 348 var randn = require( '@stdlib/random/base/randn' ); 349 350 var seed; 351 var rand; 352 var i; 353 354 // Generate pseudorandom numbers... 355 for ( i = 0; i < 100; i++ ) { 356 console.log( randn() ); 357 } 358 359 // Create a new pseudorandom number generator... 360 seed = 1234; 361 rand = randn.factory({ 362 'seed': seed 363 }); 364 for ( i = 0; i < 100; i++ ) { 365 console.log( rand() ); 366 } 367 368 // Create another pseudorandom number generator using a previous seed... 369 rand = randn.factory({ 370 'seed': randn.seed 371 }); 372 for ( i = 0; i < 100; i++ ) { 373 console.log( rand() ); 374 } 375 ``` 376 377 </section> 378 379 <!-- /.examples --> 380 381 <section class="links"> 382 383 [@stdlib/random/base/improved-ziggurat]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/improved-ziggurat 384 385 [@stdlib/random/base/box-muller]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/box-muller 386 387 </section> 388 389 <!-- /.links -->