MCPlusPlus
A Monte Carlo C++ code for radiative transport
Public Member Functions | List of all members
MCPP::Simulation Class Reference

The Simulation class is the core of the MC method. More...

#include <MCPlusPlus/simulation.h>

+ Inheritance diagram for MCPP::Simulation:
+ Collaboration diagram for MCPP::Simulation:

Public Member Functions

void addHistogram (Histogram *hist)
 Adds a histogram to be performed during the simulation. More...
 
void clear ()
 Clears the simulation internal data.
 
u_int64_t currentPhoton () const
 
u_int64_t nPhotons () const
 The total number of photons to be simulated. More...
 
uint nThreads ()
 
void reportProgress () const
 Print progress information. More...
 
void run ()
 Runs the simulation. More...
 
const Samplesample () const
 
void setExitKVectorsDirsSaveFlags (unsigned int value)
 
void setExitKVectorsSaveFlags (unsigned int value)
 
void setExitPointsSaveFlags (unsigned int value)
 
void setFresnelReflectionsEnabled (bool enable)
 
void setMultipleRNGStates (const vector< string > states)
 Sets a vector of RNG states to be used by the threads. More...
 
void setNPhotons (const u_int64_t N)
 Set the total number of walkers to simulated. More...
 
void setNThreads (unsigned int value)
 Sets the number of parallel threads to be used. More...
 
void setNWalkers (const u_int64_t N)
 
void setOutputFileName (const char *name)
 
void setRawOutputEnabled (bool enable)
 Enables raw output. More...
 
void setSample (Sample *sample)
 Sets the kind of sample to be simulated. The simulation is automatically set as the sample's parent. More...
 
void setSaveTrajectoryEnabled (bool enabled=true)
 Enables saving trajectory points in memory. More...
 
void setSource (Source *source)
 Sets the kind of source to be simulated. The simulation is automatically set as the source's parent. More...
 
void setTimeOriginZ (const MCfloat z)
 Sets the coordinate $ z_0 $ of the origin of times ( $ t = 0 $) More...
 
void setWalkTimesSaveFlags (unsigned int value)
 
 Simulation (BaseObject *parent=NULL)
 
void terminate ()
 Gracefully terminates the currently running simulation. More...
 
const vector< vector< MCfloat > * > * trajectories () const
 Returns the trajectories of the simulated photons. More...
 
- Public Member Functions inherited from MCPP::BaseRandom
 BaseRandom (BaseObject *parent=NULL)
 
unsigned int currentSeed () const
 The seed currently used by the RNG. More...
 
void dumpGeneratorState (const char *fileName) const
 Dumps the RNG internal state to file. More...
 
string generatorState () const
 The RNG internal state. More...
 
void loadGeneratorState (const char *fileName)
 Loads a RNG state from file. More...
 
void setGeneratorState (string state)
 Set the internal RNG state. More...
 
void setSeed (unsigned int seed)
 Sets a new seed for the RNG. More...
 
- Public Member Functions inherited from MCPP::BaseObject
 BaseObject (BaseObject *parent=NULL)
 
list< BaseObject * > childList () const
 
BaseObjectclone () const
 Returns a cloned instance of the current object. More...
 
void describe () const
 Prints a description of the object and its main properties. More...
 
bool hasAParent () const
 
bool inheritsRandom () const
 Determines whether or not the object derives from BaseRandom. More...
 
BaseObjectparent () const
 Returns a pointer to the parent object.
 
bool sanityCheck () const
 Performs a series of integrity checks on internal data to ensure that the object is properly initialized and ready to be used. More...
 
void setParent (BaseObject *parent)
 Makes the object a child of parent. More...
 
string typeName () const
 The class name of the object. More...
 
bool wasCloned () const
 Determines whether or not the object was cloned. More...
 

Additional Inherited Members

- Protected Member Functions inherited from MCPP::BaseObject
void addObjectToCheck (const BaseObject **const obj)
 Adds a BaseObject pointer to the list of objects to be checked. More...
 
void clearObjectsToCheck ()
 
void copyToInternalVariable (char **dest, const char *src)
 
void logMessage (const string &msg) const
 Logs a message to stderr. More...
 
void logMessage (const char *fmt,...) const
 
- Protected Attributes inherited from MCPP::BaseRandom
unsigned int _currentSeed
 
MCEngine * mt
 
- Protected Attributes inherited from MCPP::BaseObject
bool _inheritsRandom
 
list< const BaseObject *const * > objectsToCheck
 

Detailed Description

The Simulation class is the core of the MC method.

