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