Base random number generator class. All random number generators should be derived from this class. More...

#include <egs_rndm.h>

Inheritance diagram for EGS_RandomGenerator:

Public Member Functions
	EGS_RandomGenerator (int n=128)
	Construct a RNG that has an array of n points to hold random numbers. More...

	EGS_RandomGenerator (const EGS_RandomGenerator &r)
	Copy constructor. More...

virtual	~EGS_RandomGenerator ()
	Destructor. More...

EGS_Float	getUniform ()
	Returns a random number uniformly distributed between zero (inclusive) and 1 (exclusive). More...

EGS_I64	numbersGenerated () const
	Returns the number of random numbers generated so far. More...

EGS_I64	numbersUsed () const
	Returns the number of random numbers used so far. More...

void	getAzimuth (EGS_Float &cphi, EGS_Float &sphi)
	Sets cphi and sphi to the cosine and sine of a random angle uniformely distributed between 0 and $2 \pi$ . More...

EGS_Float	getGaussian ()
	Returns a Gaussian distributed random number with mean zero and standard deviation 1.

virtual void	fillArray (int n, EGS_Float *array)=0
	Fill the array of n elements pointed to by array with random numbers. More...

virtual EGS_RandomGenerator *	getCopy ()=0
	Get a copy of the RNG.

virtual void	setState (EGS_RandomGenerator *r)=0
	Set the state of the RNG from another RNG.

virtual void	saveState ()=0
	Save the RNG state.

virtual void	resetState ()=0
	Reset the state to a previously saved state.

virtual int	rngSize () const =0
	The memory needed to store the rng state.

virtual void	describeRNG () const
	Describe this RNG. More...

state_functions
bool	storeState (ostream &data)
	Functions for storing, seting and reseting the state of a RNG object. More...

bool	setState (istream &data)

bool	addState (istream &data)

void	resetCounter ()

Static Public Member Functions
static EGS_RandomGenerator *	createRNG (EGS_Input *inp, int sequence=0)
	Create a RNG object from the information pointed to by inp and return a pointer to it. More...

static EGS_RandomGenerator *	defaultRNG (int sequence=0)
	Returns a pointer to the default egspp RNG. More...

Protected Member Functions
virtual bool	storePrivateState (ostream &data)=0
	Store the state of the RNG to the output stream data. More...

virtual bool	setPrivateState (istream &data)=0
	Set the state of the RNG object from the data in the input stream data. More...

void	copyBaseState (const EGS_RandomGenerator &r)

void	allocate (int n)

int	baseSize () const
	The memory needed to store the base state.

Protected Attributes
EGS_I64	count
	random number generated so far

int	np
	size of the array rarray

int	ip
	pointer to the next rarray element in the sequence

EGS_Float *	rarray
	array with random numbers of size np.

Detailed Description

Base random number generator class. All random number generators should be derived from this class.

A random number generator (RNG) is a central part of every Monte Carlo simulation. In order to have the possibility of using different RNGs, the egspp class library defines a RNG as an abstract class. However, for the sake of efficiency, the main method for drawing random numbers getUniform() is implemented as an inline function, which returns the next number in an array of random numbers, possibly after calling the pure virtual method fillArray() to fill the array with random numbers. Appart from getUniform(), which returns a random number uniformely distributed between zero (inclusive) and one (exclusive), EGS_RandomGenerator implements some frequently needed algorithms such as picking a random azimuthal angle ( getAzimuth() ) angle and picking a Gaussian distributed number ( getGaussian() ).

Todo:: Should not EGS_RandomGenerator be derived from EGS_Object, so that dynamically loading RNG DSOs is automatically implemented?

Examples:: sources/egs_point_source/egs_point_source.cpp.

Definition at line 67 of file egs_rndm.h.

Constructor & Destructor Documentation

EGS_RandomGenerator::EGS_RandomGenerator ( int n = 128 )

Construct a RNG that has an array of n points to hold random numbers.

Memory gets allocated and rarray points to it. The pointer ip is set to point beyond the array (so that at the next call of getUniform() rarray gets filled via a call to fillArray() ).

Definition at line 74 of file egs_rndm.cpp.

References np, and rarray.

EGS_RandomGenerator::EGS_RandomGenerator ( const EGS_RandomGenerator & r )

Copy constructor.

Being able to save the state of a RNG is useful in advanced applications such as correlated sampling.

Definition at line 85 of file egs_rndm.h.

virtual EGS_RandomGenerator::~EGS_RandomGenerator ( )

virtual

Destructor.

Deallocates the memory pointed to by rarray.

Definition at line 93 of file egs_rndm.h.

Member Function Documentation

EGS_Float EGS_RandomGenerator::getUniform ( )

Returns a random number uniformly distributed between zero (inclusive) and 1 (exclusive).

Uses the virtual method fillArray() to fill the array rarray, if the pointer ip points beyond the last element of rarray.

Examples:: sources/egs_point_source/egs_point_source.cpp.

Definition at line 103 of file egs_rndm.h.

Referenced by EGS_RadionuclideSource::getNextParticle(), EGS_SphericalShellShape::getPoint(), EGS_BoxShape::getPoint(), EGS_SphereShape::getPoint(), EGS_CylinderShape::getPoint(), EGS_CylinderShape::getPointInCircle(), EGS_SphericalShellShape::getPointSourceDirection(), EGS_BoxShape::getPointSourceDirection(), EGS_SphereShape::getPointSourceDirection(), EGS_CylinderShape::getPointSourceDirection(), EGS_AliasTable::sample(), EGS_SimpleAliasTable::sample(), EGS_RadionuclideSpectrum::sample(), and EGS_AliasTable::sampleBin().

