File: //usr/share/slsh/help/randfuns.hlp
rand_exp
SYNOPSIS
Generate exponentially distributed random numbers
USAGE
X = rand_exp([Rand_Type g,] beta [,num])
DESCRIPTION
This function generates random numbers that are distributed according
to an exponential distribution with parameter beta > 0. The
distribution's probability density is given by
P(x,beta) = (1/beta) exp(-x/beta)
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
NOTES
The exponential generator is commonly used to simulate waiting times
between events.
SEE ALSO
rand_new, rand_uniform
--------------------------------------------------------------
rand_int
SYNOPSIS
Generate random integers
USAGE
X = rand_int ([Rand_Type g,] imin, imax [,num])
DESCRIPTION
This function may be used to generate a random integer `X' such
that `imin <= X <= imax'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand, rand_new
--------------------------------------------------------------
rand_tdist
SYNOPSIS
Generate random numbers from the Student t distribution
USAGE
X = rand_tdist ([Rand_Type g,] nu [,num])
DESCRIPTION
This function generates random numbers that are distributed according
to the Student-t distribution with nu>0.0 degrees of freedom.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand_new, rand_chisq, rand_fdist
--------------------------------------------------------------
rand_fdist
SYNOPSIS
Generate random numbers from the F distribution
USAGE
X = rand_fdist ([Rand_Type g,], nu1, nu2 [,num])
DESCRIPTION
This function generates random numbers that are distributed according
to the F-distribution, which is the ratio of two chi-squared
distributed variates whose degrees of freedom are given by
`nu1' (numerator) and `nu2' (denominator).
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand_chisq, rand_tdist, rand_gauss, rand_new
--------------------------------------------------------------
rand_chisq
SYNOPSIS
Generate Chi-Square distributed random numbers
USAGE
X = rand_fdist ([Rand_Type g,] nu, [,num])
DESCRIPTION
This function generates random numbers that are distributed according
to the Chi-squared distribution with `nu > 0' degrees of freedom.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand_fdist, rand_tdist, rand_gauss, rand_new
--------------------------------------------------------------
rand_flat
SYNOPSIS
Generate uniformly distributed random numbers
USAGE
X = rand_fdist ([Rand_Type g,] xmin, xmax [,num])
DESCRIPTION
This function generates random double-precision floating point
numbers that are uniformly distributed in the range
`xmin<=X<xmax'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand_uniform_pos, rand_int, rand, rand_new
--------------------------------------------------------------
rand_gamma
SYNOPSIS
Generate Gamma distributed random numbers
USAGE
X = rand_gamma ([Rand_Type g,], k, theta [,num])
DESCRIPTION
This function returns random deviates that are Gamma-distributed
according to the probability density
P(x; k,theta) = x^(k-1)*exp(-x/theta)/(theta^k * Gamma(k))
where `k,theta>0.0'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_beta, rand_uniform, rand_binomial, rand_new
--------------------------------------------------------------
rand_binomial
SYNOPSIS
Generate random numbers from the binomial distribution
USAGE
X = rand_binomial ([Rand_Type g,], p, n, [,num])
DESCRIPTION
This function generates binomial distributed random numbers
according to the probability density
P(x;p,n) = n!/(k!*(n-k)!) * p^k * (1-p)^(n-k)
where `n' is a non-negative integer and `0<=p<=1'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_gamma, rand_poisson, rand_uniform, rand_new
--------------------------------------------------------------
rand_poisson
SYNOPSIS
Generate Poisson distributed random numbers
USAGE
k = rand_poisson ([Rand_Type g,] mu [,num])
DESCRIPTION
This function generates random unsigned integers that are
poisson-distributed according to the probability distribution
P(k;mu) = mu^k/k! * exp(-mu)
where `mu>0.0'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_gauss, rand_uniform, rand_binomial, rand_new
--------------------------------------------------------------
rand_geometric
SYNOPSIS
Generate random numbers from the geometric distribution
USAGE
k = rand_geometric ([Rand_Type g,] p [,num])
DESCRIPTION
This function generates random numbers that are distributed
according to a geometric distribution with a probability density
P(k; p) = p*(1-p)^(k-1)
where `0<=p<=1'
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_poisson, rand_exp, rand_gauss, rand_uniform, rand_new
--------------------------------------------------------------
rand_cauchy
SYNOPSIS
Generate random numbers from the Cauchy distribution
USAGE
X = rand_cauchy ([Rand_Type g,] gamma [,num])
DESCRIPTION
This function generates random numbers that are distributed
according to a cauchy-distribution with a probability density
P(x; gamma) = 1/(PI*gamma)/(1+(x/gamma)^2)
where `gamma>=0.0'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_gauss, rand_poisson, rand_exp, rand_new
--------------------------------------------------------------
rand_beta
SYNOPSIS
Generate random numbers from the beta distribution
USAGE
X = rand_fdist ([Rand_Type g,] a, b [,num])
DESCRIPTION
This function generates random numbers that are distributed
according to a Beta-distribution with a probability density
P(x; a,b) = x^(a-1)*(1-x)^(b-1)/B(a,b)
where `a, b > 0'.
SEE ALSO
rand_gamma, rand_binomial, rand_chisq
--------------------------------------------------------------
rand_gauss
SYNOPSIS
Generate gaussian-distributed random numbers
USAGE
X = rand_gauss ([Rand_Type g,] sigma [,num])
DESCRIPTION
This function generates gaussian random numbers with the specified
sigma and mean of 0 according to the probability density
P(x; sigma) = 1/sqrt(2*PI*sigma^2) * exp(-0.5*x^2/sigma^2)
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
NOTES
This implementation utilizes the Box-Muller algorithm.
SEE ALSO
rand_uniform, rand_poisson, rand_chisq, rand_gauss, rand_new
--------------------------------------------------------------
rand
SYNOPSIS
Generate random integers numbers
USAGE
X = rand ([Rand_Type g,] [,num])
DESCRIPTION
This function generates unsigned 32 bit randomly distributed
integers on the closed interval 0<=X<=0xFFFFFFFFUL.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_new, rand_int, rand_uniform, rand_flat
--------------------------------------------------------------
rand_uniform_pos
SYNOPSIS
Generate uniform positive random numbers
USAGE
X = rand_uniform_pos ([Rand_Type] [num])
DESCRIPTION
This function generates uniformly distributed random numbers in open
interval `0<X<1'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform, rand_new
--------------------------------------------------------------
rand_uniform
SYNOPSIS
Generate uniform random numbers
USAGE
X = rand_uniform ([Rand_Type g] [num])
DESCRIPTION
This function generates uniformly distributed double precision
numbers on the semi-closed interval `0<=r<1'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
SEE ALSO
rand_uniform_pos, rand_int, rand_flat, rand_new
--------------------------------------------------------------
srand
SYNOPSIS
Seed the random number generator
USAGE
srand ([Rand_Type g,] Array_Type seeds)
DESCRIPTION
This function may be used to seed an instance of a rand number
generator using the values of an array of an unsigned long integers.
If a generator (created by `rand_new') is specified as the first
argument, then is will be seeded; otherwise, the seeds will
get applied to the default generator.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
The `num' parameter indicates that `num' random values are to
be generated and returned as an array.
EXAMPLE
gen = rand_new ();
srand (gen, [_time(), _pid(), 0xFF80743]);
SEE ALSO
rand_new, rand, rand_uniform
--------------------------------------------------------------
rand_new
SYNOPSIS
Instantiate a new random number generator
USAGE
Rand_Type rand_new ([array-of-seeds])
DESCRIPTION
This function creates a new instance of the basic random number
generator. An optional array of 32 bit unsigned integers may be used
to seed the generator. By default, the generator is seeding using
the current time and process id. The `srand' function may also
be used to seed the generator. The generator created by the
`rand_new' function may be passed as the first argument to most
of the other functions in the module to indicate that this instance
should be used as the basic generator.
EXAMPLE
The following example shows how to create an array of 512 uniform
random numbers derived from the default instance of the basic
generator:
x = rand_uniform (512);
A specific instance of the generator may be created using the
`rand_new' function and used by `rand_uniform' as follows:
g = rand_new ([0x1234, 0x5678912, 0xEFAB1234]);
x = rand_uniform (g, 512);
NOTES
The generator is a hybrid one that sums the results of 3 separate
generators: George Marsaglia's MZRAN13 generator, a multiply with
carry generator (also by Marsaglia), and a product generator. The
combined generator has a 192 bit state and a period exceeding 10^46.
The resulting random sequences were tested using version 2.24.4 of
the dieharder random number testing program. The tests showed that
this generator performed better than the famous Marsenne
Twister (`mt19937') both in terms of randomness and speed. More
information about the test results may be found at
`http://www.jedsoft.org/slang/modules/rand.html'.
The `mt19937' generator is separately available via the GSL
module.
SEE ALSO
srand, rand_int, rand_uniform
--------------------------------------------------------------
rand_sample
SYNOPSIS
Randomly sample from one or more arrays
USAGE
(b1 [,b2,...]) = rand_sample ([Rand_Type g,] a1 [,a2,...], num);
DESCRIPTION
This function may be used to randomly sample `num' elements from
one or more arrays (`a1,...'). The arrays must be consistent in
the sense that they must have the same leading dimension, which is
the one to be sampled.
The optional first argument may be used to specify a different
instance of a random number generator. Otherwise, the default
generator will be used.
EXAMPLE
Suppose A is a 1-d array with 20 elements, and B is a 2d array with
dimensions [20,30]. Then
(A1, B1) = rand_sample (A, B, 5);
will produce a 1d array A1 with 5 elements and a 2d array B1 with
dimensions [5,30].
NOTES
The indices used to sample the arrays are created using the first
`num' elements of a random permutation of the integers
`[0:dim0-1]' where `dim0' is the size of the leading
dimension. The same set of indices are used for all the arrays.
Hence any correspondence between `a0[i,..]' and `a1[i,...'
will be preserved in the samples.
SEE ALSO
rand_permutation, rand_new
--------------------------------------------------------------
rand_permutation
SYNOPSIS
Generate a random permutation of integers
USAGE
p = rand_permutation ([Rand_Type g,] Int_Type n)
DESCRIPTION
This function may be used to generate a random permutation of the
sequence of integers `0,1,..,n-1'.
The optional parameter `g' may be used to
specify the underlying random number generator. See the
documentation for the `rand_new' function for more information.
SEE ALSO
rand_sample
--------------------------------------------------------------