A simple run control object for advanced EGSnrc C++ applications. More...

#include <egs_run_control.h>

Inheritance diagram for EGS_RunControl:

Public Types
enum	RCOType { simple, uniform, balanced }
	Define RCO types. More...

Public Member Functions
	EGS_RunControl (EGS_Application *app)
	Creates an RCO for the application app. More...

virtual	~EGS_RunControl ()
	Destructor.

void	setNcase (EGS_I64 n)
	Set the number of particles to be simulated to n.

void	setNbatch (int n)
	Set the number of batches to n.

void	setMaxTime (EGS_Float t)
	Set the maximum CPU time for the simulation to t.

void	setRequiredUncertainty (EGS_Float a)
	Set the required statistical uncertainty to a.

EGS_I64	getNcase () const
	Returns the total number of particles to be simulated.

int	getNbatch () const
	Returns the number of batches per simulation chunk.

int	getNchunk () const
	Returns the number of simulation chunks.

virtual int	startSimulation ()
	Starts the simulation. More...

virtual EGS_I64	getNextChunk ()
	Returns the number of histories to run in the next simulation chunk. More...

virtual int	finishSimulation ()
	Finish the simulation. More...

virtual bool	startBatch (int, EGS_I64)
	Start a new batch. More...

virtual bool	finishBatch ()
	Finish a batch. More...

virtual void	describeRCO ()

virtual bool	storeState (ostream &data)

virtual bool	setState (istream &data)

virtual bool	addState (istream &data)

virtual void	resetCounter ()

virtual bool	getCombinedResult (double &, double &) const

virtual EGS_I64	getNdone () const

virtual void	setNdone (EGS_I64 Ndone)

virtual void	incrementNdone ()

virtual EGS_Float	getCPUTime () const

Static Public Member Functions
static EGS_RunControl *	getRunControlObject (EGS_Application *)

Public Attributes
int	geomErrorCount

int	geomErrorMax

Protected Attributes
EGS_Application *	app

EGS_Input *	input

EGS_I64	ncase

EGS_I64	ndone

EGS_Float	maxt

EGS_Float	accu

int	nbatch

int	restart

int	nchunk

RCOType	rco_type
	RCO type to use.

EGS_Timer	timer

EGS_Float	cpu_time

EGS_Float	previous_cpu_time

Detailed Description

A simple run control object for advanced EGSnrc C++ applications.

In EGSnrc applications derived from EGS_AdvancedApplication the program execution is controlled by a 'run control object' (RCO). The purpose of the RCO is to tell the shower loop into how many 'chunks' the simulation should be split, how many particles to run per simulation chunk, into how many batches to split a simulation chunk, etc. In this way it is easy for EGSnrc C++ application developers to either use one of the RCO's provided with egspp or to implement their own RCO's with alternative implementations or strategies for {e.g.} parallel job processing.

Terminology

Simulations are split into 'chunks'. For simple simulations (no parallel runs, etc.) there is a single simulation chunk with the number of histories specified in the input file.
Each simulation chunk is split into 'batches'. The batches are not required for statistical analysis (by using the provided scoring classes it is easy to has a history-by-history uncertainty estimation). Instead, simulation chunks are split into batches so that the progress of the simulation can be reported after the completion of a batch and the current results can be stored into a data file. By default there are 10 batches per simulation chunk

Three RCO's are provided with egspp:

A 'simple' RCO implemented in EGS_RunControl. This RCO is used by default for single job control. This RCO provides the ability to run simulations with a user specified number of particles and up to a user specified statistical uncertainty. It also provides the ability to restrict the simulation to a user specified maximum CPU time, to perform restarted simulations or to simply analyze the results of a previous run or to combine the results of previously performed parallel runs.
A 'job control file' (JCF) RCO . This RCO is used by default for parallel runs. It has all the functionality of the 'simple' RCO plus additional methods to control parallel execution via a 'job control file'.
A uniform RCO . This RCO distributes the histories uniformly among all jobs. It can be an alternative to the JCF RCO when a JCF cannot be used. This can happen when jobs do not start sequentially. In such cases the JCF may not be available if job number 1 is not started first.

Definition at line 94 of file egs_run_control.h.

Member Enumeration Documentation

enum EGS_RunControl::RCOType

Define RCO types.

Enumerator
simple	single job or multiple independent jobs
uniform	parallel jobs with same numbe of histories
balanced	parallel jobs with balanced load via JCF

Definition at line 224 of file egs_run_control.h.

Constructor & Destructor Documentation

EGS_RunControl::EGS_RunControl ( EGS_Application * app )

Creates an RCO for the application app.

This constructors obtains the user input to the application (available to the application as an EGS_Input object) and looks for

Definition at line 54 of file egs_run_control.cpp.

References egsFatal, egsWarning, EGS_Input::getInput(), EGS_Application::getInput(), EGS_Application::getNparallel(), and EGS_Input::takeInputItem().

Member Function Documentation

int EGS_RunControl::startSimulation ( )

virtual

Starts the simulation.

Returns zero if the simulation was successfully started, a positive value if no error occured but no histories are to be run (e.g. combine and analyze runs) and a negative value if some error occured.

Definition at line 182 of file egs_run_control.cpp.

References EGS_Application::combineResults(), EGS_Application::describeSimulation(), egsInformation, EGS_Application::readData(), and EGS_Timer::start().

Referenced by EGS_Application::runSimulation().

virtual EGS_I64 EGS_RunControl::getNextChunk ( )

virtual

Returns the number of histories to run in the next simulation chunk.

In a simple run this is simply the number of histories specified in the input file. For parallel runs the simulation is split into smaller 'chunks' and this function returns how many histories are in such a chunk. This function is called from within the runSimulation() function of EGS_Application.

Definition at line 166 of file egs_run_control.h.

Referenced by EGS_Application::runSimulation().

int EGS_RunControl::finishSimulation ( )

virtual

Finish the simulation.

This function is called from within the finishSimulation() method of EGS_Application and should return 1 of the follwoing 3 exit codes:

-1 indicates that some error occured
0 indicates that everything was OK and the application should simply exit.
1 indicates that everything was OK and that this job is the last job in a parallel run.

Reimplemented in EGS_UniformRunControl.

Definition at line 823 of file egs_run_control.cpp.

References egsInformation, EGS_Application::getElectronSteps(), EGS_Application::getFirstParallel(), EGS_Application::getIparallel(), EGS_Application::getNparallel(), EGS_Application::randomNumbersUsed(), and EGS_Timer::time().

Referenced by EGS_AdvancedApplication::finishSimulation(), EGS_Application::finishSimulation(), and EGS_UniformRunControl::finishSimulation().

bool EGS_RunControl::startBatch	(	int	ibatch,
		EGS_I64	ncase_per_batch
	)

virtual

Start a new batch.

This function is called from within the shower loop before starting each new batch. Returns true, if the simulation is to proceed, false if the simulation is to be terminated immediately.

Definition at line 216 of file egs_run_control.cpp.

References egsInformation, and egsWarning.

Referenced by EGS_Application::runSimulation().

bool EGS_RunControl::finishBatch ( )

virtual

Finish a batch.

This function is called from within the shower loop after a batch has been finished. Returns true, if the simulation is to proceed, false if the simulation is to be terminated immediately.

Definition at line 234 of file egs_run_control.cpp.

References egsInformation, egsWarning, EGS_Application::getCurrentResult(), EGS_Application::outputData(), and EGS_Timer::time().

Referenced by EGS_Application::runSimulation().

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

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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation