Base class for advanced EGSnrc C++ applications. More...

#include <egs_application.h>

Inheritance diagram for EGS_Application:

Public Types
enum	AusgabCall { BeforeTransport = 0, EgsCut = 1, PegsCut = 2, UserDiscard = 3, ExtraEnergy = 4, AfterTransport = 5, BeforeBrems = 6, AfterBrems = 7, BeforeMoller = 8, AfterMoller = 9, BeforeBhabha = 10, AfterBhabha = 11, BeforeAnnihFlight = 12, AfterAnnihFlight = 13, BeforeAnnihRest = 28, AfterAnnihRest = 14, BeforePair = 15, AfterPair = 16, BeforeCompton = 17, AfterCompton = 18, BeforePhoto = 19, AfterPhoto = 20, EnteringUphi = 21, LeavingUphi = 22, BeforeRayleigh = 23, AfterRayleigh = 24, FluorescentEvent = 25, CosterKronigEvent = 26, AugerEvent = 27, BeforePhotoNuc = 29, AfterPhotoNuc = 30, BeforeEII = 31, AfterEII = 32, AfterSubPhoton = 33, AfterSubElectron = 34, UnknownCall = 35 }
	Possible calls to the user scoring function ausgab(). More...

Public Member Functions
	EGS_Application (int argc, char **argv)
	Construct an EGSnrc application. More...

virtual	~EGS_Application ()
	Destruct the EGSnrc application. More...

virtual int	initSimulation ()
	Initializes the EGSnrc application. More...

virtual void	setSimulationChunk (EGS_I64 nstart, EGS_I64 nrun)
	Set the simulation chunk. More...

virtual int	runSimulation ()
	Runs an EGSnrc simulation. More...

virtual int	finishSimulation ()
	Analyze and output the results. More...

virtual void	describeSimulation ()
	Describe the simulation. More...

virtual int	simulateSingleShower ()
	Simulates a single particle shower. More...

virtual void	getCurrentResult (double &sum, double &sum2, double &norm, double &count)
	Report the current result. More...

virtual void	analyzeResults ()
	Analyze the simulation results. More...

virtual void	outputResults ()
	Output the simulation results. More...

virtual int	combineResults ()
	Combine results from parallel runs. More...

virtual int	combinePartialResults ()
	Combine intermediate results from parallel runs. More...

int	howManyJobsDone ()
	Counts how many *.egsdat files in app folder. More...

virtual int	outputData ()
	Output intermediate results. More...

virtual int	readData ()
	Read intermediate results. More...

EGS_Input *	getInput ()
	Returns a pointer to the EGS_Input object containing the user input to the application found in the input file.

const string &	getAppName () const
	Returns the application name.

const string &	getEgsHome () const
	Returns the `EGS_HOME` directory.

const string &	getHenHouse () const
	Returns the `HEN_HOUSE` directory.

const string &	getOutputFile () const
	Returns the base name of the output file(s)

const string &	getFinalOutputFile () const
	Returns the base name of the final output file(s) More...

string	constructIOFileName (const char *extension, bool with_run_dir) const
	Constructs and returns the name of an input/output file. More...

const string &	getAppDir () const
	Returns the absolute path to the user code directory.

const string &	getRunDir () const
	Returns the name of the working directory.

const string &	getWorkDir () const
	Returns the name of the working directory.

virtual void	setAusgabCall (AusgabCall call, bool on_or_off)
	Turns on or off a call to the user scoring function ausgab. More...

int	getNparallel () const
	Returns the number of parallel jobs executing. More...

int	getIparallel () const
	Returns the job number in a parallel run. More...

int	getFirstParallel () const
	Returns the first job number in a parallel run. More...

int	howfar (int ireg, const EGS_Vector &x, const EGS_Vector &u, EGS_Float &t, int *newmed)
	Calculates distance to a boundary along the current direction. More...

EGS_Float	hownear (int ireg, const EGS_Vector &x)
	Calculates nearest distance to a boundary in any direction. More...

int	getMedium (int ireg)
	Returns the medium index in region ireg using C-style indexing.

bool	isRealRegion (int ireg)
	Returns true if ireg is a real region, false otherwise. More...

int	isWhere (EGS_Vector &r)

void	getNumberRegions (const string &str, vector< int > &regs)
	Gets numbers out of str and pushes them onto regs. More...

void	getLabelRegions (const string &str, vector< int > &regs)
	Gets the regions for the labels in str and pushes onto regs. More...

EGS_Float	getMU ()
	Returns the value of the mu synchronization parameter. More...

int	userScoring (int iarg, int ir=-1)
	User scoring function for accumulation of results and VRT implementation. More...

virtual int	ausgab (int)
	User scoring function. More...

virtual void	startNewParticle ()
	Start the transport of a new particle. More...

virtual void	enterNewRegion ()
	Particle enters new region. More...

virtual void	fillRandomArray (int n, EGS_Float *rns)
	Fill an array with random numbers using the application's RNG. More...

virtual EGS_I64	randomNumbersUsed () const
	Returns the number of random numbers used. More...

virtual void	getElectronSteps (double &ch_steps, double &all_steps) const
	Get the number of electron steps taken. More...

virtual int	addState (istream &data)
	Add data from a parallel job. More...

virtual void	resetCounter ()
	Reset the application to a 'pristine' state. More...

virtual void	describeUserCode () const
	Describe the user code. More...

virtual void	appInformation (const char *)
	Write an information message.

virtual void	appWarning (const char *)
	Write a warning message.

virtual void	appFatal (const char *)
	Write a warning message and exit.

void	checkDeviceFull (FILE *)
	Check if a device holding a given stream is full.

EGS_Float	getFluence ()

int	getnRegions ()

int	getnMedia ()

const char *	getMediumName (int ind)

virtual EGS_Float	getMediumRho (int ind)

virtual EGS_Float	getEdep ()

virtual void	setEdep (EGS_Float edep)

virtual EGS_Float	getEcut ()

virtual EGS_Float	getPcut ()

