Chaste  Release::2018.1
RandomNumberGenerator Class Reference

#include <RandomNumberGenerator.hpp>

+ Inheritance diagram for RandomNumberGenerator:
+ Collaboration diagram for RandomNumberGenerator:

Public Member Functions

double StandardNormalRandomDeviate ()
 
double NormalRandomDeviate (double mean, double stdDev)
 
double ranf ()
 
double GammaRandomDeviate (double shape, double scale)
 
double ExponentialRandomDeviate (double scale)
 
unsigned randMod (unsigned base)
 
template<class T >
void Shuffle (std::vector< boost::shared_ptr< T > > &rValues)
 
void Shuffle (unsigned num, std::vector< unsigned > &rValues)
 
void Reseed (unsigned seed)
 
- Public Member Functions inherited from SerializableSingleton< RandomNumberGenerator >
SerializableSingleton
< RandomNumberGenerator > * 
GetSerializationWrapper () const
 

Static Public Member Functions

static RandomNumberGeneratorInstance ()
 
static void Destroy ()
 

Protected Member Functions

 RandomNumberGenerator ()
 

Private Member Functions

template<class Archive >
void save (Archive &archive, const unsigned int version) const
 
template<class Archive >
void load (Archive &archive, const unsigned int version)
 

Private Attributes

boost::mt19937 mMersenneTwisterGenerator
 
boost::variate_generator
< boost::mt19937
&, boost::uniform_real<> > 
mGenerateUnitReal
 
boost::variate_generator
< boost::mt19937
&, boost::random::normal_distribution_v165<> > 
mGenerateStandardNormal
 

Static Private Attributes

static RandomNumberGeneratormpInstance = nullptr
 

Friends

class boost::serialization::access
 

Detailed Description

A special singleton class allowing one to generate different types of random number in a consistent way across platforms and different versions of compilers, standard libraries, and our dependencies. As a result Chaste developers should always use this class to get random numbers rather than accessing C/C++/boost methods directly.

This class is a singleton and an instance should be retrieved with: RandomNumberGenerator* p_gen = RandomNumberGenerator::Instance();

Note for developers that might want to change this class!:

We use boost random number library for random number generation under the hood http://www.boost.org/doc/libs/1_65_0/doc/html/boost_random.html

Generally boost is consistent between our supported versions (listed on https://chaste.cs.ox.ac.uk/trac/wiki/InstallGuides/DependencyVersions) but on a couple of occasions boost has broken backwards compatibility between random numbers for a given seed.

To get around this, we have copied a minimal set of boost's more recent random include headers into the folder global/src/random

If the user is on a recent version of boost, the boost libraries/includes are used by default, if the user is on an older version of boost some of the Chaste copies of newer boost distributions in global/src/random are used instead to give consistent random numbers across boost versions.

Definition at line 81 of file RandomNumberGenerator.hpp.

Constructor & Destructor Documentation

RandomNumberGenerator::RandomNumberGenerator ( )
protected

Protected constructor. Use Instance() to access the random number generator.

Definition at line 47 of file RandomNumberGenerator.cpp.

References mpInstance.

Referenced by Instance().

Member Function Documentation

void RandomNumberGenerator::Destroy ( )
static

Destroy the current instance of the random number generator. The next call to Instance will create a new instance and re-seed. This method *must* be called before program exit, to avoid a memory leak.

Definition at line 68 of file RandomNumberGenerator.cpp.

References mpInstance.

Referenced by AbstractCellBasedTestSuite::tearDown().

double RandomNumberGenerator::ExponentialRandomDeviate ( double  scale)
Returns
Generate a random number from an exponential distribution with specified scale parameter.
Parameters
scaleThe scale parameter of the exponential distribution from which the random number is drawn, often named lambda

Definition at line 138 of file RandomNumberGenerator.cpp.

References mMersenneTwisterGenerator.

Referenced by CellCycleTimesGenerator::GenerateCellCycleTimeSequence(), and ExponentialG1GenerationalCellCycleModel::SetG1Duration().

double RandomNumberGenerator::GammaRandomDeviate ( double  shape,
double  scale 
)
Returns
Generate a random number from a gamma distribution with specified shape and scale parameters.
Parameters
shapethe shape parameter of the gamma distribution from which the random number is drawn
scalethe scale parameter of the gamma distribution from which the random number is drawn

Definition at line 124 of file RandomNumberGenerator.cpp.

References mMersenneTwisterGenerator.

Referenced by GammaG1CellCycleModel::SetG1Duration().

RandomNumberGenerator * RandomNumberGenerator::Instance ( )
static
Returns
a pointer to the random number generator object. The object is created the first time this method is called.

Definition at line 59 of file RandomNumberGenerator.cpp.

References mpInstance, and RandomNumberGenerator().

Referenced by AbstractCellBasedSimulation< ELEMENT_DIM, SPACE_DIM >::AbstractCellBasedSimulation(), DiffusionForce< DIM >::AddForceContribution(), RandomDirectionVertexBasedDivisionRule< SPACE_DIM >::CalculateCellDivisionVector(), CryptCentreBasedDivisionRule< ELEMENT_DIM, SPACE_DIM >::CalculateCellDivisionVector(), CryptVertexBasedDivisionRule< SPACE_DIM >::CalculateCellDivisionVector(), RandomDirectionCentreBasedDivisionRule< ELEMENT_DIM, SPACE_DIM >::CalculateCellDivisionVector(), ExclusionCaBasedDivisionRule< SPACE_DIM >::CalculateDaughterNodeIndex(), ShovingCaBasedDivisionRule< SPACE_DIM >::CalculateDaughterNodeIndex(), CryptShovingCaBasedDivisionRule::CalculateDaughterNodeIndex(), RandomCellKiller< DIM >::CheckAndLabelSingleCellForApoptosis(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::CheckForRosettes(), CryptCellsGenerator< CELL_CYCLE_MODEL >::Generate(), CellsGenerator< CELL_CYCLE_MODEL, DIM >::GenerateBasicRandom(), CellCycleTimesGenerator::GenerateCellCycleTimeSequence(), StochasticOxygenBasedCellCycleModel::GenerateStochasticG2Duration(), StochasticWntCellCycleModel::GenerateStochasticG2Duration(), HoneycombMeshGenerator::GetCircularMesh(), CryptProjectionStatistics::GetCryptSection(), CryptStatistics::GetCryptSection(), VertexMesh< ELEMENT_DIM, SPACE_DIM >::GetShortAxisOfElement(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::IdentifySwapType(), CryptSimulationBoundaryCondition< DIM >::ImposeBoundaryCondition(), PlaneBoundaryCondition< ELEMENT_DIM, SPACE_DIM >::ImposeBoundaryCondition(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::PerformProtorosetteResolution(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::PerformRosetteRankDecrease(), TetrahedralMesh< ELEMENT_DIM, SPACE_DIM >::PermuteNodes(), BernoulliTrialCellCycleModel::ReadyToDivide(), SimpleWntCellCycleModel::serialize(), StochasticOxygenBasedCellCycleModel::serialize(), StochasticWntCellCycleModel::serialize(), UniformG1GenerationalCellCycleModel::serialize(), GammaG1CellCycleModel::serialize(), UniformCellCycleModel::serialize(), ExponentialG1GenerationalCellCycleModel::serialize(), RandomCellKiller< DIM >::serialize(), AbstractCellBasedSimulation< DIM >::serialize(), UniformCellCycleModel::SetCellCycleDuration(), UniformG1GenerationalCellCycleModel::SetG1Duration(), ExponentialG1GenerationalCellCycleModel::SetG1Duration(), GammaG1CellCycleModel::SetG1Duration(), SimpleWntCellCycleModel::SetG1Duration(), AbstractCellBasedTestSuite::setUp(), Shuffle(), PottsBasedCellPopulation< DIM >::UpdateCellLocations(), CaBasedCellPopulation< DIM >::UpdateCellLocations(), SimpleOxygenBasedCellCycleModel::UpdateHypoxicDuration(), and CaBasedCellPopulation< DIM >::WriteVtkResultsToFile().

template<class Archive >
void RandomNumberGenerator::load ( Archive &  archive,
const unsigned int  version 
)
inlineprivate

Load the RandomNumberGenerator and its member variables.

Note
do not serialize this singleton directly. Instead, serialize the object returned by GetSerializationWrapper().
Parameters
archivethe archive
versionthe current version of this class

Definition at line 140 of file RandomNumberGenerator.hpp.

References mGenerateStandardNormal, and mMersenneTwisterGenerator.

double RandomNumberGenerator::NormalRandomDeviate ( double  mean,
double  stdDev 
)
Returns
Generate a random number from a normal distribution with given mean and standard deviation.
Parameters
meanthe mean of the normal distribution from which the random number is drawn
stdDevthe standard deviation of the normal distribution from which the random number is drawn

Definition at line 119 of file RandomNumberGenerator.cpp.

References StandardNormalRandomDeviate().

Referenced by StochasticOxygenBasedCellCycleModel::GenerateStochasticG2Duration(), StochasticWntCellCycleModel::GenerateStochasticG2Duration(), and SimpleWntCellCycleModel::SetG1Duration().

unsigned RandomNumberGenerator::randMod ( unsigned  base)
Returns
Generate a random number modulo base (i.e. an integer within the range [0, base) == [0,1,..,base-1] ).
Parameters
basethe order of the field of positive integers from which the random number is drawn. This should be no greater than INT_MAX

Definition at line 77 of file RandomNumberGenerator.cpp.

References mMersenneTwisterGenerator, and NEVER_REACHED.

Referenced by CryptShovingCaBasedDivisionRule::CalculateDaughterNodeIndex(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::PerformProtorosetteResolution(), MutableVertexMesh< ELEMENT_DIM, SPACE_DIM >::PerformRosetteRankDecrease(), Shuffle(), PottsBasedCellPopulation< DIM >::UpdateCellLocations(), and CaBasedCellPopulation< DIM >::UpdateCellLocations().

double RandomNumberGenerator::ranf ( )
Returns
Generate a uniform random number in (0,1].

Definition at line 109 of file RandomNumberGenerator.cpp.

References mGenerateUnitReal.

Referenced by RandomDirectionVertexBasedDivisionRule< SPACE_DIM >::CalculateCellDivisionVector(), CryptCentreBasedDivisionRule< ELEMENT_DIM, SPACE_DIM >::CalculateCellDivisionVector(), RandomDirectionCentreBasedDivisionRule< ELEMENT_DIM, SPACE_DIM >::CalculateCellDivisionVector(), CryptVertexBasedDivisionRule< SPACE_DIM >::CalculateCellDivisionVector(), ExclusionCaBasedDivisionRule< SPACE_DIM >::CalculateDaughterNodeIndex(), ShovingCaBasedDivisionRule< SPACE_DIM >::CalculateDaughterNodeIndex(), RandomCellKiller< DIM >::CheckAndLabelSingleCellForApoptosis(), CryptCellsGenerator< CELL_CYCLE_MODEL >::Generate(), CellsGenerator< CELL_CYCLE_MODEL, DIM >::GenerateBasicRandom(), HoneycombMeshGenerator::GetCircularMesh(), CryptProjectionStatistics::GetCryptSection(), CryptStatistics::GetCryptSection(), VertexMesh< ELEMENT_DIM, SPACE_DIM >::GetShortAxisOfElement(), CryptSimulationBoundaryCondition< DIM >::ImposeBoundaryCondition(), PlaneBoundaryCondition< ELEMENT_DIM, SPACE_DIM >::ImposeBoundaryCondition(), BernoulliTrialCellCycleModel::ReadyToDivide(), UniformCellCycleModel::SetCellCycleDuration(), UniformG1GenerationalCellCycleModel::SetG1Duration(), PottsBasedCellPopulation< DIM >::UpdateCellLocations(), CaBasedCellPopulation< DIM >::UpdateCellLocations(), SimpleOxygenBasedCellCycleModel::UpdateHypoxicDuration(), and CaBasedCellPopulation< DIM >::WriteVtkResultsToFile().

void RandomNumberGenerator::Reseed ( unsigned  seed)

Reseed the random number generator.

Parameters
seedthe new seed

Definition at line 153 of file RandomNumberGenerator.cpp.

References mGenerateStandardNormal, mGenerateUnitReal, and mMersenneTwisterGenerator.

Referenced by CellCycleTimesGenerator::GenerateCellCycleTimeSequence(), and AbstractCellBasedTestSuite::setUp().

template<class Archive >
void RandomNumberGenerator::save ( Archive &  archive,
const unsigned int  version 
) const
inlineprivate

Save the RandomNumberGenerator and its member variables.

Note
do not serialize this singleton directly. Instead, serialize the object returned by GetSerializationWrapper().
Parameters
archivethe archive
versionthe current version of this class

Definition at line 112 of file RandomNumberGenerator.hpp.

References mGenerateStandardNormal, and mMersenneTwisterGenerator.

template<class T >
void RandomNumberGenerator::Shuffle ( std::vector< boost::shared_ptr< T > > &  rValues)
inline

Produce a permutation of the integers and non-empty std::vector, using the Knuth-algorithm (also called the Fisher-Yates algorithm), a linear time unbiased method. The values are shuffled in place.

Parameters
rValuesthe initial values and the output permutation of shuffled values. Must be non-empty

Definition at line 214 of file RandomNumberGenerator.hpp.

References Instance(), and randMod().

Referenced by TetrahedralMesh< ELEMENT_DIM, SPACE_DIM >::PermuteNodes(), PottsBasedCellPopulation< DIM >::UpdateCellLocations(), and CaBasedCellPopulation< DIM >::UpdateCellLocations().

void RandomNumberGenerator::Shuffle ( unsigned  num,
std::vector< unsigned > &  rValues 
)

Produce a permutation of the integers 0,1,..,num-1, using the Knuth-algorithm (also called the Fisher-Yates algorithm), a linear time unbiased method. The shuffled values are returned in rValues, which doesn't need to be correctly-sized when passed in.

Parameters
numthe number of integers to shuffle
rValuesthe output permutation of shuffled values (any initial values ignored)

Definition at line 164 of file RandomNumberGenerator.cpp.

References Instance(), and randMod().

double RandomNumberGenerator::StandardNormalRandomDeviate ( )
Returns
a random number from the normal distribution with mean 0 and standard distribution 1.

Definition at line 114 of file RandomNumberGenerator.cpp.

References mGenerateStandardNormal.

Referenced by DiffusionForce< DIM >::AddForceContribution(), and NormalRandomDeviate().

Member Data Documentation

boost::variate_generator<boost::mt19937&, boost::random::normal_distribution_v165<> > RandomNumberGenerator::mGenerateStandardNormal
private

An adaptor to a standard normal distribution.

Definition at line 94 of file RandomNumberGenerator.hpp.

Referenced by load(), Reseed(), save(), and StandardNormalRandomDeviate().

boost::variate_generator<boost::mt19937&, boost::uniform_real<> > RandomNumberGenerator::mGenerateUnitReal
private

An adaptor to a unit interval distribution.

Definition at line 90 of file RandomNumberGenerator.hpp.

Referenced by ranf(), and Reseed().

boost::mt19937 RandomNumberGenerator::mMersenneTwisterGenerator
private

The main random number generator.

Definition at line 85 of file RandomNumberGenerator.hpp.

Referenced by ExponentialRandomDeviate(), GammaRandomDeviate(), load(), randMod(), Reseed(), and save().

RandomNumberGenerator * RandomNumberGenerator::mpInstance = nullptr
staticprivate

Pointer to the single instance.

Definition at line 99 of file RandomNumberGenerator.hpp.

Referenced by Destroy(), Instance(), and RandomNumberGenerator().


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