In order to set up a simulation, you first have to specify a Sample and a Source using setSample() and setSource(). Use setNWalkers() to specify the total number of walkers to be simulated.

Several Histograms can be performed with every simulation; see addHistogram. The output file can be specified using setOutputFileName(). Additionally, raw output with the data of each single simulated photons can be enabled using setRawOutputEnabled(). In the latter case output flags can be specified with their setter functions: setWalkTimesSaveFlags(), etc.; keep in mind that this causes heavy memory usage and big output file sizes.

Before running the simulation, a RNG has to be initialized by either calling setSeed(), loadGeneratorState() or setGeneratorState(). Use run() to start the simulation.

If you want to run the simulation in parallel threads, use setNThreads() to specify the number of threads to be used. In this case multiple RNG states can be loaded with setMultipleRNGStates(), otherwise sequential numbers from 0 to the number of threads will be used as seeds for each thread.

Signals

The progress of the simulation currently running can be printed on stderr by sending the USR1 signal to the process instantiating a Simulation object. Progress of all threads can be printed by sending SIGUSR2. Finally the TERM signal causes the simulation to terminate gracefully (see terminate()).

Member Function Documentation

◆ addHistogram()

void Simulation::addHistogram ( Histogram hist)

Adds a histogram to be performed during the simulation.

Parameters
histThe simulation is automatically set as the histogram's parent. Histograms are performed live during the simulation, At the end of the simulation, histograms are saved in the H5 output file specified using setOutputFileName(), each in a different dataset according to their names.

◆ nPhotons()

u_int64_t Simulation::nPhotons ( ) const

The total number of photons to be simulated.

Returns

◆ reportProgress()

void Simulation::reportProgress ( ) const

Print progress information.

This can also be triggered by sending the USR1 signal to the process instantiating the Simulation object.

◆ run()

void Simulation::run ( )

Runs the simulation.

Defaults to single thread operation. Use setNThreads() to set the number of parallel threads used to run the simulation.

Precondition
The RNG has to be valid (see BaseRandom)

◆ setMultipleRNGStates()

void Simulation::setMultipleRNGStates ( const vector< string >  states)

Sets a vector of RNG states to be used by the threads.

Parameters
states

If the vector is not set or has fewer elements than the specified number of threads to be run, a new RNG with a sequential seed will be created.

◆ setNPhotons()

void Simulation::setNPhotons ( const u_int64_t  N)

Set the total number of walkers to simulated.

Parameters
N

◆ setNThreads()

void Simulation::setNThreads ( unsigned int  value)

Sets the number of parallel threads to be used.

Parameters
value

◆ setRawOutputEnabled()

void Simulation::setRawOutputEnabled ( bool  enable)

Enables raw output.

Parameters
enableIf enabled, per photon values are saved in the output file according to the specified flags. See setWalkTimesSaveFlags(), setExitPointsSaveFlags(), setExitKVectorsSaveFlags(). Keep in mind that this causes heavy memory usage and big output file sizes.

◆ setSample()

void Simulation::setSample ( Sample sample)

Sets the kind of sample to be simulated. The simulation is automatically set as the sample's parent.

Parameters
sample

◆ setSaveTrajectoryEnabled()

void Simulation::setSaveTrajectoryEnabled ( bool  enabled = true)

Enables saving trajectory points in memory.

Parameters
enabled

This function works only if the library is compiled with the ENABLE_TRAJECTORY option, which defaults to false for performance reasons.

◆ setSource()

void Simulation::setSource ( Source source)

Sets the kind of source to be simulated. The simulation is automatically set as the source's parent.

Parameters
source

◆ setTimeOriginZ()

void Simulation::setTimeOriginZ ( const MCfloat  z)

Sets the coordinate $ z_0 $ of the origin of times ( $ t = 0 $)

Parameters
z

If the photon source is placed at a coordinate $ z \neq z_0 $, then the photon time distribution – which is specified at the source position – is offset (with sign) by the time it takes for the photon to travel from the source to $ z_0 $ (or viceversa) flying in a straight line and crossing the boundaries at 90°. This property defaults to $ z = 0 $.

◆ terminate()

void Simulation::terminate ( )

Gracefully terminates the currently running simulation.

Causes run() to return as soon as the photon currently being simulated is completed. The simulation data is written to the output file as usual. This function can also be triggered by sending the TERM signal to the process instantiating the Simulation object; every thread will be terminated gracefully.

◆ trajectories()

const vector< vector< MCfloat > * > * Simulation::trajectories ( ) const

Returns the trajectories of the simulated photons.

Returns

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