EGS_I64 EGS_RandomGenerator::numbersGenerated ( ) const

Returns the number of random numbers generated so far.

This is useful for simulation diagnostics purposes.

See Also: numbersUsed()

Definition at line 116 of file egs_rndm.h.

EGS_I64 EGS_RandomGenerator::numbersUsed ( ) const

Returns the number of random numbers used so far.

This is normally different than numbersGenerated() as some of the numbers in the array rarray may not have been used yet.

Definition at line 125 of file egs_rndm.h.

Referenced by EGS_Application::randomNumbersUsed().

void EGS_RandomGenerator::getAzimuth	(	EGS_Float &	cphi,
		EGS_Float &	sphi
	)

Sets cphi and sphi to the cosine and sine of a random angle uniformely distributed between 0 and $2 \pi$ .

The default implementation uses a box method as this is faster on AMD and Intel CPUs. If the preprocessor macro FAST_SINCOS is defined, then an azimuthal angle $\phi$ is drawn uniformly between 0 and $2 \pi$ and cphi and sphi are calculated using the cosine and sine functions.

Examples:: sources/egs_point_source/egs_point_source.cpp.

Definition at line 138 of file egs_rndm.h.

Referenced by EGS_SphericalShellShape::getPoint(), EGS_SphereShape::getPoint(), EGS_SphericalShellShape::getPointSourceDirection(), EGS_SphereShape::getPointSourceDirection(), and EGS_CylinderShape::getPointSourceDirection().

EGS_RandomGenerator * EGS_RandomGenerator::createRNG	(	EGS_Input *	inp,
		int	sequence = `0`
	)

static

Create a RNG object from the information pointed to by inp and return a pointer to it.

The input inp must either be itself, or it mist have a property with key rng definition, otherwise the return value of this function will be null. The sequence parameter is usefull to automatically adjust the initial random number seeds in parallel runs.

Note: it is planned to extend this function to be able to create RNG objects by dinamically loading RNG dynamic shared objects, but this functionality is not there yet. For now, the only RNG type available is a ranmar RNG.

Definition at line 408 of file egs_rndm.cpp.

References EGS_Input::compare(), egsWarning, EGS_Input::getInput(), EGS_Input::isA(), and EGS_Input::takeInputItem().

Referenced by EGS_SimpleApplication::EGS_SimpleApplication(), EGS_Application::initRNG(), and volcor::VCOptions::setRNG().

EGS_RandomGenerator * EGS_RandomGenerator::defaultRNG ( int sequence = 0 )

static

Returns a pointer to the default egspp RNG.

The default egspp RNG is ranmar. The RNG is initialized with by increasing the second ranmar default initial seed by sequence.

Definition at line 464 of file egs_rndm.cpp.

References egsFatal.

Referenced by EGS_SimpleApplication::EGS_SimpleApplication(), EGS_Application::initRNG(), and volcor::VCOptions::setRNG().

virtual void EGS_RandomGenerator::fillArray	(	int	n,
		EGS_Float *	array
	)

pure virtual

Fill the array of n elements pointed to by array with random numbers.

This pure virtual function must be implemented by derived RNG classes to fill the array array with n random numbers uniformly distributed between 0 (inclusive) and 1 (exclusive). The reason for having the interval defined to exclude unity is the fact that traditionally RNGs used with the EGS system have had this property and therefore in many algorithms this behaviour is assumed (e.g. log(1-r) is used without checking if 1-r is 0).

Implemented in EGS_Ranmar.

Referenced by EGS_SimpleApplication::fillRandomArray(), and EGS_Application::fillRandomArray().

bool EGS_RandomGenerator::storeState ( ostream & data )

Functions for storing, seting and reseting the state of a RNG object.

These functions are useful for being able to perform restarted calculations and to combine the result of parallel runs. They are used by the default implementations of the outputData(), readData(), etc. of the EGS_Application class. The base RNG class implementation stores/reads count, np, ip and rarray to the output or input stream data. Derived RNG classes should should store/read additional data needed to set their state to be the same as at the time of executing one of these functions by reimplementing the pure virtual functions storePrivateState() and setPrivateState().

Definition at line 82 of file egs_rndm.cpp.

References count, egsStoreI64(), ip, np, rarray, and storePrivateState().

Referenced by EGS_Application::outputData().

virtual void EGS_RandomGenerator::describeRNG ( ) const

virtual

Describe this RNG.

Derived RNG classes should reimplement this method to output some information about the RNG being used in ther simulation. This is handy for EGSnrc C++ applications.

Reimplemented in EGS_Ranmar.

Definition at line 256 of file egs_rndm.h.

Referenced by EGS_Application::describeSimulation(), and volcor::VCResults::outputResults().

virtual bool EGS_RandomGenerator::storePrivateState ( ostream & data )

protectedpure virtual

Store the state of the RNG to the output stream data.

Derived RNG classes must implement this function to store as much data as needed to the output stream data so that a RNG object can be set to exactly the same using these data by invoking setPrivateState().

See Also: storeState(), setState().

Implemented in EGS_Ranmar.

Referenced by storeState().

virtual bool EGS_RandomGenerator::setPrivateState ( istream & data )

protectedpure virtual

Set the state of the RNG object from the data in the input stream data.

This method must be implemented in derived RNG classes. It should read the same data as stored by storePrivateState() in the same order from the input stream data.

Implemented in EGS_Ranmar.

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

/home/rwtownson/EGSnrc/HEN_HOUSE/egs++/egs_rndm.h
/home/rwtownson/EGSnrc/HEN_HOUSE/egs++/egs_rndm.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation