Random Variate Generation Routines

This module provides facilities for basic pseudo-random number generation, and for generation of random variates from various common distributions.

All the random generation procedures use the same underlying "stream" of random numbers. This stream is generated using the nrand48 pseudo-random generation procedure found on most Unix systems, with the output being combined with a limited supply of real random numbers from the file "randfile" in the source directory for this software, in order to reduce the chances that the pseudo-random numbers aren't random enough.

A pseudo-random number stream is determined by an integer seed, which is typically set by the user for each experimental run (eg, to 1, 2, 3, etc. for successive runs). The state of the random number stream can be saved in a structure of type rand_state, and later restored. For example, the state could be saved in a file at the end of a run, and restored if it is later decided that the run should be continued for longer.

The methods for generating random variates from various distributions are mostly taken from the following reference:

Devroye, L. (1986) Non-Uniform Random Variate Generation, New York: Springer-Verlag.

Header file required: rand.h

void rand_seed
( int seed;  /* Seed to set state based on */
)

Sets the random number generator to a state that is determined from the integer seed. Setting the seed the same on two occasions, and then calling exactly the same sequence of random generation procedures, should produce exactly the same sequence of random variates. (Note: this may not be true, however, if computers with different architectures are used on the two occasions.)

Sequential seeds should produce streams that are pretty much independent (unlike the situation for some pseudo-random number generators). Setting the seed randomly according to the time or day, or some such, without recording what it was, is not recommended, since the results are then not reproducible.

rand_state *rand_get_state (void)

void rand_use_state 
( rand_state *state  /* Pointer to a previously saved state */
)

double rand_uniform (void)

double rand_uniopen (void)

int rand_int 
( int n  /* Number of integers (from 0) to pick from */
)

Randomly picks an integer from the set { 0, 1, ..., n-1 }, with each integer being equally probable. The probabilities may become somewhat unequal, however, if n is very large, approaching 2³¹.

int rand_pickd
( double *p,  /* Array of probabilities, of length n */
  int n       /* Number of integers (from 0) to pick from */
)

Randomly picks an integer from the set { 0, 1, ..., n-1 }, with probabilities given by the array of double-precision numbers passed as the first argument. These numbers need not sum to one, but they must be non-negative, and must not all be zero. The actual probabilities used are obtained by dividing each number in this array by the sum of all the numbers.

If one of the probabilities is exactly zero, it is guaranteed that the corresponding integer will not be picked.

int rand_pickf
( float *p,  /* Array of probabilities, of length n */
  int n      /* Number of integers (from 0) to pick from */
)

This procedure is the same as rand_pickd except that the array giving the probabilities is an array of single-precision floating point numbers, rather than double-precision.

int rand_poisson
( double lambda  /* Mean of the Poisson distribution */
)

Generates a non-negative integer from the Poisson distribution with mean lambda.

int rand_permutation
( int *perm,  /* Place to store the permutation */
  int n       /* Number of integers to permute */
)

Stores a random permutation of the integers from 1 to n in the array perm, which must be at least n long. All permutations are equally likely.

double rand_gaussian (void)

Generates a random value drawn from the Gaussian (normal) distribution with mean zero and standard deviation one, whose density function is proportional to exp(-x²/2), with x being any real value.

double rand_logistic (void)

Generates a random value drawn from the logistic distribution with location parameter zero and width parameter one, whose density function is proportional to exp(-x) / [1 + exp(-x)]², with x being any real value.

double rand_cauchy (void)

Generates a random value drawn from the Cauchy distribution with centre at zero and width one, whose density function is proportional to 1 / (1+x²), with x being any real value.

double rand_gamma
( double A   /* Shape parameter */
)

Generates a random value drawn from the gamma distribution with positive shape parameter A, whose density function is proportional to x^A-1 exp(-x), with x being any positive real. This procedure will never return a value that is exactly zero.

double rand_exponential (void)

Generates a random value drawn from the exponential distribution with mean one, whose density function is exp(-x), with x being any positive real. This procedure will never return a value that is exactly zero.

Note: This is a common special case of the gamma distribution.

double rand_beta
( double A,  /* Parameters of distribution */
  double B
)

Generates a random value drawn from the beta distribution with positive parameters A and B, whose density function is proportional to x^A-1(1-x)^B-1, with x being any real in the interval (0,1). This procedure will never return a value that is exactly zero or exactly one.