Main Page Modules Class Hierarchy Compound List File List Compound Members

# Random number generation

## Continuous distributions

Docs is in the group documentation in index.h. Whatever you type here is ignored by Doxygen :-(
SIM_API double | uniform (double a, double b, int rng=0)
SIM_API double | exponential (double mean, int rng=0)
SIM_API double | normal (double mean, double stddev, int rng=0)
SIM_API double | truncnormal (double mean, double stddev, int rng=0)
SIM_API double | gamma_d (double alpha, double beta, int rng=0)
SIM_API double | beta (double alpha1, double alpha2, int rng=0)
SIM_API double | erlang_k (unsigned int k, double mean, int rng=0)
SIM_API double | chi_square (unsigned int k, int rng=0)
SIM_API double | student_t (unsigned int i, int rng=0)
SIM_API double | cauchy (double a, double b, int rng=0)
SIM_API double | triang (double a, double b, double c, int rng=0)
double | lognormal (double m, double s, int rng=0)
SIM_API double | weibull (double a, double b, int rng=0)
SIM_API double | pareto_shifted (double a, double b, double c, int rng=0)

## Discrete distributions

Docs is in the group documentation in index.h. Whatever you type here is ignored by Doxygen :-(
SIM_API int | intuniform (int a, int b, int rng=0)
int | bernoulli (double p, int rng=0)
SIM_API int | binomial (int n, double p, int rng=0)
SIM_API int | geometric (double p, int rng=0)
SIM_API int | negbinomial (int n, double p, int rng=0)
SIM_API int | poisson (double lambda, int rng=0)

## Compatibility

SIM_API double | genk_uniform (double gen_nr, double a, double b)
SIM_API double | genk_intuniform (double gen_nr, double a, double b)
SIM_API double | genk_exponential (double gen_nr, double p)
SIM_API double | genk_normal (double gen_nr, double mean, double variance)
SIM_API double | genk_truncnormal (double gen_nr, double mean, double variance)

## Random number generation.

Docs is in the group documentation in index.h. Whatever you type here is ignored by Doxygen :-(
SIM_API int | testrand ()
SIM_API long | opp_nextrand (long &seed)
SIM_API void | opp_randomize ()
SIM_API long | randseed ()
SIM_API long | randseed (long seed)
SIM_API long | intrand ()
SIM_API long | intrand (long r)
double | dblrand ()
SIM_API void | genk_opp_randomize (int gen_nr)
SIM_API long | genk_randseed (int gen_nr)
SIM_API long | genk_randseed (int gen_nr, long seed)
SIM_API long | genk_intrand (int gen_nr)
SIM_API long | genk_intrand (int gen_nr, long r)
double | genk_dblrand (int gen_nr)

## Detailed Description

Distributions

There are several functions which generate random variates from different distributions: uniform, exponential, normal, truncated normal, gamma, beta, Erlang, Weibull, Bernoulli, binomial, geometric, Poisson, and several more.

The functions rely on the random number generator described below.

The documentation of individual functions includes the generation method it uses. The description may refer to one of the following publications:

LawKelton: A.M. Law and W.D. Kelton, Simulation Modeling and Analysis, 3rd ed., McGraw Hill, 2000.

Banks: J. Banks: Handbook of Simulation, Wiley, 1998.

Random number generator

OMNeT++ currently has a 31-bit built-in pseudo random number generator (RNG) that gives long int (32-bit) values in the range 1...2^31-2, with a period length of 2^31-2.

The generator is a linear congruential generator (LCG), and uses the method x=(x * 75) mod (2^31-1). The testrand() method can be used to check if the generator works correctly. Required hardware is exactly 32-bit integer arithmetics.

OMNeT++ provides several independent random number generators (by default 32; this number is defined as NUM_RANDOM_GENERATORS in utils.h), identified by numbers. The generator number is usually the gen_nr argument to functions beginning with genk_.

Source: Raj Jain: The Art of Computer Systems Performance Analysis (John Wiley & Sons, 1991), pages 441-444, 455.

## Function Documentation

int bernoulli ( | double p,
| int rng = 0 )`[inline]`

Returns the result of a Bernoulli trial with probability p, that is, 1 with probability p and 0 with probability (1-p).

Generation is using elementary look-up.

Parameters:

  p | 0=<p<=1
  rng | the underlying random number generator

SIM_API double beta ( | double alpha1,
| double alpha2,
| int rng = 0 )

Returns a random variate from the beta distribution with parameters alpha1, alpha2.

Generation is using relationship to Gamma distribution: if Y1 has gamma distribution with alpha=alpha1 and beta=1 and Y2 has gamma distribution with alpha=alpha2 and beta=2, then Y = Y1/(Y1+Y2) has beta distribution with parameters alpha1 and alpha2.

Parameters:

  alpha1, alpha2 | >0
  rng | the underlying random number generator

SIM_API int binomial ( | int n,
| double p,
| int rng = 0 )

Returns a random integer from the binomial distribution with parameters n and p, that is, the number of successes in n independent trials with probability p.

Generation is using the relationship to Bernoulli distribution (runtime is proportional to n).

Parameters:

  n | n>=0
  p | 0<=p<=1
  rng | the underlying random number generator

SIM_API double cauchy ( | double a,
| double b,
| int rng = 0 )

Returns a random variate from the Cauchy distribution (also called Lorentzian distribution) with parameters a,b where b>0.

This is a continuous distribution describing resonance behavior. It also describes the distribution of horizontal distances at which a line segment tilted at a random angle cuts the x-axis.

Generation uses inverse transform.

Parameters:

  a |
  b | b>0
  rng | the underlying random number generator

SIM_API double chi_square ( | unsigned int k,
| int rng = 0 )

Returns a random variate from the chi-square distribution with k degrees of freedom. The chi-square distribution arises in statistics. If Yi are k independent random variates from the normal distribution with unit variance, then the sum-of-squares (sum(Yi^2)) has a chi-square distribution with k degrees of freedom.

The expected value of this distribution is k. Chi_square with parameter k is gamma-distributed with alpha=k/2, beta=2.

Generation is using relationship to gamma distribution.

Parameters:

  k | degrees of freedom, k>0
  rng | the underlying random number generator

double dblrand ( | )`[inline]`

| Produces random double in range 0.0...1.0 using generator 0.

SIM_API double erlang_k ( | unsigned int k,
| double mean,
| int rng = 0 )

Returns a random variate from the Erlang distribution with k phases and mean mean.

This is the sum of k mutually independent random variables, each with exponential distribution. Thus, the kth arrival time in the Poisson process follows the Erlang distribution.

Erlang with parameters m and k is gamma-distributed with alpha=k and beta=m/k.

Generation makes use of the fact that exponential distributions sum up to Erlang.

Parameters:

  k | number of phases, k>0
  mean | >0
  rng | the underlying random number generator

SIM_API double exponential ( | double mean,
| int rng = 0 )

Returns a random variate from the exponential distribution with the given mean (that is, with parameter lambda=1/mean).

Parameters:

  mean | mean value
  rng | the underlying random number generator

SIM_API double gamma_d ( | double alpha,
| double beta,
| int rng = 0 )

Returns a random variate from the gamma distribution with parameters alpha>0, beta>0.

Gamma is the generalization of the Erlang distribution for non-integer k values, which becomes the alpha parameter. The chi-square distribution is a special case of the gamma distribution.

The expected value of this distribution is beta/alpha; for special case alpha=1, it becomes the exponential distribution with mean=beta.

Generation method depends on the value of alpha:

- alpha=1: gamma_d(1,beta)=exponential(beta)
- 0<alpha<1: Acceptance-Rejection due to Ahrends/Dieter (see LawKelton page 463, Algo 1.-3.)
- alpha>1: Acceptance-Rejection due to Cheng (see LawKelton page 464, Algo 1.-4.)

Remarks:
  the name gamma_d is chosen to avoid ambiguity with a function of the same name

Parameters:

  alpha | >0
  beta | >0
  rng | the underlying random number generator

double genk_dblrand ( | int gen_nr )`[inline]`

| Produces random double in range 0.0...1.0 using generator gen_nr.

SIM_API double genk_exponential ( | double gen_nr,
| double p )

| DEPRECATED: use exponential() instead.

SIM_API long genk_intrand ( | int gen_nr,
| long r )

| Produces random integer in range 0...r-1 using generator gen_nr. (Assumes r << INTRAND_MAX.)

SIM_API long genk_intrand ( | int gen_nr )

| Produces random integer in the range 1...INTRAND_MAX using generator gen_nr.

SIM_API double genk_intuniform ( | double gen_nr,
| double a,
| double b )

| DEPRECATED: use intuniform() instead.

SIM_API double genk_normal ( | double gen_nr,
| double mean,
| double variance )

| DEPRECATED: use normal() instead.

SIM_API void genk_opp_randomize ( | int gen_nr )

| Initialize random number generator gen_nr with a random value.

SIM_API long genk_randseed ( | int gen_nr,
| long seed )

| Sets seed of generator gen_nr and returns old seed value. Zero is not allowed as a seed.

SIM_API long genk_randseed ( | int gen_nr )

| Returns current seed of generator gen_nr.

SIM_API double genk_truncnormal ( | double gen_nr,
| double mean,
| double variance )

| DEPRECATED: use truncnormal() instead.

SIM_API double genk_uniform ( | double gen_nr,
| double a,
| double b )

| DEPRECATED: use uniform() instead.

SIM_API int geometric ( | double p,
| int rng = 0 )

Returns a random integer from the geometric distribution with parameter p, that is, the number of independent trials with probability p until the first success.

This is the n=1 special case of the negative binomial distribution.

Generation uses inverse transform.

Parameters:

  p | 0<p<=1
  rng | the underlying random number generator

SIM_API long intrand ( | long r )

| Produces random integer in range 0...r-1 using generator 0. (Assumes r << INTRAND_MAX.)

SIM_API long intrand ( | )

| Produces random integer in the range 1...INTRAND_MAX using generator 0.

SIM_API int intuniform ( | int a,
| int b,
| int rng = 0 )

Returns a random integer with uniform distribution in the range [a,b], inclusive. (Note that the function can also return b.)

Parameters:

  a, b | the interval, a<b
  rng | the underlying random number generator

double lognormal ( | double m,
| double s,
| int rng = 0 )`[inline]`

Returns a random variate from the lognormal distribution with mean m and variance s>0.

Generation is using relationship to normal distribution.

Parameters:

  m | mean
  s | variance, s>0
  rng | the underlying random number generator

SIM_API int negbinomial ( | int n,
| double p,
| int rng = 0 )

Returns a random integer from the negative binomial distribution with parameters n and p, that is, the number of failures occurring before n successes in independent trials with probability p of success.

Generation is using the relationship to geometric distribution (runtime is proportional to n).

Parameters:

  n | n>=0
  p | 0<p<1
  rng | the underlying random number generator

SIM_API double normal ( | double mean,
| double stddev,
| int rng = 0 )

Returns a random variate from the normal distribution with the given mean and standard deviation.

Parameters:

  mean | mean of the normal distribution
  stddev | standard deviation of the normal distribution
  rng | the underlying random number generator

SIM_API long opp_nextrand ( | long & seed )

| Calculates the next random number with the given seed, and also updates the seed. This function makes it possible to use random number streams independent of the seeds built into OMNeT++.

SIM_API void opp_randomize ( | )

| Initialize random number generator 0 with a random value.

SIM_API double pareto_shifted ( | double a,
| double b,
| double c,
| int rng = 0 )

Returns a random variate from the shifted generalized Pareto distribution.

Generation uses inverse transform.

Parameters:

  a,b | the usual parameters for generalized Pareto
  c | shift parameter for left-shift
  rng | the underlying random number generator

SIM_API int poisson ( | double lambda,
| int rng = 0 )

Returns a random integer from the Poisson distribution with parameter lambda, that is, the number of arrivals over unit time where the time between successive arrivals follow exponential distribution with parameter lambda.

Lambda is also the mean (and variance) of the distribution.

Generation method depends on value of lambda:

- 0<lambda<=30: count number of events
- lambda>30: Acceptance-Rejection due to Atkinson (see Banks, page 166)

Parameters:

  lambda | > 0
  rng | the underlying random number generator

SIM_API long randseed ( | long seed )

| Sets seed of generator 0 and returns old seed value. Zero is not allowed as a seed.

SIM_API long randseed ( | )

| Returns current seed of generator 0.

SIM_API double student_t ( | unsigned int i,
| int rng = 0 )

Returns a random variate from the student-t distribution with i degrees of freedom. If Y1 has a normal distribution and Y2 has a chi-square distribution with k degrees of freedom then X = Y1 / sqrt(Y2/k) has a student-t distribution with k degrees of freedom.

Generation is using relationship to gamma and chi-square.

Parameters:

  i | degrees of freedom, i>0
  rng | the underlying random number generator

SIM_API int testrand ( | )

| Returns 1 if the random generator works OK. Keeps seed intact. It works by checking the following: starting with x[0]=1, x[10000]=1,043,618,065 must hold.

SIM_API double triang ( | double a,
| double b,
| double c,
| int rng = 0 )

Returns a random variate from the triangular distribution with parameters a <= b <= c.

Generation uses inverse transform.

Parameters:

  a, b, c | a <= b <= c
  rng | the underlying random number generator

SIM_API double truncnormal ( | double mean,
| double stddev,
| int rng = 0 )

Normal distribution truncated to nonnegative values. It is implemented with a loop that discards negative values until a nonnegative one comes. This means that the execution time is not bounded: a large negative mean with much smaller stddev is likely to result in a large number of iterations.

The mean and stddev parameters serve as parameters to the normal distribution before truncation. The actual random variate returned will have a different mean and standard deviation.

Parameters:

  mean | mean of the normal distribution
  stddev | standard deviation of the normal distribution
  rng | the underlying random number generator

SIM_API double uniform ( | double a,
| double b,
| int rng = 0 )

Returns a random variate with uniform distribution in the range [a,b).

Parameters:

  a, b | the interval, a<b
  rng | the underlying random number generator

SIM_API double weibull ( | double a,
| double b,
| int rng = 0 )

Returns a random variate from the Weibull distribution with parameters a, b > 0, where a is the "scale" parameter and b is the "shape" parameter. Sometimes Weibull is given with alpha and beta parameters, then alpha=b and beta=a.

The Weibull distribution gives the distribution of lifetimes of objects. It was originally proposed to quantify fatigue data, but it is also used in reliability analysis of systems involving a "weakest link," e.g. in calculating a device's mean time to failure.

When b=1, Weibull(a,b) is exponential with mean a.

Generation uses inverse transform.

Parameters:

  a | the "scale" parameter, a>0
  b | the "shape" parameter, b>0
  rng | the underlying random number generator