README.md (15611B)
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 # Pseudorandom Number Generators 22 23 > Standard library base pseudorandom number generators (PRNGs). 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var random = require( '@stdlib/random/base' ); 31 ``` 32 33 #### random 34 35 Standard library base pseudorandom number generators (PRNGs). 36 37 ```javascript 38 var ns = random; 39 // returns {...} 40 ``` 41 42 The namespace contains the following PRNGs: 43 44 <!-- <toc pattern="*"> --> 45 46 <div class="namespace-toc"> 47 48 - <span class="signature">[`arcsine( a, b )`][@stdlib/random/base/arcsine]</span><span class="delimiter">: </span><span class="description">arcsine distributed pseudorandom numbers.</span> 49 - <span class="signature">[`bernoulli( p )`][@stdlib/random/base/bernoulli]</span><span class="delimiter">: </span><span class="description">Bernoulli distributed pseudorandom numbers.</span> 50 - <span class="signature">[`beta( alpha, beta )`][@stdlib/random/base/beta]</span><span class="delimiter">: </span><span class="description">beta distributed pseudorandom numbers.</span> 51 - <span class="signature">[`betaprime( alpha, beta )`][@stdlib/random/base/betaprime]</span><span class="delimiter">: </span><span class="description">beta prime distributed pseudorandom numbers.</span> 52 - <span class="signature">[`binomial( n, p )`][@stdlib/random/base/binomial]</span><span class="delimiter">: </span><span class="description">binomial distributed pseudorandom numbers.</span> 53 - <span class="signature">[`boxMuller()`][@stdlib/random/base/box-muller]</span><span class="delimiter">: </span><span class="description">standard normally distributed pseudorandom numbers using the Box-Muller transform.</span> 54 - <span class="signature">[`cauchy( x0, gamma )`][@stdlib/random/base/cauchy]</span><span class="delimiter">: </span><span class="description">Cauchy distributed pseudorandom numbers.</span> 55 - <span class="signature">[`chi( k )`][@stdlib/random/base/chi]</span><span class="delimiter">: </span><span class="description">Chi distributed pseudorandom numbers.</span> 56 - <span class="signature">[`chisquare( k )`][@stdlib/random/base/chisquare]</span><span class="delimiter">: </span><span class="description">Chi-square distributed pseudorandom numbers.</span> 57 - <span class="signature">[`cosine( mu, s )`][@stdlib/random/base/cosine]</span><span class="delimiter">: </span><span class="description">raised cosine distributed pseudorandom numbers.</span> 58 - <span class="signature">[`discreteUniform( a, b )`][@stdlib/random/base/discrete-uniform]</span><span class="delimiter">: </span><span class="description">discrete uniform distributed pseudorandom numbers.</span> 59 - <span class="signature">[`erlang( k, lambda )`][@stdlib/random/base/erlang]</span><span class="delimiter">: </span><span class="description">Erlang distributed pseudorandom numbers.</span> 60 - <span class="signature">[`exponential( lambda )`][@stdlib/random/base/exponential]</span><span class="delimiter">: </span><span class="description">exponentially distributed pseudorandom numbers.</span> 61 - <span class="signature">[`f( d1, d2 )`][@stdlib/random/base/f]</span><span class="delimiter">: </span><span class="description">F distributed pseudorandom numbers.</span> 62 - <span class="signature">[`frechet( alpha, s, m )`][@stdlib/random/base/frechet]</span><span class="delimiter">: </span><span class="description">Fréchet distributed pseudorandom numbers.</span> 63 - <span class="signature">[`gamma( alpha, beta )`][@stdlib/random/base/gamma]</span><span class="delimiter">: </span><span class="description">gamma distributed pseudorandom numbers.</span> 64 - <span class="signature">[`geometric( p )`][@stdlib/random/base/geometric]</span><span class="delimiter">: </span><span class="description">geometric distributed pseudorandom numbers.</span> 65 - <span class="signature">[`gumbel( mu, beta )`][@stdlib/random/base/gumbel]</span><span class="delimiter">: </span><span class="description">Gumbel distributed pseudorandom numbers.</span> 66 - <span class="signature">[`hypergeometric( N, K, n )`][@stdlib/random/base/hypergeometric]</span><span class="delimiter">: </span><span class="description">hypergeometric distributed pseudorandom numbers.</span> 67 - <span class="signature">[`improvedZiggurat()`][@stdlib/random/base/improved-ziggurat]</span><span class="delimiter">: </span><span class="description">standard normally distributed pseudorandom numbers using the Improved Ziggurat method.</span> 68 - <span class="signature">[`invgamma( alpha, beta )`][@stdlib/random/base/invgamma]</span><span class="delimiter">: </span><span class="description">inverse gamma distributed pseudorandom numbers.</span> 69 - <span class="signature">[`kumaraswamy( a, b )`][@stdlib/random/base/kumaraswamy]</span><span class="delimiter">: </span><span class="description">Kumaraswamy's double bounded distributed pseudorandom numbers.</span> 70 - <span class="signature">[`laplace( mu, b )`][@stdlib/random/base/laplace]</span><span class="delimiter">: </span><span class="description">Laplace (double exponential) distributed pseudorandom numbers.</span> 71 - <span class="signature">[`levy( mu, c )`][@stdlib/random/base/levy]</span><span class="delimiter">: </span><span class="description">Lévy distributed pseudorandom numbers.</span> 72 - <span class="signature">[`logistic( mu, s )`][@stdlib/random/base/logistic]</span><span class="delimiter">: </span><span class="description">logistic distributed pseudorandom numbers.</span> 73 - <span class="signature">[`lognormal( mu, sigma )`][@stdlib/random/base/lognormal]</span><span class="delimiter">: </span><span class="description">lognormal distributed pseudorandom numbers.</span> 74 - <span class="signature">[`minstdShuffle()`][@stdlib/random/base/minstd-shuffle]</span><span class="delimiter">: </span><span class="description">A linear congruential pseudorandom number generator (LCG) whose output is shuffled.</span> 75 - <span class="signature">[`minstd()`][@stdlib/random/base/minstd]</span><span class="delimiter">: </span><span class="description">A linear congruential pseudorandom number generator (LCG) based on Park and Miller.</span> 76 - <span class="signature">[`mt19937()`][@stdlib/random/base/mt19937]</span><span class="delimiter">: </span><span class="description">A 32-bit Mersenne Twister pseudorandom number generator.</span> 77 - <span class="signature">[`negativeBinomial( r, p )`][@stdlib/random/base/negative-binomial]</span><span class="delimiter">: </span><span class="description">negative binomially distributed pseudorandom numbers.</span> 78 - <span class="signature">[`normal( mu, sigma )`][@stdlib/random/base/normal]</span><span class="delimiter">: </span><span class="description">normally distributed pseudorandom numbers.</span> 79 - <span class="signature">[`pareto1( alpha, beta )`][@stdlib/random/base/pareto-type1]</span><span class="delimiter">: </span><span class="description">Pareto (Type I) distributed pseudorandom numbers.</span> 80 - <span class="signature">[`poisson( lambda )`][@stdlib/random/base/poisson]</span><span class="delimiter">: </span><span class="description">Poisson distributed pseudorandom numbers.</span> 81 - <span class="signature">[`randi()`][@stdlib/random/base/randi]</span><span class="delimiter">: </span><span class="description">pseudorandom numbers having integer values.</span> 82 - <span class="signature">[`randn()`][@stdlib/random/base/randn]</span><span class="delimiter">: </span><span class="description">standard normally distributed pseudorandom numbers.</span> 83 - <span class="signature">[`randu()`][@stdlib/random/base/randu]</span><span class="delimiter">: </span><span class="description">uniformly distributed pseudorandom numbers between 0 and 1.</span> 84 - <span class="signature">[`rayleigh( sigma )`][@stdlib/random/base/rayleigh]</span><span class="delimiter">: </span><span class="description">Rayleigh distributed pseudorandom numbers.</span> 85 - <span class="signature">[`reviveBasePRNG( key, value )`][@stdlib/random/base/reviver]</span><span class="delimiter">: </span><span class="description">revive a JSON-serialized pseudorandom number generator (PRNG).</span> 86 - <span class="signature">[`t( v )`][@stdlib/random/base/t]</span><span class="delimiter">: </span><span class="description">Student's t-distributed pseudorandom numbers.</span> 87 - <span class="signature">[`triangular( a, b, c )`][@stdlib/random/base/triangular]</span><span class="delimiter">: </span><span class="description">triangular distributed pseudorandom numbers.</span> 88 - <span class="signature">[`uniform( a, b )`][@stdlib/random/base/uniform]</span><span class="delimiter">: </span><span class="description">uniformly distributed pseudorandom numbers.</span> 89 - <span class="signature">[`weibull( k, lambda )`][@stdlib/random/base/weibull]</span><span class="delimiter">: </span><span class="description">Weibull distributed pseudorandom numbers.</span> 90 91 </div> 92 93 <!-- </toc> --> 94 95 Attached to each PRNG are the following properties: 96 97 - **NAME**: the generator name. 98 - **seed**: the value used to seed the PRNG. 99 - **seedLength**: the length of the PRNG seed. 100 - **state**: the PRNG state. 101 - **stateLength**: the length of the PRNG state. 102 - **byteLength**: the size of the PRNG state. 103 - **PRNG**: the underlying pseudorandom number generator. 104 105 Additionally, attached to each PRNG is a `.factory()` method which supports creating a seeded PRNG and thus generating a reproducible sequence of pseudorandom numbers. 106 107 ```javascript 108 var rand; 109 var v; 110 var i; 111 112 // Generate pseudorandom values... 113 for ( i = 0; i < 100; i++ ) { 114 v = random.randu(); 115 } 116 117 // Generate the same pseudorandom values... 118 rand = random.randu.factory({ 119 'seed': random.randu.seed 120 }); 121 for ( i = 0; i < 100; i++ ) { 122 v = rand(); 123 } 124 ``` 125 126 For parameterized PRNGs, the `.factory()` method supports specifying parameters upon either PRNG creation or invocation. For example, 127 128 ```javascript 129 // Create a PRNG which requires providing parameters at each invocation: 130 var rand = random.normal.factory({ 131 'seed': 12345 132 }); 133 134 var r = rand( 1.0, 2.0 ); 135 // returns <number> 136 137 // Create a PRNG with fixed parameters: 138 rand = random.normal.factory( 1.0, 2.0, { 139 'seed': 12345 140 }); 141 142 r = rand(); 143 // returns <number> 144 ``` 145 146 </section> 147 148 <!-- /.usage --> 149 150 <section class="examples"> 151 152 ## Examples 153 154 <!-- TODO: better examples => generate histograms for several different PRNGs and compare to expected shape --> 155 156 <!-- eslint no-undef: "error" --> 157 158 ```javascript 159 var objectKeys = require( '@stdlib/utils/keys' ); 160 var random = require( '@stdlib/random/base' ); 161 162 console.log( objectKeys( random ) ); 163 ``` 164 165 </section> 166 167 <!-- /.examples --> 168 169 <section class="links"> 170 171 <!-- <toc-links> --> 172 173 [@stdlib/random/base/arcsine]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/arcsine 174 175 [@stdlib/random/base/bernoulli]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/bernoulli 176 177 [@stdlib/random/base/beta]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/beta 178 179 [@stdlib/random/base/betaprime]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/betaprime 180 181 [@stdlib/random/base/binomial]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/binomial 182 183 [@stdlib/random/base/box-muller]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/box-muller 184 185 [@stdlib/random/base/cauchy]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/cauchy 186 187 [@stdlib/random/base/chi]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/chi 188 189 [@stdlib/random/base/chisquare]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/chisquare 190 191 [@stdlib/random/base/cosine]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/cosine 192 193 [@stdlib/random/base/discrete-uniform]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/discrete-uniform 194 195 [@stdlib/random/base/erlang]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/erlang 196 197 [@stdlib/random/base/exponential]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/exponential 198 199 [@stdlib/random/base/f]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/f 200 201 [@stdlib/random/base/frechet]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/frechet 202 203 [@stdlib/random/base/gamma]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/gamma 204 205 [@stdlib/random/base/geometric]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/geometric 206 207 [@stdlib/random/base/gumbel]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/gumbel 208 209 [@stdlib/random/base/hypergeometric]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/hypergeometric 210 211 [@stdlib/random/base/improved-ziggurat]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/improved-ziggurat 212 213 [@stdlib/random/base/invgamma]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/invgamma 214 215 [@stdlib/random/base/kumaraswamy]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/kumaraswamy 216 217 [@stdlib/random/base/laplace]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/laplace 218 219 [@stdlib/random/base/levy]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/levy 220 221 [@stdlib/random/base/logistic]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/logistic 222 223 [@stdlib/random/base/lognormal]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/lognormal 224 225 [@stdlib/random/base/minstd-shuffle]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/minstd-shuffle 226 227 [@stdlib/random/base/minstd]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/minstd 228 229 [@stdlib/random/base/mt19937]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/mt19937 230 231 [@stdlib/random/base/negative-binomial]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/negative-binomial 232 233 [@stdlib/random/base/normal]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/normal 234 235 [@stdlib/random/base/pareto-type1]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/pareto-type1 236 237 [@stdlib/random/base/poisson]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/poisson 238 239 [@stdlib/random/base/randi]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/randi 240 241 [@stdlib/random/base/randn]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/randn 242 243 [@stdlib/random/base/randu]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/randu 244 245 [@stdlib/random/base/rayleigh]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/rayleigh 246 247 [@stdlib/random/base/reviver]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/reviver 248 249 [@stdlib/random/base/t]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/t 250 251 [@stdlib/random/base/triangular]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/triangular 252 253 [@stdlib/random/base/uniform]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/uniform 254 255 [@stdlib/random/base/weibull]: https://www.npmjs.com/package/@stdlib/random/tree/main/base/weibull 256 257 <!-- </toc-links> --> 258 259 </section> 260 261 <!-- /.links -->