This is a class that generates random numbers i.e. named the Random Number Generator (RNG). More...

#include <RNG.h>

Public Member Functions
	RNG ()
	default constructor More...

void	setRandomSeed (unsigned long int new_seed)
	This is the seed for the random number generator (note the call to seed_LFG is only required really if using that type of generator, but the other one is always required) More...

void	read (std::istream &is)

void	write (std::ostream &os) const

Mdouble	getRandomNumber ()
	This is a random generating routine can be used for initial positions. More...

Mdouble	getRandomNumber (Mdouble min, Mdouble max)

Mdouble	operator() (Mdouble min, Mdouble max)
	Shorthand for getRandomNumber(min, max) More...

Mdouble	operator() ()

Mdouble	getNormalVariate ()
	Produces a random number according to a normal distribution with mean 0 and standard deviation 1. More...

Mdouble	getNormalVariate (Mdouble mean, Mdouble stdev)
	Produces a random number according to a normal distribution. More...

unsigned int	getPoissonVariate (Mdouble lambda)
	Produces a random number according to a Poisson distribution. More...

Mdouble	test ()
	This function tests the quality of random numbers, based on the chi-squared test. More...

void	setLinearCongruentialGeneratorParmeters (const unsigned int a, const unsigned int c, unsigned int m)
	This functions set the parameters for the LCG random number generator. It goes multiplier, addition, mod. More...

void	randomise ()
	sets the random variables such that they differ for each run More...

void	setLaggedFibonacciGeneratorParameters (const unsigned int p, const unsigned int q)
	This function sets the parameters for the LFG random number generator. More...

void	setRandomNumberGenerator (RNGType type)
	Allows the user to set which random number generator is used. More...

Private Member Functions
Mdouble	getRandomNumberFromLinearCongruentialGenerator (Mdouble min, Mdouble max)
	This is a basic Linear Congruential Generator Random. More...

Mdouble	getRandomNumberFromLaggedFibonacciGenerator (Mdouble min, Mdouble max)
	This is a Lagged Fibonacci Generator. More...

void	seedLaggedFibonacciGenerator ()
	This seed the LFG. More...

Private Attributes
unsigned long int	randomSeedLinearCongruentialGenerator_
	This is the initial seed of the RNG. More...

std::vector< Mdouble >	randomSeedLaggedFibonacciGenerator_
	This is the seeds required for the LFG. More...

unsigned long int	a_
	This are the two parameters that control the LCG random generated. More...

unsigned long int	c_

unsigned long int	m_

unsigned long int	p_
	This are the parameters that control the LFG random generator. More...

unsigned long int	q_

RNGType	type_
	This is the type of random number generator. More...

bool	haveSavedBoxMuller_
	A flag that keeps track of whether or not to generate a new pair of normal variates (using Box–Muller) More...

Mdouble	savedBoxMuller_
	A storage space for the so-far-unused variate from the pair generated by Box–Muller. More...

Detailed Description

This is a class that generates random numbers i.e. named the Random Number Generator (RNG).

This is a stand-along class; but is encapsulated (used) by the MD class. To make it architecture safe the both LCG and function is hard codes i.e. does not use the internal C++ one.

Todo:: (AT) implement new C++-standard RNG instead of this one (Kudos on the hard work done here though ;). NB: maybe something for Mercury 2?

Constructor & Destructor Documentation

◆ RNG()

RNG::RNG ( )

default constructor

This is a random number generator and returns a Mdouble within the range specified

Todo:: {Thomas: This code does sth. when min>max; I would prefer to throw an error.}

 {
     randomSeedLinearCongruentialGenerator_ = 0;
     a_ = 1103515245;
     c_ = 12345;
     m_ = 1024 * 1024 * 1024;
     type_ = RNGType::LAGGED_FIBONACCI_GENERATOR;
     p_ = 607;
     q_ = 273;
     randomSeedLaggedFibonacciGenerator_.resize(p_);
     seedLaggedFibonacciGenerator();
  
     haveSavedBoxMuller_ = false;
     savedBoxMuller_ = 0;
  
 }

References a_, c_, haveSavedBoxMuller_, LAGGED_FIBONACCI_GENERATOR, m_, p_, q_, randomSeedLaggedFibonacciGenerator_, randomSeedLinearCongruentialGenerator_, savedBoxMuller_, seedLaggedFibonacciGenerator(), and type_.

Member Function Documentation

◆ getNormalVariate() [1/2]

Mdouble RNG::getNormalVariate ( )

Produces a random number according to a normal distribution with mean 0 and standard deviation 1.

 {
     static const double epsilon = std::numeric_limits<Mdouble>::min();
  
     if (haveSavedBoxMuller_)
     {
         /* If we have already generated a normal variate, use it. */
         haveSavedBoxMuller_ = false;
         return savedBoxMuller_;
     }
     else
     {
         /* Otherwise, generate a pair of normal variates, return one of them,
          * and save the other. */
         Mdouble radius, theta;
         do
         {
             radius = getRandomNumber(0, 1);
             theta = getRandomNumber(0, 2 * constants::pi);
         } while (radius <= epsilon);
         // make sure that the radius generated is not too small
         // (unlikely to happen, just a safety check)
  
         savedBoxMuller_ = sqrt(-2.0 * log(radius)) * sin(theta);
         haveSavedBoxMuller_ = true;
         return sqrt(-2.0 * log(radius)) * cos(theta);
     }
 }

References mathsFunc::cos(), getRandomNumber(), haveSavedBoxMuller_, mathsFunc::log(), constants::pi, savedBoxMuller_, and mathsFunc::sin().

Referenced by getNormalVariate().

◆ getNormalVariate() [2/2]

Mdouble RNG::getNormalVariate	(	Mdouble	mean,
		Mdouble	stdev
	)

Produces a random number according to a normal distribution.

 {
     if (stdev == 0) {
         logger(WARN,
                "[RNG::getNormalVariate(Mdouble, Mdouble)] Zero stdev?");
         return mean;
     } else if (stdev < 0) {
         logger(ERROR,
                "[RNG::getNormalVariate(Mdouble, Mdouble)] Negative stdev is not allowed.");
         return 0;
     } else {
         return getNormalVariate() * stdev + mean;
     }
 }

References ERROR, getNormalVariate(), logger, and WARN.

◆ getPoissonVariate()

unsigned int RNG::getPoissonVariate ( Mdouble lambda )

Produces a random number according to a Poisson distribution.

This uses Knuth's algorithm for generating Poisson variates. It's simple but slow for large values of lambda — beware.

 {
     if (lambda > 50)
     {
         logger(WARN, "[RNG::getPoissonVariate(Mdouble)] Knuth's algorithm for Poissons may be slow for lambda = %", lambda);
     }
     unsigned int k = 0; 
     Mdouble u;
     do 
     {
         k++;
         u = getRandomNumber(0, 1);
     }
     while (u > exp(-lambda));
     return k-1;
 }

References mathsFunc::exp(), getRandomNumber(), logger, and WARN.

Referenced by CurvyChute::createBottom().

◆ getRandomNumber() [1/2]

Mdouble RNG::getRandomNumber ( )

This is a random generating routine can be used for initial positions.

 {
     return getRandomNumber(0, 1);
 }

◆ getRandomNumber() [2/2]

Mdouble RNG::getRandomNumber	(	Mdouble	min,
		Mdouble	max
	)

 {
     logger.assert_debug(min <= max, "getRandomNumber: min cannot be larger than max");
     if (type_ == RNGType::LINEAR_CONGRUENTIAL_GENERATOR) {
         return getRandomNumberFromLinearCongruentialGenerator(min, max);
     } else {
         return getRandomNumberFromLaggedFibonacciGenerator(min, max);
     }
 }

References getRandomNumberFromLaggedFibonacciGenerator(), getRandomNumberFromLinearCongruentialGenerator(), LINEAR_CONGRUENTIAL_GENERATOR, logger, and type_.

◆ getRandomNumberFromLaggedFibonacciGenerator()

Mdouble RNG::getRandomNumberFromLaggedFibonacciGenerator	(	Mdouble	min,
		Mdouble	max
	)

private

This is a Lagged Fibonacci Generator.

This is a basic Linear Fibonacci Generator Random Is described by three parameters, the multiplication a, the addition c and the mod m

 {
 #pragma optimize( "", off )
     Mdouble new_seed = fmod(randomSeedLaggedFibonacciGenerator_[0] + randomSeedLaggedFibonacciGenerator_[p_ - q_],
                             static_cast<Mdouble>(1.0));
     //Update the random seed
     randomSeedLaggedFibonacciGenerator_.erase(randomSeedLaggedFibonacciGenerator_.begin());
     randomSeedLaggedFibonacciGenerator_.emplace_back(new_seed);
     
     //Generate a random number in the required range
     
     Mdouble random_num;
     
     Mdouble range = max - min;
     random_num = min + range * new_seed;
     return random_num;
 #pragma optimize( "", on )
 }

References p_, q_, and randomSeedLaggedFibonacciGenerator_.

Referenced by getRandomNumber().

◆ getRandomNumberFromLinearCongruentialGenerator()

Mdouble RNG::getRandomNumberFromLinearCongruentialGenerator	(	Mdouble	min,
		Mdouble	max
	)

private

This is a basic Linear Congruential Generator Random.

This is a basic Linear Congruential Generator Random Is described by three parameters, the multiplication a, the addition c and the mod m

 {
     //Update the random seed
     randomSeedLinearCongruentialGenerator_ = (a_ * randomSeedLinearCongruentialGenerator_ + c_) % m_;
     
     //Generate a random number in the required range
     
     Mdouble range = max - min;
     Mdouble random_num = min + range * randomSeedLinearCongruentialGenerator_ / (static_cast<Mdouble>(m_) + 1.0);
     
     return random_num;
 }

References a_, c_, m_, and randomSeedLinearCongruentialGenerator_.

Referenced by getRandomNumber(), and seedLaggedFibonacciGenerator().

◆ operator()() [1/2]

Mdouble RNG::operator() ( )

inline

     {
         return getRandomNumber(0.0, 1.0);
     }

References getRandomNumber().

◆ operator()() [2/2]

Mdouble RNG::operator()	(	Mdouble	min,
		Mdouble	max
	)

inline

Shorthand for getRandomNumber(min, max)

     {
         return getRandomNumber(min, max);
     }

References getRandomNumber().

◆ randomise()

void RNG::randomise ( )

sets the random variables such that they differ for each run

 {
 #ifdef MERCURYDPM_USE_MPI
     //First set a random seed on the root
     if (PROCESSOR_ID == 0)
     {
         setRandomSeed(static_cast<unsigned long int>(time(nullptr)));
     }
  
     //Communicate this to the rest of the processes
     std::vector<int> values(7);
     if (PROCESSOR_ID == 0)
     {
         values[0] = static_cast<unsigned int>(type_);
         values[1] = a_;
         values[2] = c_;
         values[3] = m_;
         values[4] = p_;
         values[5] = q_;
         values[6] = randomSeedLinearCongruentialGenerator_;
     } 
     MPIContainer::Instance().broadcast(values.data(),7,0);
  
     //Update the generators on the other processors   
     if (PROCESSOR_ID != 0)
     {
         type_ = static_cast<RNGType>(values[0]);
         a_ = values[1];
         c_ = values[2];
         m_ = values[3];
         p_ = values[4];
         q_ = values[5];
         randomSeedLinearCongruentialGenerator_ = values[6];
     }
     seedLaggedFibonacciGenerator();
 #else
     setRandomSeed(static_cast<unsigned long int>(time(nullptr)));
 #endif
 }

References a_, MPIContainer::broadcast(), c_, MPIContainer::Instance(), m_, p_, PROCESSOR_ID, q_, randomSeedLinearCongruentialGenerator_, seedLaggedFibonacciGenerator(), setRandomSeed(), and type_.

Referenced by FixedClusterInsertionBoundary::checkBoundaryBeforeTimeStep(), RandomClusterInsertionBoundary::checkBoundaryBeforeTimeStep(), LawinenBox::LawinenBox(), main(), FixedClusterInsertionBoundary::placeParticle(), RandomClusterInsertionBoundary::placeParticle(), and DPMBase::readNextArgument().

◆ read()

void RNG::read ( std::istream & is )

 {
     std::string dummy;
     unsigned int type;
     is >> type;
     type_ = static_cast<RNGType>(type);
     is >> a_;
     is >> c_;
     is >> m_;
     is >> p_;
     is >> q_;
     is >> randomSeedLinearCongruentialGenerator_;
     //note: the seeds for the LaggedFibonacciGenerator cannot be restarted currently.
     seedLaggedFibonacciGenerator();
     //randomSeedLaggedFibonacciGenerator_.resize(p_);
     //for (auto& v : randomSeedLaggedFibonacciGenerator_) 
     //    is >> v;
 }

References a_, c_, m_, p_, q_, randomSeedLinearCongruentialGenerator_, seedLaggedFibonacciGenerator(), and type_.

Referenced by DPMBase::read().

◆ seedLaggedFibonacciGenerator()

void RNG::seedLaggedFibonacciGenerator ( )

private

This seed the LFG.

 {
     for (unsigned int i = 0; i < p_; i++)
     {
         randomSeedLaggedFibonacciGenerator_[i] = getRandomNumberFromLinearCongruentialGenerator(0, 1.0);
     }
 }

References getRandomNumberFromLinearCongruentialGenerator(), constants::i, p_, and randomSeedLaggedFibonacciGenerator_.

Referenced by randomise(), read(), RNG(), setLaggedFibonacciGeneratorParameters(), and setRandomSeed().

◆ setLaggedFibonacciGeneratorParameters()

void RNG::setLaggedFibonacciGeneratorParameters	(	const unsigned int	p,
		const unsigned int	q
	)

This function sets the parameters for the LFG random number generator.

 {
     //p must be greater than q so makes sure this is true. Not sure what happens if you set p=q, in the LFG alogrithm.
     if (p < q)
     {
         p_ = q;
         q_ = p;
     }
     else
     {
         p_ = p;
         q_ = q;
     }
     
     randomSeedLaggedFibonacciGenerator_.resize(p_);
     seedLaggedFibonacciGenerator();
 }

References p_, q_, randomSeedLaggedFibonacciGenerator_, and seedLaggedFibonacciGenerator().

◆ setLinearCongruentialGeneratorParmeters()

void RNG::setLinearCongruentialGeneratorParmeters	(	const unsigned int	a,
		const unsigned int	c,
		unsigned int	m
	)

This functions set the parameters for the LCG random number generator. It goes multiplier, addition, mod.

 {
     a_ = a;
     c_ = c;
     m_ = m;
 }

References a_, c_, and m_.

Referenced by main().

◆ setRandomNumberGenerator()

void RNG::setRandomNumberGenerator ( RNGType type )

Allows the user to set which random number generator is used.

 {
     type_ = type;
 }

References type_.

Referenced by main().

◆ setRandomSeed()

void RNG::setRandomSeed ( unsigned long int new_seed )

This is the seed for the random number generator (note the call to seed_LFG is only required really if using that type of generator, but the other one is always required)

 {
     randomSeedLinearCongruentialGenerator_ = new_seed;
     seedLaggedFibonacciGenerator();
 }

References randomSeedLinearCongruentialGenerator_, and seedLaggedFibonacciGenerator().

Referenced by DPMBase::constructor(), main(), particleParticleTest(), PSD::PSD(), randomise(), and PSD::setFixedSeed().

◆ test()

Mdouble RNG::test ( )

This function tests the quality of random numbers, based on the chi-squared test.

This function tests the quality of random numbers, based on the chi-squared test. It reports a probability that the random number being generated are coming from a uniform distributed. If this number is less than 0.95, it is strongly advised that you change the parameters being used

 {
     //This are the fixed parameters that define the test
     static unsigned int num_of_tests = 100000;
     static Mdouble max_num = 100.0;
     static unsigned int num_of_bins = 10;
     
     //This is the generated random_number
     Mdouble rn;
     //This is the bin the random number will lie in
     unsigned int bin = 0;
     //This is a vector of bins
     std::vector<int> count;
     count.resize(num_of_bins);
     
     //Initialisation of the bins
     for (unsigned int i = 0; i < num_of_bins; i++)
     {
         count[bin] = 0;
     }
     
     //Loop over a number of tests
     for (unsigned int i = 0; i < num_of_tests; i++)
     {
         rn = getRandomNumber(0.0, max_num);
         bin = static_cast<unsigned int>(std::floor(rn * num_of_bins / max_num));
         
         //Add one to the bin count
         count[bin]++;
         
     }
     
     //Final post-process the result and report on the random number
     Mdouble chi_cum = 0.0;
     Mdouble expected = num_of_tests / num_of_bins;
     
     for (unsigned int i = 0; i < num_of_bins; i++)
     {
         chi_cum = chi_cum + (count[i] - expected) * (count[i] - expected) / expected;
         logger(INFO, "% : % : %\n", Flusher::NO_FLUSH, i, count[i], (count[i] - expected) * (count[i] - expected) /
                                                                     expected);
     }
     //end for loop over computing the chi-squared value.
     logger(INFO, "chi_cum %", chi_cum);
  
     return mathsFunc::chi_squared_prob(chi_cum, num_of_bins);
 }

References mathsFunc::chi_squared_prob(), getRandomNumber(), constants::i, INFO, logger, and NO_FLUSH.

Referenced by main().

◆ write()

void RNG::write ( std::ostream & os ) const

 {
     os << " " << static_cast<unsigned int>(type_);
     os << " " << a_;
     os << " " << c_;
     os << " " << m_;
     os << " " << p_;
     os << " " << q_;
     os << " " << randomSeedLinearCongruentialGenerator_;
     //for (auto v : randomSeedLaggedFibonacciGenerator_) 
     //    os << " " << v;
 }