README.md (8024B)
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 # MINSTD Shuffle 22 23 > A linear congruential pseudorandom number generator ([LCG][lcg]) whose output is shuffled. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var minstd = require( '@stdlib/random/base/minstd-shuffle' ); 31 ``` 32 33 #### minstd() 34 35 Returns a pseudorandom integer on the interval `[1, 2147483646]`. 36 37 ```javascript 38 var v = minstd(); 39 // returns <number> 40 ``` 41 42 #### minstd.normalized() 43 44 Returns a pseudorandom number on the interval `[0,1)`. 45 46 ```javascript 47 var v = minstd.normalized(); 48 // returns <number> 49 ``` 50 51 #### minstd.factory( \[options] ) 52 53 Returns a linear congruential pseudorandom number generator ([LCG][lcg]) whose output is shuffled. 54 55 ```javascript 56 var rand = minstd.factory(); 57 ``` 58 59 The function accepts the following `options`: 60 61 - **seed**: pseudorandom number generator seed. 62 - **state**: an [`Int32Array`][@stdlib/array/int32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option. 63 - **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`. 64 65 By default, a random integer is used to seed the returned generator. To seed the generator, provide either an `integer` on the interval `[1, 2147483646]` 66 67 ```javascript 68 var rand = minstd.factory({ 69 'seed': 1234 70 }); 71 72 var v = rand(); 73 // returns 1421600654 74 ``` 75 76 or, for arbitrary length seeds, an array-like `object` containing signed 32-bit integers 77 78 ```javascript 79 var Int32Array = require( '@stdlib/array/int32' ); 80 81 var rand = minstd.factory({ 82 'seed': new Int32Array( [ 1234 ] ) 83 }); 84 85 var r = rand(); 86 // returns 20739838 87 ``` 88 89 To return a generator having a specific initial state, set the generator `state` option. 90 91 ```javascript 92 var rand; 93 var bool; 94 var r; 95 var i; 96 97 // Generate pseudorandom numbers, thus progressing the generator state: 98 for ( i = 0; i < 1000; i++ ) { 99 r = minstd(); 100 } 101 102 // Create a new PRNG initialized to the current state of `minstd`: 103 rand = minstd.factory({ 104 'state': minstd.state 105 }); 106 107 // Test that the generated pseudorandom numbers are the same: 108 bool = ( rand() === minstd() ); 109 // returns true 110 ``` 111 112 #### minstd.NAME 113 114 The generator name. 115 116 ```javascript 117 var str = minstd.NAME; 118 // returns 'minstd-shuffle' 119 ``` 120 121 #### minstd.MIN 122 123 Minimum possible value. 124 125 ```javascript 126 var min = minstd.MIN; 127 // returns 1 128 ``` 129 130 #### minstd.MAX 131 132 Maximum possible value. 133 134 ```javascript 135 var max = minstd.MAX; 136 // returns 2147483646 137 ``` 138 139 #### minstd.seed 140 141 The value used to seed `minstd()`. 142 143 ```javascript 144 var rand; 145 var v; 146 var i; 147 148 // Generate pseudorandom values... 149 for ( i = 0; i < 100; i++ ) { 150 v = minstd(); 151 } 152 153 // Generate the same pseudorandom values... 154 rand = minstd.factory({ 155 'seed': minstd.seed 156 }); 157 for ( i = 0; i < 100; i++ ) { 158 v = rand(); 159 } 160 ``` 161 162 #### minstd.seedLength 163 164 Length of generator seed. 165 166 ```javascript 167 var len = minstd.seedLength; 168 // returns <number> 169 ``` 170 171 #### minstd.state 172 173 Writable property for getting and setting the generator state. 174 175 ```javascript 176 var r = minstd(); 177 // returns <number> 178 179 r = minstd(); 180 // returns <number> 181 182 // ... 183 184 // Get a copy of the current state: 185 var state = minstd.state; 186 // returns <Int32Array> 187 188 r = minstd(); 189 // returns <number> 190 191 r = minstd(); 192 // returns <number> 193 194 // Reset the state: 195 minstd.state = state; 196 197 // Replay the last two pseudorandom numbers: 198 r = minstd(); 199 // returns <number> 200 201 r = minstd(); 202 // returns <number> 203 204 // ... 205 ``` 206 207 #### minstd.stateLength 208 209 Length of generator state. 210 211 ```javascript 212 var len = minstd.stateLength; 213 // returns <number> 214 ``` 215 216 #### minstd.byteLength 217 218 Size (in bytes) of generator state. 219 220 ```javascript 221 var sz = minstd.byteLength; 222 // returns <number> 223 ``` 224 225 #### minstd.toJSON() 226 227 Serializes the pseudorandom number generator as a JSON object. 228 229 ```javascript 230 var o = minstd.toJSON(); 231 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 232 ``` 233 234 </section> 235 236 <!-- /.usage --> 237 238 <section class="notes"> 239 240 ## Notes 241 242 - Before output from a simple linear congruential generator ([LCG][lcg]) is returned, the output is shuffled using the Bays-Durham algorithm. This additional step considerably strengthens the "randomness quality" of a simple [LCG][lcg]'s output. 243 - The generator has a period of approximately `2.1e9` (see [Numerical Recipes in C, 2nd Edition](#references), p. 279). 244 - An [LCG][lcg] is fast and uses little memory. On the other hand, because the generator is a simple [linear congruential generator][lcg], the generator has recognized shortcomings. By today's PRNG standards, the generator's period is relatively short. In general, this generator is unsuitable for Monte Carlo simulations and cryptographic applications. 245 - 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. 246 - 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). 247 248 </section> 249 250 <!-- /.notes --> 251 252 <section class="examples"> 253 254 ## Examples 255 256 <!-- eslint no-undef: "error" --> 257 258 ```javascript 259 var minstd = require( '@stdlib/random/base/minstd-shuffle' ); 260 261 var seed; 262 var rand; 263 var i; 264 265 // Generate pseudorandom numbers... 266 for ( i = 0; i < 100; i++ ) { 267 console.log( minstd() ); 268 } 269 270 // Create a new pseudorandom number generator... 271 seed = 1234; 272 rand = minstd.factory({ 273 'seed': seed 274 }); 275 for ( i = 0; i < 100; i++ ) { 276 console.log( rand() ); 277 } 278 279 // Create another pseudorandom number generator using a previous seed... 280 rand = minstd.factory({ 281 'seed': minstd.seed 282 }); 283 for ( i = 0; i < 100; i++ ) { 284 console.log( rand() ); 285 } 286 ``` 287 288 </section> 289 290 <!-- /.examples --> 291 292 * * * 293 294 <section class="references"> 295 296 ## References 297 298 - Park, S. K., and K. W. Miller. 1988. "Random Number Generators: Good Ones Are Hard to Find." _Communications of the ACM_ 31 (10). New York, NY, USA: ACM: 1192–1201. doi:[10.1145/63039.63042][@park:1988]. 299 - Bays, Carter, and S. D. Durham. 1976. "Improving a Poor Random Number Generator." _ACM Transactions on Mathematical Software_ 2 (1). New York, NY, USA: ACM: 59–64. doi:[10.1145/355666.355670][@bays:1976]. 300 - Herzog, T.N., and G. Lord. 2002. _Applications of Monte Carlo Methods to Finance and Insurance_. ACTEX Publications. [https://books.google.com/books?id=vC7I\\\_gdX-A0C][@herzog:2002]. 301 - Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William T. Vetterling. 1992. _Numerical Recipes in C: The Art of Scientific Computing, Second Edition_. Cambridge University Press. 302 303 </section> 304 305 <!-- /.references --> 306 307 <section class="links"> 308 309 [lcg]: https://en.wikipedia.org/wiki/Linear_congruential_generator 310 311 [@park:1988]: http://dx.doi.org/10.1145/63039.63042 312 313 [@bays:1976]: http://dx.doi.org/10.1145/355666.355670 314 315 [@herzog:2002]: https://books.google.com/books?id=vC7I_gdX-A0C 316 317 [@stdlib/array/int32]: https://www.npmjs.com/package/@stdlib/array-int32 318 319 </section> 320 321 <!-- /.links -->