virtual EGS_Float	getRM ()

virtual void	setRadiativeSplitting (const EGS_Float &nsplit)

virtual EGS_Float	getTVSTEP ()

virtual EGS_Interpolator *	getDEDX (const int &imed, const int &iq)

string	sourceType ()

int	sourceCharge ()

int	sourceEmax ()

virtual void	setLatch (const int &ip, const int &latch)

virtual void	incLatch (const int &ip, const int &increment)

virtual int	getNp ()

virtual int	getNpOld ()

virtual void	setLatch (int latch)

Static Public Member Functions
static EGS_Application *	activeApplication ()
	Get the active application. More...

static void	setActiveApplication (EGS_Application *)
	Set the active EGS_Application class. More...

static bool	getArgument (int &argc, char *argv, const char name1, const char *name2, string &arg)
	Finds a command line argument. More...

static void	checkEnvironmentVar (int &argc, char *argv, const char env, const char n1, const char n2, string &var)
	Finds a command line argument. More...

Public Attributes
EGS_Particle	top_p
	The top particle on the stack (i.e., the particle being transported)

int	Np
	The index of the top particle on the stack.

Protected Member Functions
virtual int	initGeometry ()
	Initialize the simulation geometry. More...

virtual int	initSource ()
	Initialize the particle source. More...

virtual int	initCrossSections ()
	Initialize the EGSnrc cross sections and cross section/transport options. More...

virtual int	initScoring ()
	Initialize the scoring of quantities of interest. More...

virtual int	initRunControl ()
	Construct the run control object. More...

virtual int	initRNG ()
	Initialize the random number generator. More...

virtual int	initEGSnrcBackEnd ()
	Initialize the EGSnrc backend. More...

void	initAusgabObjects ()
	Initialize ausgab objects. More...

void	addAusgabObject (EGS_AusgabObject *o)
	Adds an ausgab object to the list of ausgab objects.

virtual int	startNewShower ()
	Called just before the shower() function. More...

virtual int	finishShower ()
	Called just after the shower() function. More...

virtual int	shower ()
	Simulate a single shower. More...

virtual void	finishRun ()

void	storeGeometryStep (int ireg, int inew, const EGS_Vector &x, const EGS_Vector &u, EGS_Float twant, EGS_Float t)

void	reportGeometryError ()

Protected Attributes
EGS_Input *	input
	the input to this simulation.

EGS_BaseGeometry *	geometry
	the geometry of this simulation

EGS_BaseSource *	source
	the particle source

EGS_RandomGenerator *	rndm
	the random number generator

EGS_RunControl *	run
	the run control object.

bool	ausgab_flag [UnknownCall]
	on/off flags for ausgab calls

string	app_name
	The application name.

string	egs_home
	The EGS_HOME directory.

string	hen_house
	The HEN_HOUSE directory.

string	app_dir
	The user code directory.

string	run_dir
	The working directory during the run.

string	egs_config
	The EGSnrc config.

string	input_file
	The input file name.

string	output_file
	The output file name (no extension)

string	final_output_file
	The final output file name.

string	pegs_file
	The pegs file name.

string	abs_pegs_file
	The pegs file name including absolute path.

int	n_parallel
	Number of parallel jobs.

int	i_parallel
	Job index in parallel runs.

int	first_parallel
	first parallel job number

bool	batch_run
	Interactive or batch run.

bool	simple_run
	Use a simple run control object for parallel runs.

bool	uniform_run
	Use a uniform run control object for parallel runs.

bool	is_pegsless
	set to true if a pegsless run

EGS_Particle	p

EGS_I64	current_case
	The current case as returned from the source.

EGS_I64	last_case
	The last case simulated.

ostream *	data_out
	data output stream More...

istream *	data_in
	data input stream More...

int	app_index
	the index of this application. More...

EGS_SimpleContainer < EGS_AusgabObject * >	a_objects_list
	The ausgab objects.

EGS_SimpleContainer < EGS_AusgabObject * > *	a_objects
	The ausgab objects for the various ausgab calls.

EGS_GeometryHistory *	ghistory

Detailed Description

Base class for advanced EGSnrc C++ applications.

The recommended method for developing EGSnrc C++ applications is to derive an application class from one of the advanced application classes. At this point, the EGS_AdvancedApplication class, which is based on the mortran version of EGSnrc, is the only class available. However, when EGSnrc is reimplemented in C++ there will be a corresponding EGS_AdvancedCppApplication class. The EGS_Application class implements all functionality that is independent on the details of the physics functions implementation (mortran vs C++). The motivation behind this approach is that EGSnrc applications developed for the mortran back-end should work with as little change as possible with a future EGSnrc version written in C++.

EGS_Application and EGS_AdvancedApplication implement a large portion of the work needed to develop an EGSnrc user code. Many of the functions implementing particular aspects of the initialization, the simulation loop, the storing of intermediate results, etc., are declared virtual to provide a high level of flexibility, but in general only very few of the virtual functions must be re-implemented in derived classes. The following is a brief recipe for developing an EGSnrc application derived from EGS_AdvancedApplication. For the sake of a concrete example we will assume that the application calculates the dose distribution in all regions of the geometry specified in the input file and that the class derived from EGS_AdvancedApplication implementing this functionality is called MyDoseApplication.

Re-implement initScoring() to initialize the scoring of quantities of interest. In many cases the initialization will simply involve the construction of one or more EGS_ScoringArray objects, which will be used to accumulate the quantites of interest at run time. It is of course possible to have more advanced initialization controlled via a section in the input file that can be obtained from the input protected data member (see e.g. cavity.cpp for an example). For our example case of a sode scoring application the implementation could look like this
```
  int MyDoseApplication::initScoring() {
      dose = new EGS_ScoringArray(geometry->regions());
      return 0;
  }
```
Here, dose is a class member of type EGS_ScoringArray *.
Re-implement the startNewShower() function. In most cases the implementation will consist of calling the EGS_ScoringArray::setHistory() function of all scoring array objects used for accumulating results. This is necessary for the history-by-history statistical analysis. In our example the implementation should look like this
```
  int MyDoseApplication::startNewShower() {
      if( current_case != last_case ) {
          dose->setHistory(current_case);
          last_case = current_case;
      }
      return 0;
  }
```
Re-implement the outputData() function to output the current simulation results to a data file. This is necessary for the ability to restart a simulation or to combine the results of a parallel run. In most cases the implementation will involve calling the EGS_AdvancedApplication version first, so that data related to the state of the particle source, the random number generator, the EGSnrc back-end, etc., is stored, and than calling the storeState() function of the scoring objects. In our example case the implementation should look like this:
```
  int MyDoseApplication::outputData() {
      int err = EGS_AdvancedApplication::outputData();
      if( err ) return err;
      if( !dose->storeState(*data_out) ) return 99;
      return 0;
  }
```
i.e. if an error occurs while storing the base application data the function returns this error code. Otherwise it stores the dose data and returns a special error code if EGS_ScoringArray::storeState() fails.
Re-implement the readData() function to read results from a data file. This is necessary for restarted calculations and is basically the same as outputData() but now readData() and setState() are used instead of outputData() and storeState():
```
  int MyDoseApplication::readData() {
      int err = EGS_AdvancedApplication::readData();
      if( err ) return err;
      if( !dose->setState(*data_in) ) return 99;
      return 0;
  }
```
Re-implement the resetCounter() function. This function is called before combining the results of a parallel run and should set all scoring objects to a 'pristine' state. In our example the implementation looks like this:
```
  void MyDoseApplication::resetCounter() {
      EGS_AdvancedApplication::resetCounter();
      dose->reset();
  }
```

Re-implement the addState() function. This function is called from within the loop over parallel job results and should add the data found in the data stream passed as argument to the current data. In our example the implementation is as follows

  int MyDoseApplication::addState(istream &data) {
      // **** add base data
      int err = EGS_AdvancedApplication::addState(data);
      if( err ) return err;
      // *** temporary scoring array
      EGS_ScoringArray tmp(geometry->regions());
      if( !tmp.setState(data) ) return 99; // error while reading data
      (*dose) += tmp;                      // add data
      return 0;
  }

Implement the ausgab() function to perform the actual scoring. Unfortunately, this is dependent upon the simulation back-end. For an application based on the mortran back-end, the relevant data is available from pointers to the Fortran common blocks with the general rule that the Fortran common block XXX is accessed via the_xxx, e.g. the particle stack is pointed to by the_stack, the EPCONT common that contains information about energy deposition, step-lengths, region indeces, etc., via the_epcont, etc. Information about the various EGSnrc common blocks is found in PIRS-701. The common blocks exported as C-style structures are defined in $HEN_HOUSE/interface/egs_interface2.h. Depending on the application, the ausgab() function may be quite complex. In our example application it is very simple:
```
  int MyDoseApplication::ausgab(int iarg) {
      if( the_epcont->edep > 0 ) { // energy is being deposited
          int np = the_stack->np - 1; // top particle on the particle stack.
          int ir = the_stack->ir[np]-2; // region index
          if( ir >= 0 ) dose->score(ir,the_epcont->edep*the_stack->wt[np]);
      }
      return 0;
  }
```
In the above implementation no check is being made for the value of the iarg argument. This is because by default calls to ausgab() are made only for energy deposition events. However, in more advanced applciations, one can set up calls to ausgab for a number of other events (see PIRS-701, EGS_Application::AusgabCall, setAusgabCall()) and should check the value of iarg to determine the type of event initiating the call to ausgab(). Another thing to keep in mind is the fact that the Fortran-style indexing is used by the mortran back-end so that the top stack particle is the_stack->np - 1 and not the_stack->np. Finally, the convention used in the geometry package is that the outside region has index -1 while inside regions have indeces from 0 to the number of regions - 1. This convention is translated to the outside region being region 1 in the mortran back-end and inside regions having indeces 2 to number of regions + 1 and makes the subtraction of 2 from the particle region index necessary.
Re-implement the outputResults() function. The implementation should output the results of the simulation in a convenient form. Relatively short output could be put into the .egslog file by using the egsInformation() function for writing the data. Large amounts of data are better output into separate output files. To construct an output file name the application has access to the base output file name (without extension) via getOutputFile(), to the application directory via getAppDir(), to the working directory via getWorkDir(), etc.
Possibly re-implement the getCurrentResult() function to provide a single result and its uncertainty. This is not necessary for the proper operation of the application but is a nice feature. It is used to obtain a combined result for all parallel jobs during parallel processing execution, which is written to the job control file. In our example dose application one could for instance provide as the single result the dose in a single 'watch region':
```
  void MyDoseApplication::getCurrentResult(double &sum, double &sum2,
                              double &norm, double &count) {
      // set number of statistically independent events
      count = current_case;
      // obtain the score in the watch region
      dose->currentScore(watch_region,sum,sum2);
      // set the normalization
      norm = 1.602e-10*count/source->getFluence()/watch_region_mass;
  }
```
It is worth noting that in the process of combining the results of all parallel runs the run control object divides the result by the total number of statistically independent events. If we want the normalization to be in Gy/incident fluence we have to multiply back by count and then divide by the watch region mass, the particle fluence and multiply with 1.602e-10 to convert the energy deposited (counted in MeV) to J.
Possibly re-implement the describeUserCode() and describeSimulation() functions to provide a description of your user code and a description of the simulation being performed with both outputs going to the log file.

Todo:: Add time dependence

Definition at line 267 of file egs_application.h.

Member Enumeration Documentation

enum EGS_Application::AusgabCall

Possible calls to the user scoring function ausgab().

