RNG Class Reference

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 cos(), oomph::SarahBL::epsilon, getRandomNumber(), haveSavedBoxMuller_, Eigen::bfloat16_impl::log(), min, constants::pi, UniformPSDSelfTest::radius, savedBoxMuller_, sin(), sqrt(), and BiharmonicTestFunctions2::theta.

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 Eigen::bfloat16_impl::exp(), getRandomNumber(), k, lambda, 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);
}

Referenced by SmoothChute::actionsBeforeTimeStep(), Chutebelt::actionsOnRestart(), NautaMixer::addParticles(), HeaterBoundary::checkBoundaryAfterParticleMoved(), BaseCluster::computeInternalStructure(), LawinenBox::create_inflow_particle(), ChutePeriodic::create_inflow_particle(), ChuteWithContraction::create_inflow_particle(), Funnel::create_inflow_particle(), AngleOfRepose::create_inflow_particle(), FlowRule::create_inflow_particle(), SilbertPeriodic::create_inflow_particle(), SegregationWithHopper::create_inflow_particle(), Slide::create_rough_wall(), Chute::createBottom(), CurvyChute::createBottom(), Chute::createFlowParticle(), PSD::drawSample(), InsertionBoundary::generateParticle(), BidisperseCubeInsertionBoundary::generateParticle(), PolydisperseInsertionBoundary::generateParticle(), getNormalVariate(), getPoissonVariate(), InitialConditions< SpeciesType >::InitialConditions(), HorizontalMixer::introduceParticlesInDomain(), LeesEdwardsSelfTest::LeesEdwardsSelfTest(), main(), operator()(), BaseCluster::particleInsertionSuccessful(), FixedClusterInsertionBoundary::placeParticle(), ChuteInsertionBoundary::placeParticle(), CubeInsertionBoundary::placeParticle(), CylinderInsertionBoundary::placeParticle(), HopperInsertionBoundary::placeParticle(), PolydisperseInsertionBoundary::placeParticle(), RandomClusterInsertionBoundary::placeParticle(), SphereInsertionBoundary::placeParticle(), MD_demo::RandomRadius(), DPMBase::setMeanVelocityAndKineticEnergy(), BaseCluster::setRadii(), ClosedCSCWalls::setupInitialConditions(), CSCInit::setupInitialConditions(), CSCWalls::setupInitialConditions(), MercuryLogo::setupInitialConditions(), SmoothChute::setupInitialConditions(), NozzleDemo::setupInitialConditions(), Binary::setupInitialConditions(), FreeCooling2DinWallsDemo::setupInitialConditions(), FreeCooling3DDemoProblem::setupInitialConditions(), FreeCooling3DinWallsDemo::setupInitialConditions(), FreeCoolingDemoProblem::setupInitialConditions(), HourGlass2D::setupInitialConditions(), HourGlass::setupInitialConditions(), MinimalExampleDrum::setupInitialConditions(), TimeDependentPeriodicBoundary3DSelfTest::setupInitialConditions(), FiveParticles::setupInitialConditions(), Cstatic2d::setupInitialConditions(), InitialBed::setupInitialConditions(), NozzleSelfTest::setupInitialConditions(), ParticleCreation::setupInitialConditions(), ParticleParticleCollision::setupInitialConditions(), WallParticleCollision::setupInitialConditions(), my_problem_HGRID::setupInitialConditions(), TriangulatedScrewSelfTest::setupInitialConditions(), TriangulatedWallSelfTest::setupInitialConditions(), DrumRot::setupInitialConditions(), RotatingDrum::setupInitialConditions(), ScalingTestInitialConditionsRelax::setupInitialConditions(), GranularCollapse::setupInitialConditions(), EllipticalSuperQuadricCollision::setupInitialConditions(), Tutorial11::setupInitialConditions(), MD_demo::setupInitialConditions(), MpiMaserChuteTest::setupInitialConditions(), MpiPeriodicBoundaryUnitTest::setupInitialConditions(), ChuteBottom::setupInitialConditions(), and test().

getRandomNumber() [2/2]

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

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

References getRandomNumberFromLaggedFibonacciGenerator(), getRandomNumberFromLinearCongruentialGenerator(), LINEAR_CONGRUENTIAL_GENERATOR, logger, max, min, 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 Eigen::bfloat16_impl::fmod(), max, min, 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_, max, min, 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(), max, and min.

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(), DPMBase::readNextArgument(), and RotatingDrumBidisperse::RotatingDrumBidisperse().

read()

void RNG::read

(

std::istream &

is

)

Todo:

tw @at should that number be part of the restart file? It seems to be computed from the other numbers.

{
    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(), oomph::Global_string_for_annotation::string(), compute_granudrum_aor::type, 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(), 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, p_, Eigen::numext::q, 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, a_, calibrate::c, c_, m, and m_.

setRandomNumberGenerator()

void RNG::setRandomNumberGenerator

(

RNGType

type

)

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

{
    type_ = type;
}

References compute_granudrum_aor::type, and type_.

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(), 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(), Eigen::bfloat16_impl::floor(), getRandomNumber(), i, INFO, logger, and NO_FLUSH.

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;
}

References a_, c_, m_, p_, q_, randomSeedLinearCongruentialGenerator_, and type_.

Referenced by DPMBase::write().

Member Data Documentation

a_

unsigned long int RNG::a_

private

This are the two parameters that control the LCG random generated.

Referenced by getRandomNumberFromLinearCongruentialGenerator(), randomise(), read(), RNG(), setLinearCongruentialGeneratorParmeters(), and write().

c_

unsigned long int RNG::c_

private

Referenced by getRandomNumberFromLinearCongruentialGenerator(), randomise(), read(), RNG(), setLinearCongruentialGeneratorParmeters(), and write().

haveSavedBoxMuller_

bool RNG::haveSavedBoxMuller_

private

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

Referenced by getNormalVariate(), and RNG().

m_

unsigned long int RNG::m_

private

Referenced by getRandomNumberFromLinearCongruentialGenerator(), randomise(), read(), RNG(), setLinearCongruentialGeneratorParmeters(), and write().

p_

unsigned long int RNG::p_

private

This are the parameters that control the LFG random generator.

Referenced by getRandomNumberFromLaggedFibonacciGenerator(), randomise(), read(), RNG(), seedLaggedFibonacciGenerator(), setLaggedFibonacciGeneratorParameters(), and write().

q_

unsigned long int RNG::q_

private

Referenced by getRandomNumberFromLaggedFibonacciGenerator(), randomise(), read(), RNG(), setLaggedFibonacciGeneratorParameters(), and write().

randomSeedLaggedFibonacciGenerator_

std::vector<Mdouble> RNG::randomSeedLaggedFibonacciGenerator_

private

This is the seeds required for the LFG.

Referenced by getRandomNumberFromLaggedFibonacciGenerator(), RNG(), seedLaggedFibonacciGenerator(), and setLaggedFibonacciGeneratorParameters().

randomSeedLinearCongruentialGenerator_

unsigned long int RNG::randomSeedLinearCongruentialGenerator_

private

This is the initial seed of the RNG.

Referenced by getRandomNumberFromLinearCongruentialGenerator(), randomise(), read(), RNG(), setRandomSeed(), and write().

savedBoxMuller_

Mdouble RNG::savedBoxMuller_

private

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

Referenced by getNormalVariate(), and RNG().

type_

RNGType RNG::type_

private

This is the type of random number generator.

Referenced by getRandomNumber(), randomise(), read(), RNG(), setRandomNumberGenerator(), and write().

---

The documentation for this class was generated from the following files:

• RNG.h
• RNG.cc