_random_bits::Random
Declared in lemon/random.h, in the group Miscellaneous Tools; the same class on the Doxygen site.
-
template< class Word >
class Random Mersenne Twister random number generator.
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.
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 thereal()member function. If you want to get random number from the {0, 1, …, n-1} integer range, use theoperator[] or theinteger()method. And to get random number from the whole range of an integer type, you can use the argumentlessinteger()oruinteger()functions. Finally, you can get random bool with equal chance of true and false or with given probability of true result using theboolean()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
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.
Initialization
-
inline Random()
Default constructor.
Constructor with constant seeding.
-
template< typename Number >
inline Random( Number seed ) Constructor with seed. The current number type will be converted to the architecture word type.
-
template< typename Iterator >
inline Random( Iterator begin , Iterator end ) Constructor with array seeding. The given range should contain any number type and the numbers will be converted to the architecture word type.
-
inline Random( const Random & other )
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.
-
inline Random & operator=( const Random & other )
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.
-
template< typename Number >
inline void seed( Number seed ) Seeding random sequence.
Seeding the random sequence. The current number type will be converted to the architecture word type.
-
template< typename Iterator >
inline void seed( Iterator begin , Iterator end ) Seeding random sequence.
Seeding the random sequence. The given range should contain any number type and the numbers will be converted to the architecture word type.
-
inline bool seed()
Seeding from the random device or from the time.
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 theseedFromTime().- Returns:
Currently always
true.
-
inline bool seedFromFile( const std::string & file = "/dev/urandom" , int offset = 0 )
Seeding from file.
Seeding the random sequence from file. The linux kernel has two devices,
/dev/randomand/dev/urandomwhich could give good seed values for pseudo random generators (The difference between two devices is that therandommay block the reading operation while the kernel can give good source of randomness, while theurandomdoes not block the input, but it could give back bytes with worse entropy).- Parameters:
file – The source file
offset – The offset, from the file read.
- Returns:
truewhen the seeding successes.
-
inline bool seedFromTime()
Seeding from the time. This function uses the current time of
std::chrono::system_clockand ofstd::chrono::steady_clockfor initialize the random sequence.- Returns:
Currently always
true.
Uniform Distributions
-
template< typename Number >
inline Number real() Returns a random real number from the range [0, 1).
It returns a random real number from the range [0, 1). The default Number type is
double.
-
inline double real()
-
inline double operator()()
Returns a random real number from the range [0, 1).
It returns a random double from the range [0, 1).
-
inline double operator()( double b )
Returns a random real number from the range [0, b).
It returns a random real number from the range [0, b).
-
inline double operator()( double a , double b )
Returns a random real number from the range [a, b).
It returns a random real number from the range [a, b).
-
template< typename Number >
inline Number integer( Number b ) Returns a random integer from a range.
It returns a random integer from the range {0, 1, …, b - 1}.
-
template< typename Number >
inline Number integer( Number a , Number b ) Returns a random integer from a range.
It returns a random integer from the range {a, a + 1, …, b - 1}.
-
template< typename Number >
inline Number operator[]( Number b ) Returns a random integer from a range.
It returns a random integer from the range {0, 1, …, b - 1}.
-
template< typename Number >
inline Number uinteger() Returns a random non-negative integer.
It returns a random non-negative integer uniformly from the whole range of the current
Numbertype. The default result type of this function isunsigned int.
-
inline unsigned int uinteger()
-
template< typename Number >
inline Number integer() Returns a random integer.
It returns a random integer uniformly from the whole range of the current
Numbertype. The default result type of this function isint.
-
inline int integer()
-
inline bool boolean()
Returns a random bool.
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.
Non-uniform Distributions
-
inline bool boolean( double p )
Returns a random bool with given probability of true result.
It returns a random bool with given probability of true result.
-
inline double gauss()
Standard normal (Gauss) distribution.
Note
The Cartesian form of the Box-Muller transformation is used to generate a random normal distribution.
-
inline double gauss( double mean , double std_dev )
Normal (Gauss) distribution with given mean and standard deviation.
See also
-
inline double lognormal( double n_mean , double n_std_dev )
Lognormal distribution. The parameters are the mean and the standard deviation of
exp(X).
-
inline double lognormal( const std::pair< double , double > & params )
Lognormal distribution. The parameter is an
std::pairof the mean and the standard deviation ofexp(X).
-
inline std::pair< double , double > lognormalParamsFromMD( double mean , double std_dev )
Compute the lognormal parameters from mean and standard deviation.
This function computes the lognormal parameters from mean and standard deviation. The return value can direcly be passed to lognormal().
-
inline double lognormalMD( double mean , double std_dev )
Lognormal distribution with given mean and standard deviation.
-
inline double exponential( double lambda = 1.0 )
Exponential distribution with given mean.
This function generates an exponential distribution random number with mean
1/lambda.
-
inline double gamma( int k )
Gamma distribution with given integer shape.
This function generates a gamma distribution random number.
- Parameters:
k – shape parameter (
k>0integer)
-
inline double gamma( double k , double theta = 1.0 )
Gamma distribution with given shape and scale parameter.
This function generates a gamma distribution random number.
- Parameters:
k – shape parameter (
k>0)theta – scale parameter
-
inline double weibull( double k , double lambda )
Weibull distribution.
This function generates a Weibull distribution random number.
- Parameters:
k – shape parameter (
k>0)lambda – scale parameter (
lambda>0)
-
inline double pareto( double k , double x_min )
Pareto distribution.
This function generates a Pareto distribution random number.
- Parameters:
k – shape parameter (
k>0)x_min – location parameter (
x_min>0)
-
inline int poisson( double lambda )
Poisson distribution.
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.
Two-Dimensional Distributions
-
inline dim2::Point< double > gauss2()
A kind of two-dimensional normal (Gauss) distribution.
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.
-
inline dim2::Point< double > exponential2()
A kind of two-dimensional exponential distribution.
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).
-
inline Random()