Enumerator
BeforeTransport	before the step
EgsCut	energy below Ecut or Pcut
PegsCut	energy below AE or AP
UserDiscard	user requested discard
ExtraEnergy	initiated when part of the energy is not transferred to particles (e.g. binding energy)
AfterTransport	after the step
BeforeBrems	before a bremsstrahlung interaction
AfterBrems	after a bremsstrahlung interaction
BeforeMoller	before an inelastic collision (e-)
AfterMoller	after an inelastic collision (e-)
BeforeBhabha	before an inelastic collision (e+)
AfterBhabha	after an inelastic collision (e+)
BeforeAnnihFlight	before annihilation in flight
AfterAnnihFlight	after annihilation in flight
BeforeAnnihRest	before annihilation at rest
AfterAnnihRest	after annihilation at rest
BeforePair	before pair production
AfterPair	after pair production
BeforeCompton	before a Compton scattering event
AfterCompton	after a Compton scattering event
BeforePhoto	before a photo-absorption event
AfterPhoto	after a photo-absorption event
EnteringUphi	the rotation routine was just entered
LeavingUphi	I consider the above 2 to be obsolete. about to leave the rotation routine
BeforeRayleigh	before coherent scattering
AfterRayleigh	after coherent scattering
FluorescentEvent	a fluorescent transition just occured
CosterKronigEvent	a Coster-Kronig transition just occured
AugerEvent	an Auger transition just occured
BeforePhotoNuc	before a photonuclear event
AfterPhotoNuc	after a photonuclear event
BeforeEII	before electron impact ionization
AfterEII	after electron impact ionization
AfterSubPhoton	after sub-threshold photon energy deposition
AfterSubElectron	after sub-threshold electron energy deposition
UnknownCall	last element in the enumeration

Definition at line 539 of file egs_application.h.

Constructor & Destructor Documentation

EGS_Application::EGS_Application	(	int	argc,
		char **	argv
	)

Construct an EGSnrc application.

The constructor checks the arguments passed on the command line and sets up the name of the application, the input file name, the pegs file name, the output file name, the working directory, batch vs interactive run, parallel job execution (i_parallel and n_parallel) and reads in the input file into an EGS_Input object (a pointer to this object is available with the protected data member input)

Definition at line 225 of file egs_application.cpp.

References AfterTransport, app_dir, app_index, app_name, ausgab_flag, batch_run, BeforeTransport, checkEnvironmentVar(), egs_home, egsFatal, egsGetPid(), egsHostName(), egsJoinPath(), egsStripPath(), egsWarning, final_output_file, first_parallel, getArgument(), hen_house, i_parallel, input, input_file, is_pegsless, n_parallel, output_file, run_dir, EGS_Input::setContentFromFile(), simple_run, uniform_run, and UnknownCall.

EGS_Application::~EGS_Application ( )

virtual

Destruct the EGSnrc application.

The destructor deletes the random number generator, the run control object, the input object, the source and the geometry.

Definition at line 961 of file egs_application.cpp.

References a_objects, app_index, EGS_Object::deleteObject(), EGS_BaseGeometry::deref(), geometry, input, rndm, run, EGS_BaseGeometry::setActiveGeometryList(), and source.

Member Function Documentation

int EGS_Application::initSimulation ( )

virtual

Initializes the EGSnrc application.

The default implementation of this function performs initializations related to the geometry, the source, the random number generator, the run control object, the EGSnrc mortran back end, the cross sections and the scoring of quantities of interest by calling in succession the protected virtual functions initGeometry(), initSource(), initRNG(), initRunControl(), initEGSnrcBackEnd(), initCrossSections() and initScoring().

If all calls succeed (i.e. the above functions return zero) the return value is zero.
The return value is 1 if any of initGeometry(), initSource(), initRNG() or initRunControl() returns a non-zero status,
2 if initEGSnrcBackEnd() returns a non-zero status,
3 if initCrossSections() returns a non-zero status and
4 if initScoring() returns a non-zero status.

The EGSnrc C++ application developer can change the way an EGSnrc application is initialized by re-implementing this function or one of the virtual functions called from it.

Definition at line 750 of file egs_application.cpp.

References describeUserCode(), egsInformation, egsWarning, initAusgabObjects(), initCrossSections(), initEGSnrcBackEnd(), initGeometry(), initRNG(), initRunControl(), initScoring(), and initSource().

void EGS_Application::setSimulationChunk	(	EGS_I64	nstart,
		EGS_I64	nrun
	)

virtual

Set the simulation chunk.

Tells the application that the next chunk of particles to be simulated starts at nstart and will consist of nrun particles. This is necessary for parallel runs using phase space files. The default implementation simply calls the EGS_BaseSource::setSimulationChunk() method.

Definition at line 801 of file egs_application.cpp.

References EGS_BaseSource::setSimulationChunk(), and source.

int EGS_Application::runSimulation ( )

virtual

Runs an EGSnrc simulation.

This function performs the actual simulation. In its default implementation, the shower loop is a loop that is repeated while the getNextChunk() function of the run control object returns a positive number of histories to run. Each time getNextChunk() returns a positive number of histories to simulate, this number is split into "batches" (the number of batches is obtained from the run control object using getNbatch()) and the startBatch() and finishBatch() functions of the run control object are called at the beginning and end of a batch. The startBatch() and finishBatch() functions are virtual and can be re-implemented in derived classes to do things such as reporting the progress of the simulation, storing intermediate results into files, etc. In each batch the simulateSingleShower() function is called the appropriate number of times. The loop over single showers is terminated if simulateSingleShower() returns a non-zero status. The loop over batches is terminated if either startBatch() or finishBatch() returns a non-zero status.

Definition at line 836 of file egs_application.cpp.

References egsInformation, egsWarning, EGS_RunControl::finishBatch(), geometry, EGS_RunControl::getNbatch(), EGS_RunControl::getNextChunk(), rndm, run, simulateSingleShower(), source, EGS_RunControl::startBatch(), and EGS_RunControl::startSimulation().

int EGS_Application::finishSimulation ( )

virtual

Analyze and output the results.

The default implementation of this function calls the finishSimulation method of the run control object and simply returns its exit code if this is negative (indicating some sort of an error condition). Otherwise outputResults() and finishRun() are called in succession.

Reimplemented in EGS_AdvancedApplication.

