abLEMON 1.9.0-101-gccb8629
A maintained fork of LEMON
Loading...
Searching...
No Matches
Random< Word > Class Template Reference

Mersenne Twister random number generator. More...

#include <lemon/random.h>

Public Member Functions

Initialization
 Random ()
 Default constructor.
template< typename Number >
 Random (Number seed)
 Constructor with seed.
template< typename Iterator >
 Random (Iterator begin, Iterator end)
 Constructor with array seeding.
 Random (const Random &other)
 Copy constructor.
Random & operator= (const Random &other)
 Assign operator.
template< typename Number >
void seed (Number seed)
 Seeding random sequence.
template< typename Iterator >
void seed (Iterator begin, Iterator end)
 Seeding random sequence.
bool seed ()
 Seeding from the random device or from the time.
bool seedFromFile (const std::string &file="/dev/urandom", int offset=0)
 Seeding from file.
bool seedFromTime ()
 Seeding from the time.
Uniform Distributions
template< typename Number >
Number real ()
 Returns a random real number from the range [0, 1).
double operator() ()
 Returns a random real number from the range [0, 1).
double operator() (double b)
 Returns a random real number from the range [0, b).
double operator() (double a, double b)
 Returns a random real number from the range [a, b).
template< typename Number >
Number integer (Number b)
 Returns a random integer from a range.
template< typename Number >
Number integer (Number a, Number b)
 Returns a random integer from a range.
template< typename Number >
Number operator[] (Number b)
 Returns a random integer from a range.
template< typename Number >
Number uinteger ()
 Returns a random non-negative integer.
template< typename Number >
Number integer ()
 Returns a random integer.
bool boolean ()
 Returns a random bool.
Non-uniform Distributions
bool boolean (double p)
 Returns a random bool with given probability of true result.
double gauss ()
 Standard normal (Gauss) distribution.
double gauss (double mean, double std_dev)
 Normal (Gauss) distribution with given mean and standard deviation.
double lognormal (double n_mean, double n_std_dev)
 Lognormal distribution.
double lognormal (const std::pair< double , double > &params)
 Lognormal distribution.
std::pair< double , double > lognormalParamsFromMD (double mean, double std_dev)
 Compute the lognormal parameters from mean and standard deviation.
double lognormalMD (double mean, double std_dev)
 Lognormal distribution with given mean and standard deviation.
double exponential (double lambda=1.0)
 Exponential distribution with given mean.
double gamma (int k)
 Gamma distribution with given integer shape.
double gamma (double k, double theta=1.0)
 Gamma distribution with given shape and scale parameter.
double weibull (double k, double lambda)
 Weibull distribution.
double pareto (double k, double x_min)
 Pareto distribution.
int poisson (double lambda)
 Poisson distribution.
Two-Dimensional Distributions
dim2::Point< double > disc ()
 Uniform distribution on the full unit circle.
dim2::Point< double > gauss2 ()
 A kind of two-dimensional normal (Gauss) distribution.
dim2::Point< double > exponential2 ()
 A kind of two-dimensional exponential distribution.

Detailed Description

template< class Word >
class lemon::_random_bits::Random< Word >

The Mersenne Twister is a twisted generalized feedback shift-register generator of Matsumoto and Nishimura. The period of this generator is \( 2^{19937} - 1\) and it is equi-distributed in 623 dimensions for 32-bit numbers. The time performance of this generator is comparable to the commonly used generators.

This is a template implementation of both 32-bit and 64-bit architecture optimized versions. The generators differ slightly in the initialization and generation phase so they produce two completely different sequences.

Warning
Do not use this class directly, but instead one of Random, Random32 or Random64.

The generator gives back random numbers of several types. To get a random number from a range of a floating point type, you can use one form of the operator() or the real() member function. If you want to get random number from the {0, 1, ..., n-1} integer range, use the operator[] or the integer() method. And to get random number from the whole range of an integer type, you can use the argumentless integer() or uinteger() functions. Finally, you can get random bool with equal chance of true and false or with given probability of true result using the boolean() member functions.

Various non-uniform distributions are also supported: normal (Gauss), exponential, gamma, Poisson, etc.; and a few two-dimensional distributions, too.

// The commented code is identical to the other
double a = rnd(); // [0.0, 1.0)
// double a = rnd.real(); // [0.0, 1.0)
double b = rnd( 100.0 ); // [0.0, 100.0)
// double b = rnd.real(100.0); // [0.0, 100.0)
double c = rnd( 1.0 , 2.0 ); // [1.0, 2.0)
// double c = rnd.real(1.0, 2.0); // [1.0, 2.0)
int d = rnd[ 100000 ]; // 0..99999
// int d = rnd.integer(100000); // 0..99999
int e = rnd[ 6 ] + 1; // 1..6
// int e = rnd.integer(1, 1 + 6); // 1..6
int b = rnd.uinteger< int >(); // 0 .. 2^31 - 1
int c = rnd.integer< int >(); // - 2^31 .. 2^31 - 1
bool g = rnd.boolean(); // P(g = true) = 0.5
bool h = rnd.boolean( 0.8 ); // P(h = true) = 0.8
Random rnd
Global random number generator instance.
Definition random.cc:29

LEMON provides a global instance of the random number generator: rnd. In most cases, it is a good practice to use this global generator to get random numbers.

See also
Random, Random32 or Random64.

Constructor & Destructor Documentation

◆ Random() [1/4]

template< class Word >
Random ( )
inline

Constructor with constant seeding.

◆ Random() [2/4]

template< class Word >
template< typename Number >
Random ( Number seed)
inline

Constructor with seed. The current number type will be converted to the architecture word type.

◆ Random() [3/4]

template< class Word >
template< typename Iterator >
Random ( Iterator begin,
Iterator end )
inline

Constructor with array seeding. The given range should contain any number type and the numbers will be converted to the architecture word type.

◆ Random() [4/4]

template< class Word >
Random ( const Random< Word > & other)
inline

Copy constructor. The generated sequence will be identical to the other sequence. It can be used to save the current state of the generator and later use it to generate the same sequence.

Member Function Documentation

◆ operator=()

template< class Word >
Random & operator= ( const Random< Word > & other)
inline

Assign operator. The generated sequence will be identical to the other sequence. It can be used to save the current state of the generator and later use it to generate the same sequence.

◆ seed() [1/3]

template< class Word >
template< typename Number >
void seed ( Number seed)
inline

Seeding the random sequence. The current number type will be converted to the architecture word type.

◆ seed() [2/3]

template< class Word >
template< typename Iterator >
void seed ( Iterator begin,
Iterator end )
inline

Seeding the random sequence. The given range should contain any number type and the numbers will be converted to the architecture word type.

◆ seed() [3/3]

template< class Word >
bool seed ( )
inline

By default, this function seeds the generator with words of std::random_device. If it does not succeed (e.g., the device throws), it uses the seedFromTime().

Returns
Currently always true.

◆ seedFromFile()

template< class Word >
bool seedFromFile ( const std::string & file = "/dev/urandom",
int offset = 0 )
inline

Seeding the random sequence from file. The linux kernel has two devices, /dev/random and /dev/urandom which could give good seed values for pseudo random generators (The difference between two devices is that the random may block the reading operation while the kernel can give good source of randomness, while the urandom does not block the input, but it could give back bytes with worse entropy).

Parameters
fileThe source file
offsetThe offset, from the file read.
Returns
true when the seeding successes.

◆ seedFromTime()

template< class Word >
bool seedFromTime ( )
inline

Seeding from the time. This function uses the current time of std::chrono::system_clock and of std::chrono::steady_clock for initialize the random sequence.

Returns
Currently always true.

◆ real()

template< class Word >
template< typename Number >
Number real ( )
inline

It returns a random real number from the range [0, 1). The default Number type is double.

◆ operator()() [1/3]

template< class Word >
double operator() ( )
inline

It returns a random double from the range [0, 1).

◆ operator()() [2/3]

template< class Word >
double operator() ( double b)
inline

It returns a random real number from the range [0, b).

◆ operator()() [3/3]

template< class Word >
double operator() ( double a,
double b )
inline

It returns a random real number from the range [a, b).

◆ integer() [1/3]

template< class Word >
template< typename Number >
Number integer ( Number b)
inline

It returns a random integer from the range {0, 1, ..., b - 1}.

◆ integer() [2/3]

template< class Word >
template< typename Number >
Number integer ( Number a,
Number b )
inline

It returns a random integer from the range {a, a + 1, ..., b - 1}.

◆ operator[]()

template< class Word >
template< typename Number >
Number operator[] ( Number b)
inline

