Random number generators

Detailed Description

Generate random numbers according to various distributions.

Note:: The random number generators are not thread-safe. This isn't generally a problem, unless you are using the pseudo-random sequences. In that case, you need to lock the state variable you are using when generating random numbers.

Enumerations

enum RANDOMTYPE {
  RT_INVALID = -1, RT_DEGENERATE, RT_UNIFORM, RT_NORMAL,
  RT_LOGNORMAL, RT_BERNOULLI, RT_PARETO, RT_EXPONENTIAL,
  RT_SAMPLED, RT_RAYLEIGH, RT_WEIBULL, RT_GAMMA,
  RT_BETA, RT_TRIANGLE, RT_INVALID = -1, RT_DEGENERATE,
  RT_UNIFORM, RT_NORMAL, RT_LOGNORMAL, RT_BERNOULLI,
  RT_PARETO, RT_EXPONENTIAL, RT_SAMPLED, RT_RAYLEIGH,
  RT_WEIBULL
}

Functions

double pseudorandom_value (RANDOMTYPE type, unsigned int *state,...)

Generate a pseudo-random value using the known state that is updated.

int random_apply (char *group_expression, char *property, RANDOMTYPE type,...)

Apply a random number to property of a group of objects.

double random_bernoulli (double p)

Generate a Bernoulli distributed random number.

double random_beta (double alpha, double beta)

Generate a Beta distributed random number.

double random_degenerate (double a)

Generate the same number always.

double random_exponential (double lambda)

Generate an exponentially distributed random number.

double random_gamma (double alpha, double beta)

Generate a Gamma distributed random number.

double random_lognormal (double gmu, double gsigma)

Generate a log Gaussian distributed random number.

int random_nargs (char *name)

Gets the number of arguments required by distribution (0=failed, -1=variable).

double random_normal (double m, double s)

Generate a Gaussian distributed random number.

double random_pareto (double m, double k)

Generate a Pareto distributed random number.

double random_rayleigh (double sigma)

Generate a Rayleigh distributed random number.

double random_sampled (unsigned n, double *x)

Generate a number randomly sample uniformly from a list.

int random_test (void)

Test random distributions.

double random_triangle (double a, double b)

Generate a symmetric triangle distributed random number.

RANDOMTYPE random_type (char *name)

Converts a distribution name to a RANDOMTYPE.

double random_uniform (double a, double b)

Generate a uniformly distributed random number.

double random_value (RANDOMTYPE type,...)

Generate a random value.

double random_weibull (double lambda, double k)

Generate a Weibull distributed random number.

int randwarn ()

randwarn checks to see if non-determinism warning is necessary

Enumeration Type Documentation

enum RANDOMTYPE

Enumerator:

RT_INVALID	used to flag bad random types
RT_DEGENERATE	degenerate distribution (Dirac delta function); double only_value
RT_UNIFORM	uniform distribution; double minimum_value, double maximum_value
RT_NORMAL	normal distribution; double arithmetic_mean, double arithmetic_stdev
RT_LOGNORMAL	log-normal distribution; double geometric_mean, double geometric_stdev
RT_BERNOULLI	Bernoulli distribution; double probability_of_observing_1.
RT_PARETO	Pareto distribution; double minimum_value, double gamma_scale.
RT_EXPONENTIAL	exponential distribution; double coefficient, double k_scale
RT_SAMPLED	sampled distribution; unsigned number_of_samples, double samples[n_samples]
RT_RAYLEIGH	Rayleigh distribution; double sigma.
RT_WEIBULL	Weibull distribution; double lambda, double k.
RT_GAMMA	Gamma distribution; double alpha, double beta.
RT_BETA	Beta distribution; double alpha, double beta.
RT_TRIANGLE	Triangle distribution; double a, double b.
RT_INVALID	used to flag bad random types
RT_DEGENERATE	degenerate distribution (Dirac delta function); double only_value
RT_UNIFORM	uniform distribution; double minimum_value, double maximum_value
RT_NORMAL	normal distribution; double arithmetic_mean, double arithmetic_stdev
RT_LOGNORMAL	log-normal distribution; double geometric_mean, double geometric_stdev
RT_BERNOULLI	Bernoulli distribution; double probability_of_observing_1.
RT_PARETO	Pareto distribution; double minimum_value, double gamma_scale.
RT_EXPONENTIAL	exponential distribution; double coefficient, double k_scale
RT_SAMPLED	sampled distribution; unsigned number_of_samples, double samples[n_samples]
RT_RAYLEIGH	Rayleigh distribution; double sigma.
RT_WEIBULL	Weibull distribution; double lambda, double k.

Definition at line 14 of file random.h.

Function Documentation

double pseudorandom_value	(	RANDOMTYPE	type,
		unsigned int *	state,
			...
	)

Generate a pseudo-random value using the known state that is updated.

Returns:: a double containing the random number

Parameters:

type	the type of distribution desired
state	the state of the random number generator

Definition at line 608 of file random.c.

Referenced by random_test().