Definition at line 1039 of file egs_application.cpp.

References a_objects_list, data_out, EGS_RunControl::finishSimulation(), outputResults(), run, and run_dir.

Referenced by EGS_AdvancedApplication::finishSimulation().

void EGS_Application::describeSimulation ( )

virtual

Describe the simulation.

This function should produce information about the geometry, source, transport parameter, scoring options, etc. The default implementation described the geometry and the source.

Reimplemented in EGS_AdvancedApplication.

Definition at line 807 of file egs_application.cpp.

References a_objects_list, EGS_RandomGenerator::describeRNG(), egsInformation, geometry, EGS_BaseSource::getSourceDescription(), EGS_BaseGeometry::printInfo(), rndm, run, and source.

Referenced by EGS_AdvancedApplication::describeSimulation(), and EGS_RunControl::startSimulation().

int EGS_Application::simulateSingleShower ( )

virtual

Simulates a single particle shower.

The default implementation of this function obtaines particles from the source until a particle is inside the geometry or the particle trajectory enters the geometry (if no particle out of 100000 particles enters the geometry there is a warning issued and 1 is returned to the calling function). When a particle enters the geometry, the startNewShower(), shower() and finishShower() functions are called in succession. If any of these functions returns a non-zero status, simulateSingleShower() returns immediately with this status (so that, if all other calls are successful, the return value of finishShower() becomes the return value of simulateSingleShower() )

Definition at line 916 of file egs_application.cpp.

References current_case, EGS_Particle::E, egsWarning, finishShower(), geometry, EGS_BaseSource::getNextParticle(), EGS_BaseGeometry::howfar(), EGS_Particle::ir, EGS_BaseGeometry::isWhere(), last_case, EGS_Particle::latch, p, EGS_Particle::q, rndm, shower(), source, startNewShower(), EGS_Particle::u, veryFar, EGS_Particle::wt, and EGS_Particle::x.

Referenced by runSimulation().

virtual void EGS_Application::getCurrentResult	(	double &	sum,
		double &	sum2,
		double &	norm,
		double &	count
	)

virtual

Report the current result.

This virtual function should be re-implemented in derived classes to report intermediate results during a simulation.

Definition at line 387 of file egs_application.h.

Referenced by EGS_RunControl::finishBatch().

virtual void EGS_Application::analyzeResults ( )

virtual

Analyze the simulation results.

This virtual function should be re-implemented in derived classes to perform the statistical analysis of the simulation results.

Definition at line 400 of file egs_application.h.

virtual void EGS_Application::outputResults ( )

virtual

Output the simulation results.

This virtual function should be re-implemented in derived classes to output the simulation results.

Definition at line 407 of file egs_application.h.

Referenced by combinePartialResults(), EGS_AdvancedApplication::finishSimulation(), and finishSimulation().

int EGS_Application::combineResults ( )

virtual

Combine results from parallel runs.

The default implementation of this function first calls resetCounter() to set the application to a 'pristine' state and then loops over all files with file names of the form ofile_wX.egsdat, where ofile is the output file name for the parallel run and X is an integer between 1 and 100, adding the data from these files using addState(). This implementation should work for almost any situation. Nevertheless, combineResults() is declared as virtual to give the possibility for re-implementation, just in case something unusual needs to be done to sum the results of parallel runs.

Definition at line 621 of file egs_application.cpp.

References addState(), app_dir, egsInformation, egsJoinPath(), egsWarning, final_output_file, first_parallel, n_parallel, resetCounter(), and run.

Referenced by combinePartialResults(), EGS_AdvancedApplication::finishSimulation(), and EGS_RunControl::startSimulation().

int EGS_Application::combinePartialResults ( )

virtual

Combine intermediate results from parallel runs.

Calls combineResults, followed by the output of intermediate results. Currently used by the uniform RCO while a watcher job is waiting for all jobs to complete.

Definition at line 609 of file egs_application.cpp.

References a_objects_list, combineResults(), and outputResults().

Referenced by EGS_UniformRunControl::finishSimulation().

int EGS_Application::howManyJobsDone ( )

Counts how many *.egsdat files in app folder.

Used by the uniform RCO to estimate how many parallel runs completed. This RCO initially deletes existing *.egsdat files to avoid counting files from previous runs. It is an estimate since some jobs might have failed.

Definition at line 593 of file egs_application.cpp.

References app_dir, egsJoinPath(), final_output_file, first_parallel, and n_parallel.

Referenced by EGS_UniformRunControl::finishSimulation().

int EGS_Application::outputData ( )

virtual

Output intermediate results.

This function stores the state of the application to a data file. Stored quantities are last_case, the state of the run control object, the state of the source object and the state of the random number generator. The data is stored in coutput_file.egsdat and data_out points to the output data stream created by opening the file. Derived classes should re-implement to add their own data to the above after invoking the base class outputData() function. The data stored should be enough to be able to restart a previous calculation and/or to combine the results of parallel runs.

Reimplemented in EGS_AdvancedApplication.

Definition at line 479 of file egs_application.cpp.

References a_objects_list, constructIOFileName(), current_case, data_out, egsStoreI64(), egsWarning, rndm, run, source, EGS_BaseSource::storeState(), and EGS_RandomGenerator::storeState().

Referenced by EGS_RunControl::finishBatch(), and EGS_AdvancedApplication::outputData().

int EGS_Application::readData ( )

virtual

Read intermediate results.

Opens the data file input_file.egsdat for reading, which must contain results of a previous simulation stored with outputData(), and sets data_in to point to the input stream. It then reads and sets the state of the application from a data file. Read quantities are last_case, the state of the run control object, the state of the source object and the state of the random number generator. Derived classes should re-implement to read their additional data after invoking the base class readData() function. This function is intended to be used for restarted calculations.

Reimplemented in EGS_AdvancedApplication.

Definition at line 517 of file egs_application.cpp.

References a_objects_list, constructIOFileName(), current_case, data_in, egsGetI64(), egsWarning, last_case, rndm, run, EGS_BaseSource::setState(), and source.

Referenced by EGS_AdvancedApplication::readData(), and EGS_RunControl::startSimulation().

const string& EGS_Application::getFinalOutputFile ( ) const

Returns the base name of the final output file(s)

For single job runs the final output file name is the same as the output file name obtained via getOutputFile(). For parallel runs they are different with this function returning xxx wheras getOutputFile() returns xxx_wX with xxx indicating the output file name and X the job number.

Definition at line 510 of file egs_application.h.

string EGS_Application::constructIOFileName	(	const char *	extension,
		bool	with_run_dir
	)		const

Constructs and returns the name of an input/output file.

Constructs the name of the file by joining the application directory, run directory (which may be empty, if this is the job combining a parallel run), if with_run_dir is true, the output file name, and the extension given as argument.

Definition at line 469 of file egs_application.cpp.

References app_dir, egsJoinPath(), output_file, and run_dir.

Referenced by outputData(), and readData().

virtual void EGS_Application::setAusgabCall	(	AusgabCall	call,
		bool	on_or_off
	)

virtual

Turns on or off a call to the user scoring function ausgab.

This function is re-implemented in EGS_AdvancedApplication to also modify the mortran array iausfl

Reimplemented in EGS_AdvancedApplication.

Definition at line 585 of file egs_application.h.

Referenced by addAusgabObject(), and EGS_AdvancedApplication::setAusgabCall().

int EGS_Application::getNparallel ( ) const

Returns the number of parallel jobs executing.

The number of parallel jobs is taken from the command line argument -P n (or –parallel n) but is reset to 1 if there was no job number specified (see getIparallel()) or the job number was greater than the number of parallel jobs.

Definition at line 596 of file egs_application.h.

Referenced by EGS_BeamSource::EGS_BeamSource(), EGS_RunControl::EGS_RunControl(), and EGS_RunControl::finishSimulation().

int EGS_Application::getIparallel ( ) const

Returns the job number in a parallel run.

The job number is specified on the command line using -j n or –job n and requires that the number of parallel jobs was also specified using -P n.

Definition at line 606 of file egs_application.h.

Referenced by EGS_BeamSource::EGS_BeamSource(), and EGS_RunControl::finishSimulation().

int EGS_Application::getFirstParallel ( ) const

Returns the first job number in a parallel run.

The first job number is specified on the command line using -f n or –first-job n and requires that the number of parallel jobs was also specified using -P n.

Definition at line 616 of file egs_application.h.

Referenced by EGS_RunControl::finishSimulation().

int EGS_Application::howfar	(	int	ireg,
		const EGS_Vector &	x,
		const EGS_Vector &	u,
		EGS_Float &	t,
		int *	newmed
	)

Calculates distance to a boundary along the current direction.

This function implements the EGSnrc howfar geometry specification

Definition at line 624 of file egs_application.h.

EGS_Float EGS_Application::hownear	(	int	ireg,
		const EGS_Vector &	x
	)

Calculates nearest distance to a boundary in any direction.

This function implements the EGSnrc hownear geometry specification

Definition at line 643 of file egs_application.h.

bool EGS_Application::isRealRegion ( int ireg )

Returns true if ireg is a real region, false otherwise.

This method is needed because of the region indexing style used by some composite geometries which results in a larger number of regions than actual regions. This method can be used in such cases to check if a region exists.

Definition at line 659 of file egs_application.h.

void EGS_Application::getNumberRegions	(	const string &	str,
		vector< int > &	regs
	)

Gets numbers out of str and pushes them onto regs.

Finds integer numbers in str and pushes them onto the vector regs. For an input string containing a mixture of labels and region numbers, this extracts the region numbers.

Usually you will do something like:

string regionString;
vector<int> regionVector;
int err1 = input->getInput("cavity regions",regionString);
geom->getNumberRegions(regionString, regionVector);
geom->getLabelRegions(regionString, regionVector);

Definition at line 681 of file egs_application.h.

void EGS_Application::getLabelRegions	(	const string &	str,
		vector< int > &	regs
	)

Gets the regions for the labels in str and pushes onto regs.

This function is used after getNumberRegions. It looks for labels in str, finds the corresponding local region numbers, and pushes those region numbers onto the region number vector regs.

The regs vector is sorted by this function, and duplicates are removed!

Definition at line 693 of file egs_application.h.

EGS_Float EGS_Application::getMU ( )

Returns the value of the mu synchronization parameter.

The parameter, mu, is a random number on [0,1) associated with each primary history and is retrieved from source. It can be used to synchronize geometric parameters throughout a simulation. If mu is not available in source (i.e., the getMu function has not been reimplemented in source), then this returns -1.

Definition at line 705 of file egs_application.h.

int EGS_Application::userScoring	(	int	iarg,
		int	ir = `-1`
	)

User scoring function for accumulation of results and VRT implementation.

This function first calls the processEvent() method of the ausgab objects registered with the application and then proceeds to call ausgab().

Definition at line 111 of file egs_application.cpp.

Referenced by EGS_RadionuclideSource::getNextParticle().

virtual int EGS_Application::ausgab ( int )

virtual

User scoring function.

This function should be re-implemented in derived classes to perform the actual scoring of the quantities of interest.

Definition at line 722 of file egs_application.h.

virtual void EGS_Application::startNewParticle ( )

virtual

Start the transport of a new particle.

This function is called just before the transport of a new particle begins and should be re-implemented in derived classes. Its default re-implementation in EGS_AdvancedApplication is to set the medium index of the current particle region. It can be re-implemented in derived classes to set other quantities such as ecut, pcut, etc. in order to have such quantities varying on a region-by-region bases.

Reimplemented in EGS_AdvancedApplication.

Definition at line 736 of file egs_application.h.

virtual void EGS_Application::enterNewRegion ( )

virtual

Particle enters new region.