It returns a random integer from the range {0, 1, ..., b - 1}.

◆ uinteger()

template< class Word >
template< typename Number >
Number uinteger ( )
inline

It returns a random non-negative integer uniformly from the whole range of the current Number type. The default result type of this function is unsigned int.

◆ integer() [3/3]

template< class Word >
template< typename Number >
Number integer ( )
inline

It returns a random integer uniformly from the whole range of the current Number type. The default result type of this function is int.

◆ boolean() [1/2]

template< class Word >
bool boolean ( )
inline

It returns a random bool. The generator holds a buffer for random bits. Every time when it become empty the generator makes a new random word and fill the buffer up.

◆ boolean() [2/2]

template< class Word >
bool boolean ( double p)
inline

It returns a random bool with given probability of true result.

◆ gauss() [1/2]

template< class Word >
double gauss ( )
inline

Standard normal (Gauss) distribution.

Note
The Cartesian form of the Box-Muller transformation is used to generate a random normal distribution.

◆ gauss() [2/2]

template< class Word >
double gauss ( double mean,
double std_dev )
inline

Normal (Gauss) distribution with given mean and standard deviation.

See also
gauss()

◆ lognormal() [1/2]

template< class Word >
double lognormal ( double n_mean,
double n_std_dev )
inline

Lognormal distribution. The parameters are the mean and the standard deviation of exp(X).

◆ lognormal() [2/2]

template< class Word >
double lognormal ( const std::pair< double , double > & params)
inline

Lognormal distribution. The parameter is an std::pair of the mean and the standard deviation of exp(X).

◆ lognormalParamsFromMD()

template< class Word >
std::pair< double , double > lognormalParamsFromMD ( double mean,
double std_dev )
inline

This function computes the lognormal parameters from mean and standard deviation. The return value can direcly be passed to lognormal().

◆ lognormalMD()

template< class Word >
double lognormalMD ( double mean,
double std_dev )
inline

Lognormal distribution with given mean and standard deviation.

◆ exponential()

template< class Word >
double exponential ( double lambda = 1.0)
inline

This function generates an exponential distribution random number with mean 1/lambda.

◆ gamma() [1/2]

template< class Word >
double gamma ( int k)
inline

This function generates a gamma distribution random number.

Parameters
kshape parameter (k>0 integer)

◆ gamma() [2/2]

template< class Word >
double gamma ( double k,
double theta = 1.0 )
inline

This function generates a gamma distribution random number.

Parameters
kshape parameter (k>0)
thetascale parameter

◆ weibull()

template< class Word >
double weibull ( double k,
double lambda )
inline

This function generates a Weibull distribution random number.

Parameters
kshape parameter (k>0)
lambdascale parameter (lambda>0)

◆ pareto()

template< class Word >
double pareto ( double k,
double x_min )
inline

This function generates a Pareto distribution random number.

Parameters
kshape parameter (k>0)
x_minlocation parameter (x_min>0)

◆ poisson()

template< class Word >
int poisson ( double lambda)
inline

This function generates a Poisson distribution random number with parameter lambda.

The probability mass function of this distribusion is

\[ \frac{e^{-\lambda}\lambda^k}{k!} \]

Note
The algorithm is taken from the book of Donald E. Knuth titled ''Seminumerical Algorithms'' (1969). Its running time is linear in the return value.

◆ disc()

template< class Word >
dim2::Point< double > disc ( )
inline

Uniform distribution on the full unit circle.

◆ gauss2()

template< class Word >
dim2::Point< double > gauss2 ( )
inline

This function provides a turning symmetric two-dimensional distribution. The two coordinates are independent and of standard normal distribution.

Note
The coordinates are the two random variables provided by the polar form of the Box-Muller method.

◆ exponential2()

template< class Word >
dim2::Point< double > exponential2 ( )
inline

This function provides a turning symmetric two-dimensional distribution. For \((V_1, V_2)\) uniform in the unit disc and \(S = V_1^2 + V_2^2\), it returns \(-\ln(S)/S \cdot (V_1, V_2)\): its direction is uniform, and its distance from the origin is \(-\ln(S)/\sqrt{S}\) with \(S\) uniform in \((0, 1)\), which exceeds \(r\) with the probability \(u\) such that \(-\ln(u)/\sqrt{u} = r\) (not an exponential distribution).