int random_apply	(	char *	group_expression,
		char *	property,
		RANDOMTYPE	type,
			...
	)

Apply a random number to property of a group of objects.

Returns:: the number of objects changed

Parameters:

group_expression	the group definition; see find_objects()
property	the property to update
type	the distribution type

Definition at line 571 of file random.c.

References find_first(), find_next(), and find_objects().

double random_bernoulli ( double p )

Generate a Bernoulli distributed random number.

The probability density function for the Bernoulli distribution is

$Prob\left\{x=1\right\} = 1-Prob\left\{x=0\right\} = p$

Note that the Bernoulli distribution is a discrete distribution.

Parameters:

p	the probability of generating a 1

Definition at line 238 of file random.c.

References output_warning().

Referenced by random_test().

double random_beta	(	double	alpha,
		double	beta
	)

Generate a Beta distributed random number.

The Beta probability density function is

$\varphi \left( x; \alpha,\beta\right) = \frac{\Gamma(\alpha+\beta)}{\Gamma(\alpha) \Gamma(\beta)} x^(\alpha-1) (1-x)^{\beta-1}$

Parameters:

beta

event parameters

Definition at line 467 of file random.c.

References random_gamma().

Referenced by random_test().

double random_degenerate ( double a )

Generate the same number always.

This is the Dirac delta function:

The probability density function for the Dirac delta function

$\varphi\left(a\right) = 1.0$

Definition at line 142 of file random.c.

References output_warning().

Referenced by random_test().

double random_exponential ( double lambda )

Generate an exponentially distributed random number.

The exponential probability density function is

$\varphi\left(x\right) = \left\{ \begin{array}{c c} \lambda e^{-\lambda x} & x \geq o \\ 0 & x < 0 \end{array} \right\}$

Parameters:

lambda

the rate parameter lambda

Definition at line 351 of file random.c.

References output_warning(), and throw_exception().

Referenced by random_test().

double random_gamma	(	double	alpha,
		double	beta
	)

Generate a Gamma distributed random number.

The Gamma probability density function is

$\varphi \left( x; \alpha,\beta\right) = \frac{1}{\Gamma(\alpha) \beta^\alpha} x^{\alpha-1} e^{-x/\beta}$

Definition at line 412 of file random.c.

Referenced by random_beta(), and random_test().

double random_lognormal	(	double	gmu,
		double	gsigma
	)

Generate a log Gaussian distributed random number.

The log-normal probability density function is

$\varphi\left(x\right) = \frac{1}{\sqrt{2\pi}x\sigma}e^{\frac{\left(\ln x-\mu\right)^2}{2\sigma^2}}$

Parameters:

gmu	the geometric mean
gsigma	the geometric standard deviation

Definition at line 334 of file random.c.

References random_normal().

Referenced by random_test().

double random_normal	(	double	m,
		double	s
	)

Generate a Gaussian distributed random number.

The probability density function for the Gaussian (normal) distribution is

$\varphi\left(x\right) = \frac{1}{\sqrt{2\pi}\sigma}e^{\frac{\left(x-\mu\right)^2}{2\sigma^2}}$

Normally distributed random numbers are generated using the Box-Muller method:

    double random_normal(double m, double s)
    {
        double r, a, b;
        do { 
            a = 2*randunit()-1;
            b = 2*randunit()-1;
            r = a*a+b*b;
        } while (r>=1);
        return sqrt(-2*log(r)/r)*a*r*s+m;
    }

Parameters:

m	the mean of the distribution
s	the standard deviation of the distribution

Definition at line 215 of file random.c.

References output_warning().

Referenced by random_lognormal(), random_test(), and sample_from_diversity().

double random_pareto	(	double	m,
		double	k
	)

Generate a Pareto distributed random number.

The Pareto distribution is one in which the probability of drawing a number less than x is proportional to x^k. The probability density function of the Pareto distribution is

$\varphi\left( x<k \right) = k \frac{m^k}{x^{k+1}} x \geq m$

The cumulative density function is

$\varphi\left( x<k \right) = 1-(\frac{m}{x})^k$

.

Parameters:

m	the minimum value
k	the k value

Definition at line 300 of file random.c.

References output_warning(), and throw_exception().

Referenced by random_test().

double random_rayleigh ( double sigma )

Generate a Rayleigh distributed random number.

The Rayleigh probability density function is

$\varphi \left( x;\sigma \right) = \frac{x e^{-\frac{x^2}{2\sigma^2}} }{\sigma^2}$

Parameters:

sigma

mode parameter

Definition at line 400 of file random.c.

Referenced by random_test().

double random_sampled	(	unsigned	n,
		double *	x
	)

Generate a number randomly sample uniformly from a list.

The probability that the value a is drawn from the sample is

$Prob\left\{x=a\right\} = \frac{1}{n}$

Note that the sampled distriution is a discrete distribution.

Parameters:

n	the number of samples in the list
x	the sample list

Definition at line 265 of file random.c.

References output_warning(), and throw_exception().

Referenced by random_test().

int random_test ( void )

Test random distributions.

To run the self-test, use the --randtest command-line argument. The test results are output to the file specified by the global_testoutputfile variable.

Returns:: number of failed tests

Definition at line 702 of file random.c.

References max, min, output_error(), output_test(), output_verbose(), pseudorandom_value(), random_bernoulli(), random_beta(), random_degenerate(), random_exponential(), random_gamma(), random_lognormal(), random_normal(), random_pareto(), random_rayleigh(), random_sampled(), random_triangle(), random_uniform(), random_value(), and RT_NORMAL.

Referenced by cmdarg_load().

double random_triangle	(	double	a,
		double	b
	)

Generate a symmetric triangle distributed random number.

The triangle probability density function is

$\varphi\left(x|a,b\right) = \left\{ \begin{array}{c c} \frac{4(x-a)}{(b-a)^2} & a < x \leq (a+b)/2 \\ \frac{4(b-x)}{(b-a)^2} & (a+b)/2 < x \leq b \\ 0 & x \leq a | x > b \end{array} \right\}$

Definition at line 490 of file random.c.

Referenced by convert_to_loadshape(), and random_test().

RANDOMTYPE random_type ( char * name )

Converts a distribution name to a RANDOMTYPE.

Parameters:

name

the name of the distribution

Definition at line 78 of file random.c.

References RT_INVALID.

double random_uniform	(	double	a,
		double	b
	)

Generate a uniformly distributed random number.

The probability density function for the uniform distribution is

$\varphi\left(x\right) = \left\{ \begin{array}{c c} \frac{1}{b-a} & a \leq x < b \\ 0 & x<a ; x\geq b \end{array} \right\}$

Note that this uniform distribution includes a but does not include b.

Parameters:

a	the minimum number
b	the maximum number

Definition at line 168 of file random.c.

References output_warning().

Referenced by loadshape_init(), and random_test().

double random_value	(	RANDOMTYPE	type,
			...
	)

Generate a random value.

Returns:: a double containing the random number

Parameters:

type

the type of distribution desired

Definition at line 594 of file random.c.

Referenced by random_test().

double random_weibull	(	double	lambda,
		double	k
	)

Generate a Weibull distributed random number.

The Weibull probability density function is

$\varphi\left(x;k,\lambda\right) = \frac{k}{\lambda} \left( \frac{x}{\lambda} \right)^{k-1} e^{-\left(\frac{x}{\lambda}\right)^k}$

Note:: This distribution is not tested because the test requires the Gamma function, which itself would have to be implemented and tested.

Parameters:

lambda	scale parameter
k	rate shape parameter

Definition at line 380 of file random.c.

References throw_exception().


Enumerations
enum	RANDOMTYPE { RT_INVALID = -1, RT_DEGENERATE, RT_UNIFORM, RT_NORMAL, RT_LOGNORMAL, RT_BERNOULLI, RT_PARETO, RT_EXPONENTIAL, RT_SAMPLED, RT_RAYLEIGH, RT_WEIBULL, RT_GAMMA, RT_BETA, RT_TRIANGLE, RT_INVALID = -1, RT_DEGENERATE, RT_UNIFORM, RT_NORMAL, RT_LOGNORMAL, RT_BERNOULLI, RT_PARETO, RT_EXPONENTIAL, RT_SAMPLED, RT_RAYLEIGH, RT_WEIBULL }
Functions
double	pseudorandom_value (RANDOMTYPE type, unsigned int *state,...)
	Generate a pseudo-random value using the known state that is updated.
int	random_apply (char group_expression, char property, RANDOMTYPE type,...)
	Apply a random number to property of a group of objects.
double	random_bernoulli (double p)
	Generate a Bernoulli distributed random number.
double	random_beta (double alpha, double beta)
	Generate a Beta distributed random number.
double	random_degenerate (double a)
	Generate the same number always.
double	random_exponential (double lambda)
	Generate an exponentially distributed random number.
double	random_gamma (double alpha, double beta)
	Generate a Gamma distributed random number.
double	random_lognormal (double gmu, double gsigma)
	Generate a log Gaussian distributed random number.
int	random_nargs (char *name)
	Gets the number of arguments required by distribution (0=failed, -1=variable).
double	random_normal (double m, double s)
	Generate a Gaussian distributed random number.
double	random_pareto (double m, double k)
	Generate a Pareto distributed random number.
double	random_rayleigh (double sigma)
	Generate a Rayleigh distributed random number.
double	random_sampled (unsigned n, double *x)
	Generate a number randomly sample uniformly from a list.
int	random_test (void)
	Test random distributions.
double	random_triangle (double a, double b)
	Generate a symmetric triangle distributed random number.
RANDOMTYPE	random_type (char *name)
	Converts a distribution name to a RANDOMTYPE.
double	random_uniform (double a, double b)
	Generate a uniformly distributed random number.
double	random_value (RANDOMTYPE type,...)
	Generate a random value.
double	random_weibull (double lambda, double k)
	Generate a Weibull distributed random number.
int	randwarn ()
	randwarn checks to see if non-determinism warning is necessary