1#d optgen_text \__newline__ The optional parameter \exmp{g} may be used to \ 2 \__newline__ specify the underlying random number generator. See the \ 3 \__newline__ documentation for the \sfun{rand_new} function for more information. 4#d optparm_text \optgen_text \ 5 \__newline__ The \exmp{num} parameter indicates that \exmp{num} random values are to \ 6 \__newline__ be generated and returned as an array. 7 8\function{rand_exp} 9\synopsis{Generate exponentially distributed random numbers} 10\usage{X = rand_exp([Rand_Type g,] beta [,num])} 11\description 12 This function generates random numbers that are distributed according 13 to an exponential distribution with parameter beta > 0. The 14 distribution's probability density is given by 15#v+ 16 P(x,beta) = (1/beta) exp(-x/beta) 17#v- 18 \optparm_text 19\notes 20 The exponential generator is commonly used to simulate waiting times 21 between events. 22\seealso{rand_new, rand_uniform} 23\done 24 25\function{rand_int} 26\synopsis{Generate random integers} 27\usage{X = rand_int ([Rand_Type g,] imin, imax [,num])} 28\description 29 This function may be used to generate a random integer \exmp{X} such 30 that \exmp{imin <= X <= imax}. 31 \optparm_text 32\seealso{rand_uniform, rand, rand_new} 33\done 34 35\function{rand_tdist} 36\synopsis{Generate random numbers from the Student t distribution} 37\usage{X = rand_tdist ([Rand_Type g,] nu [,num])} 38\description 39 This function generates random numbers that are distributed according 40 to the Student-t distribution with nu>0.0 degrees of freedom. 41 \optparm_text 42\seealso{rand_uniform, rand_new, rand_chisq, rand_fdist} 43\done 44 45\function{rand_fdist} 46\synopsis{Generate random numbers from the F distribution} 47\usage{X = rand_fdist ([Rand_Type g,], nu1, nu2 [,num])} 48\description 49 This function generates random numbers that are distributed according 50 to the F-distribution, which is the ratio of two chi-squared 51 distributed variates whose degrees of freedom are given by 52 \exmp{nu1} (numerator) and \exmp{nu2} (denominator). 53 \optparm_text 54\seealso{rand_uniform, rand_chisq, rand_tdist, rand_gauss, rand_new} 55\done 56 57\function{rand_chisq} 58\synopsis{Generate Chi-Square distributed random numbers} 59\usage{X = rand_fdist ([Rand_Type g,] nu, [,num])} 60\description 61 This function generates random numbers that are distributed according 62 to the Chi-squared distribution with \exmp{nu > 0} degrees of freedom. 63 \optparm_text 64\seealso{rand_uniform, rand_fdist, rand_tdist, rand_gauss, rand_new} 65\done 66 67\function{rand_flat} 68\synopsis{Generate uniformly distributed random numbers} 69\usage{X = rand_fdist ([Rand_Type g,] xmin, xmax [,num])} 70\description 71 This function generates random double-precision floating point 72 numbers that are uniformly distributed in the range 73 \exmp{xmin<=X<xmax}. 74 \optparm_text 75\seealso{rand_uniform, rand_uniform_pos, rand_int, rand, rand_new} 76\done 77 78\function{rand_gamma} 79\synopsis{Generate Gamma distributed random numbers} 80\usage{X = rand_gamma ([Rand_Type g,], k, theta [,num])} 81\description 82 This function returns random deviates that are Gamma-distributed 83 according to the probability density 84#v+ 85 P(x; k,theta) = x^(k-1)*exp(-x/theta)/(theta^k * Gamma(k)) 86#v- 87 where \exmp{k,theta>0.0}. 88 \optparm_text 89\seealso{rand_beta, rand_uniform, rand_binomial, rand_new} 90\done 91 92\function{rand_binomial} 93\synopsis{Generate random numbers from the binomial distribution} 94\usage{X = rand_binomial ([Rand_Type g,], p, n, [,num])} 95\description 96 This function generates binomial distributed random numbers 97 according to the probability density 98#v+ 99 P(x;p,n) = n!/(k!*(n-k)!) * p^k * (1-p)^(n-k) 100#v- 101 where \exmp{n} is a non-negative integer and \exmp{0<=p<=1}. 102 \optparm_text 103\seealso{rand_gamma, rand_poisson, rand_uniform, rand_new} 104\done 105 106\function{rand_poisson} 107\synopsis{Generate Poisson distributed random numbers} 108\usage{k = rand_poisson ([Rand_Type g,] mu [,num])} 109\description 110 This function generates random unsigned integers that are 111 poisson-distributed according to the probability distribution 112#v+ 113 P(k;mu) = mu^k/k! * exp(-mu) 114#v- 115 where \exmp{mu>0.0}. 116 \optparm_text 117\seealso{rand_gauss, rand_uniform, rand_binomial, rand_new} 118\done 119 120\function{rand_geometric} 121\synopsis{Generate random numbers from the geometric distribution} 122\usage{k = rand_geometric ([Rand_Type g,] p [,num])} 123\description 124 This function generates random numbers that are distributed 125 according to a geometric distribution with a probability density 126#v+ 127 P(k; p) = p*(1-p)^(k-1) 128#v- 129 where \exmp{0<=p<=1} 130 \optparm_text 131\seealso{rand_poisson, rand_exp, rand_gauss, rand_uniform, rand_new} 132\done 133 134\function{rand_cauchy} 135\synopsis{Generate random numbers from the Cauchy distribution} 136\usage{X = rand_cauchy ([Rand_Type g,] gamma [,num])} 137\description 138 This function generates random numbers that are distributed 139 according to a cauchy-distribution with a probability density 140#v+ 141 P(x; gamma) = 1/(PI*gamma)/(1+(x/gamma)^2) 142#v- 143 where \exmp{gamma>=0.0}. 144 \optparm_text 145\seealso{rand_gauss, rand_poisson, rand_exp, rand_new} 146\done 147 148\function{rand_beta} 149\synopsis{Generate random numbers from the beta distribution} 150\usage{X = rand_fdist ([Rand_Type g,] a, b [,num])} 151\description 152 This function generates random numbers that are distributed 153 according to a Beta-distribution with a probability density 154#v+ 155 P(x; a,b) = x^(a-1)*(1-x)^(b-1)/B(a,b) 156#v- 157 where \exmp{a, b > 0}. 158\seealso{rand_gamma, rand_binomial, rand_chisq} 159\done 160 161\function{rand_gauss} 162\synopsis{Generate gaussian-distributed random numbers} 163\usage{X = rand_gauss ([Rand_Type g,] sigma [,num])} 164\description 165 This function generates gaussian random numbers with the specified 166 sigma and mean of 0 according to the probability density 167#v+ 168 P(x; sigma) = 1/sqrt(2*PI*sigma^2) * exp(-0.5*x^2/sigma^2) 169#v- 170 \optparm_text 171\notes 172 This implementation utilizes the Box-Muller algorithm. 173\seealso{rand_uniform, rand_poisson, rand_chisq, rand_gauss, rand_new} 174\done 175 176\function{rand} 177\synopsis{Generate random integers numbers} 178\usage{X = rand ([Rand_Type g,] [,num])} 179\description 180 This function generates unsigned 32 bit randomly distributed 181 integers on the closed interval 0<=X<=0xFFFFFFFFUL. 182 \optparm_text 183\seealso{rand_new, rand_int, rand_uniform, rand_flat} 184\done 185 186\function{rand_uniform_pos} 187\synopsis{Generate uniform positive random numbers} 188\usage{X = rand_uniform_pos ([Rand_Type] [num])} 189\description 190 This function generates uniformly distributed random numbers in open 191 interval \exmp{0<X<1}. 192 \optparm_text 193\seealso{rand_uniform, rand_new} 194\done 195 196\function{rand_uniform} 197\synopsis{Generate uniform random numbers} 198\usage{X = rand_uniform ([Rand_Type g] [num])} 199\description 200 This function generates uniformly distributed double precision 201 numbers on the semi-closed interval \exmp{0<=r<1}. 202 \optparm_text 203\seealso{rand_uniform_pos, rand_int, rand_flat, rand_new} 204\done 205 206\function{srand} 207\synopsis{Seed the random number generator} 208\usage{srand ([Rand_Type g,] Array_Type seeds)} 209\description 210 This function may be used to seed an instance of a rand number 211 generator using the values of an array of an unsigned long integers. 212 If a generator (created by \ifun{rand_new}) is specified as the first 213 argument, then is will be seeded; otherwise, the seeds will 214 get applied to the default generator. 215 \optparm_text 216\example 217#v+ 218 gen = rand_new (); 219 srand (gen, [_time(), _pid(), 0xFF80743]); 220#v- 221\seealso{rand_new, rand, rand_uniform} 222\done 223 224\function{rand_new} 225\synopsis{Instantiate a new random number generator} 226\usage{Rand_Type rand_new ([array-of-seeds])} 227\description 228 This function creates a new instance of the basic random number 229 generator. An optional array of 32 bit unsigned integers may be used 230 to seed the generator. By default, the generator is seeding using 231 the current time and process id. The \ifun{srand} function may also 232 be used to seed the generator. The generator created by the 233 \ifun{rand_new} function may be passed as the first argument to most 234 of the other functions in the module to indicate that this instance 235 should be used as the basic generator. 236\example 237 The following example shows how to create an array of 512 uniform 238 random numbers derived from the default instance of the basic 239 generator: 240#v+ 241 x = rand_uniform (512); 242#v- 243 A specific instance of the generator may be created using the 244 \ifun{rand_new} function and used by \ifun{rand_uniform} as follows: 245#v+ 246 g = rand_new ([0x1234, 0x5678912, 0xEFAB1234]); 247 x = rand_uniform (g, 512); 248#v- 249\notes 250 The generator is a hybrid one that sums the results of 3 separate 251 generators: George Marsaglia's MZRAN13 generator, a multiply with 252 carry generator (also by Marsaglia), and a product generator. The 253 combined generator has a 192 bit state and a period exceeding 10^46. 254 255 The resulting random sequences were tested using version 2.24.4 of 256 the dieharder random number testing program. The tests showed that 257 this generator performed better than the famous Marsenne 258 Twister (\exmp{mt19937}) both in terms of randomness and speed. More 259 information about the test results may be found at 260 \url{http://www.jedsoft.org/slang/modules/rand.html}. 261 262 The \exmp{mt19937} generator is separately available via the GSL 263 module. 264\seealso{srand, rand_int, rand_uniform} 265\done 266 267\function{rand_sample} 268\synopsis{Randomly sample from one or more arrays} 269\usage{(b1 [,b2,...]) = rand_sample ([Rand_Type g,] a1 [,a2,...], num);} 270\description 271 This function may be used to randomly sample \exmp{num} elements from 272 one or more arrays (\exmp{a1,...}). The arrays must be consistent in 273 the sense that they must have the same leading dimension, which is 274 the one to be sampled. 275 276 The optional first argument may be used to specify a different 277 instance of a random number generator. Otherwise, the default 278 generator will be used. 279\example 280 Suppose A is a 1-d array with 20 elements, and B is a 2d array with 281 dimensions [20,30]. Then 282#v+ 283 (A1, B1) = rand_sample (A, B, 5); 284#v- 285 will produce a 1d array A1 with 5 elements and a 2d array B1 with 286 dimensions [5,30]. 287\notes 288 The indices used to sample the arrays are created using the first 289 \exmp{num} elements of a random permutation of the integers 290 \exmp{[0:dim0-1]} where \exmp{dim0} is the size of the leading 291 dimension. The same set of indices are used for all the arrays. 292 Hence any correspondence between \exmp{a0[i,..]} and \exmp{a1[i,...} 293 will be preserved in the samples. 294\seealso{rand_permutation, rand_new} 295\done 296 297\function{rand_permutation} 298\synopsis{Generate a random permutation of integers} 299\usage{p = rand_permutation ([Rand_Type g,] Int_Type n)} 300\description 301 This function may be used to generate a random permutation of the 302 sequence of integers \exmp{0,1,..,n-1}. 303 \optgen_text 304\seealso{rand_sample} 305\done 306