This function is intended for setting up more sophisticated transport schemes that vary on a region-by-region basis. In the mortran sources when there is a region change the macros $electron_region_change or $photon_region_change are executed. In their default implementation these macros set ecut or pcut to ecut_new or pcut_new, rhor to rhor_new, medium to medium_new, the region index to irnew and smaxir to smax_new. In this way, if the user wants to implement a region-by-region variation of the above quantites, the xxx_new variables must be set to their new values in howfar, if a region change will take place at the end of the step. For varying additional quantities, the user can replace the $electron_region_change and/or $photon_region_change macros with calls to a function, which calls enterNewRegion() and provide an implementation of enterNewRegion().

Definition at line 756 of file egs_application.h.

void EGS_Application::fillRandomArray	(	int	n,
		EGS_Float *	rns
	)

virtual

Fill an array with random numbers using the application's RNG.

This function is called from within the mortran sources to get a new set of n random numbers. Its default implementation uses the application random number generator to fill the array pointed to by rns with n random numbers.

Definition at line 1078 of file egs_application.cpp.

References EGS_RandomGenerator::fillArray(), and rndm.

EGS_EXPORT EGS_Application * EGS_Application::activeApplication ( )

static

Get the active application.

This static function returns a pointer to the currently active application, which can be changed via a call to setActiveApplication(). Its primary use is to obtain the pointer to the active EGS_Application instance in the C-style functions (howfar, hownear, ausgab, etc) needed for the mortran subroutines in order to call the corresponding EGS_Application method. In most cases there will be a single EGSnrc application and the pointer to it will be set-up automatically when constructing the only EGS_Application class. However, in more advanced application the user may want to have several EGS_Application classes (e.g. the particle source itself may be derived from EGS_Application). In such cases, the setActiveApplication() function must be called by each EGS_Application instance before transporting particles.

Definition at line 103 of file egs_application.cpp.

Referenced by EGS_BaseSpectrum::createSpectrum(), EGS_AtomicRelaxations::EGS_AtomicRelaxations(), EGS_BeamSource::EGS_BeamSource(), EGS_RadionuclideBetaSpectrum::EGS_RadionuclideBetaSpectrum(), EGS_RadionuclideSource::EGS_RadionuclideSource(), and EGS_RadionuclideSpectrum::EGS_RadionuclideSpectrum().

EGS_EXPORT void EGS_Application::setActiveApplication ( EGS_Application * a )

static

Set the active EGS_Application class.

This function can be called from derived EGS_Application classes before transporting particles with a pointer to itself in situations where there is more than one instance of EGS_Application-derived classes

See Also: activeApplication().

Definition at line 107 of file egs_application.cpp.

EGS_I64 EGS_Application::randomNumbersUsed ( ) const

virtual

Returns the number of random numbers used.

The default implementation is to simply return the numbers used reported by the random number generator. Can be re-implemented in derived classes for more complex situations with correlated runs, etc.

Reimplemented in EGS_AdvancedApplication.

Definition at line 674 of file egs_application.cpp.

References EGS_RandomGenerator::numbersUsed(), and rndm.

Referenced by EGS_RunControl::finishSimulation(), and EGS_AdvancedApplication::randomNumbersUsed().

virtual void EGS_Application::getElectronSteps	(	double &	ch_steps,
		double &	all_steps
	)		const

virtual

Get the number of electron steps taken.

The number of all steps taken (single scattering or condensed history) is assigned to all_steps, the number of condensed history steps to ch_steps. Double precision numbers are used here as this is how steps are counted in the mortran back-end.

Reimplemented in EGS_AdvancedApplication.

Definition at line 814 of file egs_application.h.

Referenced by EGS_RunControl::finishSimulation().

int EGS_Application::addState ( istream & data )

virtual

Add data from a parallel job.

This function is called from within the loop over parallel jobs in the combineResults() function and must add the data found in the stream data to the results accumulated so far by the application. The default implementation reads and adds data related to the particle source, the random number generator, the run control object and the number of statistically independent events simulated (i.e. the data saved in outputData()).

See Also: outputData(), readData(), resetCounter().

Reimplemented in EGS_AdvancedApplication.

Definition at line 565 of file egs_application.cpp.

References a_objects_list, EGS_BaseSource::addState(), current_case, egsGetI64(), last_case, rndm, run, and source.

Referenced by EGS_AdvancedApplication::addState(), and combineResults().

void EGS_Application::resetCounter ( )

virtual

Reset the application to a 'pristine' state.

This function is called from within combineResults() and must reset all variables and objects collecting information about the simulation. The default implementation sets current_case and last_case to zero and calls the resetCounter() functions of the run control object, the random number generator and the source.

Reimplemented in EGS_AdvancedApplication.

Definition at line 553 of file egs_application.cpp.

References a_objects_list, current_case, last_case, EGS_BaseSource::resetCounter(), rndm, run, and source.

Referenced by combineResults(), and EGS_AdvancedApplication::resetCounter().

virtual void EGS_Application::describeUserCode ( ) const

virtual

Describe the user code.

This virtual function should be re-implemented in derived classes to output some useful and descriptive information about the user code to go into the log file. The default implementation does nothing.

Definition at line 851 of file egs_application.h.

Referenced by EGS_AdvancedApplication::finishSimulation(), and initSimulation().

bool EGS_Application::getArgument	(	int &	argc,
		char **	argv,
		const char *	name1,
		const char *	name2,
		string &	arg
	)

static

Finds a command line argument.

This function checks the argc command line arguments pointed to by argv for existence of an argument name1 or name2. If the argument exists, it sets arg to the next command line argument and returns true. Otherwise it returns false.

See Also: checkEnvironmentVar()

Definition at line 455 of file egs_application.cpp.

Referenced by EGS_Application(), and main().

void EGS_Application::checkEnvironmentVar	(	int &	argc,
		char **	argv,
		const char *	env,
		const char *	n1,
		const char *	n2,
		string &	var
	)

static

Finds a command line argument.

This function is similar to getArgument(), but if the arguments n1 and n2 are not given, it sets var from the environment variable env (if it is defined).

Definition at line 141 of file egs_application.cpp.

References egsFatal.

Referenced by EGS_Application(), and main().

int EGS_Application::initGeometry ( )

protectedvirtual

Initialize the simulation geometry.

The default implementation of this function initializes the simulation geometry from the input provided in an input file and available in the EGS_Application input object data member. Returns zero if the geometry initialization is successful, -1 if there is no input or 1 if the geometry construction failed. The user may re-implement this function to provide their own geometry initialization (e.g. a fixed geometry constructed directly instead of using an input file). This function is called from within the default implementation of the initSimulation() function.

Definition at line 681 of file egs_application.cpp.

References app_index, EGS_BaseGeometry::createGeometry(), geometry, input, EGS_BaseGeometry::ref(), and EGS_BaseGeometry::setActiveGeometryList().

Referenced by initSimulation().

int EGS_Application::initSource ( )

protectedvirtual

Initialize the particle source.

The default implementation of this function initializes the particle source from the input provided in an input file and available in the EGS_Application input object data member. Returns zero if the source initialization is successful, -1 if there is no input or 1 if the source construction failed. The user may re-implement this function to provide their own particle source initialization (e.g. a fixed source constructed directly instead of using an input file). This function is called from within the default implementation of the initSimulation() function.

Definition at line 696 of file egs_application.cpp.

References EGS_BaseSource::createSource(), input, EGS_Object::ref(), and source.

Referenced by initSimulation().

virtual int EGS_Application::initCrossSections ( )

protectedvirtual

Initialize the EGSnrc cross sections and cross section/transport options.

This function is re-implemented in the EGS_AdvancedApplication class, from which EGSnrc applications using the mortran EGSnrc physics subroutines should be derived. The default implementation is to set transport parameter and cross section options from input between :start MC Transport parameter: and :stop MC Transport parameter: in the input file, to add the media names found in the geometry to the EGSnrc back-end and to call the egsHatch() function to get the cross section data. This function is called from within the default implementation of the initSimulation() function.

Reimplemented in EGS_AdvancedApplication.

Definition at line 936 of file egs_application.h.

Referenced by initSimulation().

virtual int EGS_Application::initScoring ( )

protectedvirtual

Initialize the scoring of quantities of interest.

This function is called from within the default implementation of the initSimulation() function and must be re-implemented by the user to do all initializations related to the scoring of quantities of interest.

Definition at line 947 of file egs_application.h.

Referenced by initSimulation().

int EGS_Application::initRunControl ( )

protectedvirtual

Construct the run control object.

This function is called from within the default implementation of the initSimulation() function and is expected to construct and initialize a run control object. A run control object provides quantities such as the number of particles to run, how many batches, how many histories in the next chunk for parallel runs, etc., that are needed in the runSimulation() method. The default implementation looks for input between :start run control: and :stop run control: in the input file and contructs the run control object from it. Two default run control objects can be used:

simple: no parallel execution, etc.
parallel execution control using a job control file in the user code directory (which must therefore be on a NFS).

Definition at line 709 of file egs_application.cpp.

References run, simple_run, and uniform_run.

Referenced by initSimulation().

int EGS_Application::initRNG ( )

protectedvirtual

Initialize the random number generator.

The default implementation of this function looks for the input section defined by :start rng definition: and :stop rng definition: in the input file and constucts a random generator of the given type using the initial seeds specified. If no such input is found, the default EGSnrc random number generator is used (currently ranmar). This function is called from within the default implementation of the initSimulation() function.

Definition at line 728 of file egs_application.cpp.

References EGS_RandomGenerator::createRNG(), EGS_RandomGenerator::defaultRNG(), egsWarning, i_parallel, input, n_parallel, and rndm.

Referenced by initSimulation().

virtual int EGS_Application::initEGSnrcBackEnd ( )

protectedvirtual

Initialize the EGSnrc backend.

This function is re-implemented in the EGS_AdvancedApplication class, from which EGSnrc applications using the mortran EGSnrc physics subroutines should be derived, to call the egs_set_defaults and egs_init1 mortran subroutines. egs_set_defaults sets default values for all variables needed in the simulation. egs_init1 opens the pegs file and various other data files, opens the input file and creates the working directory. This function is called from within the default implementation of the initSimulation() function.

Reimplemented in EGS_AdvancedApplication.

Definition at line 995 of file egs_application.h.

Referenced by initSimulation().

void EGS_Application::initAusgabObjects ( )

protected

Initialize ausgab objects.

This function scans the input file for user input delimeted by :start ausgab object definition: and :stop ausgab object definition: and creates ausgab objects as requested by the user.

Definition at line 1029 of file egs_application.cpp.

References addAusgabObject(), EGS_AusgabObject::createAusgabObjects(), EGS_AusgabObject::getObject(), input, and EGS_AusgabObject::nObjects().

Referenced by initSimulation().

int EGS_Application::startNewShower ( )

protectedvirtual

Called just before the shower() function.

This function is called just before the shower() function from within the default implementation of the simulateSingleShower() function. If the return value is not zero, shower() is not called and this value is used as a return value of simulateSingleShower()

Examples:: tutor7pp.cpp.

Definition at line 952 of file egs_application.cpp.

References a_objects_list, current_case, and last_case.

Referenced by simulateSingleShower().

virtual int EGS_Application::finishShower ( )

protectedvirtual

Called just after the shower() function.

This function is called just after the shower() function from within the default implementation of the simulateSingleShower() function and its return value is returned as the return value of simulateSingleShower()

Definition at line 1028 of file egs_application.h.

Referenced by simulateSingleShower().

virtual int EGS_Application::shower ( )

protectedvirtual

Simulate a single shower.

This function is called from within the simulateSingleShower() function and should transport one particle with parameters stored in the p protected data member of EGS_Application. The default implementation does nothing. This function is reimplemented in EGS_AdvancedApplication to call the mortran EGSnrc shower subroutine.

Reimplemented in EGS_AdvancedApplication.

Definition at line 1041 of file egs_application.h.

Referenced by simulateSingleShower().