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