EGSnrc C++ class library  Report PIRS-898 (2021)
Iwan Kawrakow, Ernesto Mainegra-Hing, Frederic Tessier, Reid Townson and Blake Walters
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
EGS_BaseSource Class Referenceabstract

Base source class. All particle sources must be derived from this class. More...

#include <egs_base_source.h>

Inheritance diagram for EGS_BaseSource:
EGS_Object EGS_AngularSpreadSource EGS_BaseSimpleSource EGS_BeamSource EGS_DynamicSource EGS_PhspSource EGS_RadionuclideSource EGS_SourceCollection EGS_TransformedSource IAEA_PhspSource

Public Member Functions

 EGS_BaseSource (const string &Name="", EGS_ObjectFactory *f=0)
 Construct a source named Name. More...
 
 EGS_BaseSource (EGS_Input *input, EGS_ObjectFactory *f=0)
 Construct a source from the input pointed to by inp. More...
 
const char * getSourceDescription () const
 Get a short description of this source. More...
 
virtual EGS_I64 getNextParticle (EGS_RandomGenerator *rndm, int &q, int &latch, EGS_Float &E, EGS_Float &wt, EGS_Vector &x, EGS_Vector &u)=0
 Sample the next source particle from the source probability distribution. More...
 
virtual void setSimulationChunk (EGS_I64 nstart, EGS_I64 nrun)
 Set the next simulation chunk to start at nstart and to consist of nrun particles. More...
 
virtual int getCharge () const
 Get the charge of the source. More...
 
virtual EGS_Float getEmax () const =0
 Return the maximum energy of this source. More...
 
virtual EGS_Float getFluence () const =0
 Return the fluence this source has emitted so far. More...
 
virtual EGS_Float getMu ()
 
virtual bool storeState (ostream &data_out) const
 Store the source state into the stream data_out. More...
 
virtual bool setState (istream &data_in)
 Set the source state based on data from the stream data_in. More...
 
virtual bool addState (istream &data_in)
 Add data from the stream data_in to the source state. More...
 
virtual void resetCounter ()
 Reset the source state. More...
 
- Public Member Functions inherited from EGS_Object
 EGS_Object (const string &Name="", EGS_ObjectFactory *f=0)
 Create an EGS_Object named Name belonging to the object factory f. More...
 
 EGS_Object (EGS_Input *inp, EGS_ObjectFactory *f=0)
 Create an EGS_Object from the information pointed to by inp that belongs to object factory f. More...
 
const string & getObjectName () const
 Get the object name.
 
void setObjectName (const string &Name)
 Set the object name to Name.
 
const string & getObjectType () const
 Get the object type.
 
virtual EGS_ObjectcreateObject (EGS_Input *inp)
 Create an object from the infromation pointed to by inp. More...
 
void setName (EGS_Input *inp)
 Set the name of the object from the information provided by inp. More...
 
int ref ()
 Increase the reference count to this object.
 
int deref ()
 Decrease the reference count to this object.
 
void setFactory (EGS_ObjectFactory *f)
 Set the factory to which the object belongs. More...
 

Static Public Member Functions

static EGS_BaseSourcecreateSource (EGS_Input *)
 Create sources from the information pointed to by input. More...
 
static EGS_BaseSourcegetSource (const string &Name)
 Get a pointer to the source named Name. More...
 
static void addKnownSource (EGS_BaseSource *o)
 Add a known source object to the source factory. More...
 
static void addKnownTypeId (const char *name)
 Add a known source object typeid to the source factory. More...
 
- Static Public Member Functions inherited from EGS_Object
static string getUniqueName (const EGS_Object *o=0)
 Create and return a unique object name. More...
 
static void deleteObject (EGS_Object *o)
 Delete an object. More...
 

Protected Attributes

string description
 A short source description. More...
 
- Protected Attributes inherited from EGS_Object
string name
 The object name.
 
string otype
 The object type.
 
int nref
 Number of references to the object.
 
EGS_ObjectFactoryfactory
 The factory this object belongs to.
 

Detailed Description

Base source class. All particle sources must be derived from this class.

Particle sources in the EGSnrc C++ class library are classes derived from the base source class and compiled into dynamic shared objects (a.k.a. DLLs) that get dynamically loaded at run time as specified by the sources property source definition (see Particle sources). The base source defines the interface to a source object. The main method is getNextParticle() which returns the parameter of a single particle distributed according to some probability distribution. Additional functions that must be implemented by derived classes are

Todo:
Add time dependence
Examples:
sources/egs_point_source/egs_point_source.cpp.

Definition at line 80 of file egs_base_source.h.

Constructor & Destructor Documentation

EGS_BaseSource::EGS_BaseSource ( const string &  Name = "",
EGS_ObjectFactory f = 0 
)

Construct a source named Name.

Definition at line 87 of file egs_base_source.h.

EGS_BaseSource::EGS_BaseSource ( EGS_Input input,
EGS_ObjectFactory f = 0 
)

Construct a source from the input pointed to by inp.

The property tree pointed to by inp must contain at least the following key-value pairs:

name = name of this source
library = source library

plus additional information as needed by the source being created.

Definition at line 98 of file egs_base_source.h.

Member Function Documentation

const char* EGS_BaseSource::getSourceDescription ( ) const

Get a short description of this source.

Derived source classes should set description to a short string describing the source type.

Definition at line 107 of file egs_base_source.h.

Referenced by EGS_Application::describeSimulation().

virtual EGS_I64 EGS_BaseSource::getNextParticle ( EGS_RandomGenerator rndm,
int &  q,
int &  latch,
EGS_Float &  E,
EGS_Float &  wt,
EGS_Vector x,
EGS_Vector u 
)
pure virtual

Sample the next source particle from the source probability distribution.

This is the main interface function of a particle source. It must be implemented in derived classes to sample a particle from the source probability distribution using the random number generator rndm and to set q to the particle charge, latch to the particle latch, E to the particle kinetic energy, wt to the particle statistical weight and x and u to the particle position and direction. The return value must be the number of statistically independent particles sampled so far. For simple sources this is typically equal to the number of particles sampled, but this may not be the case for more complicated sources (e.g. for a phase-space file source of a treatment head simulation the statistically independent particles are the electrons impinging on the bremsstrahlung target or vacuum exit window, and not individual particles in the phase-space file) or sources that implement some sort of systematic sampling of the beam area.

Implemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Referenced by EGS_RadionuclideSource::getNextParticle(), EGS_SimpleApplication::run(), and EGS_Application::simulateSingleShower().

virtual void EGS_BaseSource::setSimulationChunk ( EGS_I64  nstart,
EGS_I64  nrun 
)
virtual

Set the next simulation chunk to start at nstart and to consist of nrun particles.

This method is needed for parallel runs when using phase space files. It may also be re-implemented, if one wanted to use some sort of a systematic sampling of the phase space.

Definition at line 143 of file egs_base_source.h.

Referenced by EGS_Application::setSimulationChunk().

virtual int EGS_BaseSource::getCharge ( ) const
virtual

Get the charge of the source.

This virtual function must be re-implemented in derived classes that return the source particles' charge. Multi-particle sources will return a value of -99. This value corresponds to an unknown particle type in the fluence scoring AOs.

Reimplemented in EGS_BaseSimpleSource.

Definition at line 152 of file egs_base_source.h.

virtual EGS_Float EGS_BaseSource::getEmax ( ) const
pure virtual

Return the maximum energy of this source.

This pure virtual function must be implemented in derived classes to return the maximum energy of the source. This is needed to check if the cross section data from the PEGS file covers the energy range of the simulation and will be needed in future EGSnrc versions, where the cross section data initialization will be done at run time, to define the necessary energy range for the cross section data

Implemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Referenced by EGS_SimpleApplication::EGS_SimpleApplication().

virtual EGS_Float EGS_BaseSource::getFluence ( ) const
pure virtual

Return the fluence this source has emitted so far.

This pure virtual function must be implemented in derived classes to return the particle "fluence" emitted so far by the source. Every source can have their own definition of "fluence". The particle "fluence" will be typically used in EGSnrc C++ user codes for normalization purposes. Some of the sources provided with the EGSnrc C++ class library define this quantity as real fluence (i.e. particles per unit area), whereas others define it as the number of statistically independent particles delivered so far (e.g. the phase-space file source and the BEAM simulation source).

Implemented in EGS_RadionuclideSource.

Examples:
sources/egs_point_source/egs_point_source.cpp.
virtual bool EGS_BaseSource::storeState ( ostream &  data_out) const
virtual

Store the source state into the stream data_out.

Every source should reimplement this method to store the data needed to set the state of the source to its current state into the stream data_out. This is used for restarted calculations. Examples of data needed is the number of statistically independent particles delivered so far by the source. Should return true on success, false on failure.

See Also
setState(), addState(), resetCounter().

Reimplemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Definition at line 202 of file egs_base_source.h.

Referenced by EGS_Application::outputData(), and EGS_RadionuclideSource::storeState().

virtual bool EGS_BaseSource::setState ( istream &  data_in)
virtual

Set the source state based on data from the stream data_in.

Every source should reimplement this method to read from the stream data_in data previously stored using storeState() and to set its state according to this data. This is used for restarted calculations. Should return true on success, false on failure (e.g. I/O error).

See Also
addState(), storeState(), resetCounter()

Reimplemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Definition at line 216 of file egs_base_source.h.

Referenced by EGS_Application::readData(), and EGS_RadionuclideSource::setState().

virtual bool EGS_BaseSource::addState ( istream &  data_in)
virtual

Add data from the stream data_in to the source state.

This method is required for combining the results of parallel runs. It should therefore be re-implemented in derived classes to update its own state with the data read from the input stream data_in. For instance, if the total number of statistically independent particles delivered so far is the only data the source needs, then this number should be read from the stream data_in and added to the number of statistically independent particles delivered by this source.

See Also
storeState(), setState(), resetCounter().

Reimplemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Definition at line 232 of file egs_base_source.h.

Referenced by EGS_RadionuclideSource::addState(), and EGS_Application::addState().

virtual void EGS_BaseSource::resetCounter ( )
virtual

Reset the source state.

Derived sources should reimplement this method to reset all data describing their state to a "pristine" state (i.e. zero particles delivered so far). This is needed for combining the results of parallel runs where the generic implementation of EGS_Application::combineResults() uses this method to reset the source state and then uses the addState() function to add the source data from all other parallel jobs.

Reimplemented in EGS_BaseSimpleSource, and EGS_RadionuclideSource.

Definition at line 247 of file egs_base_source.h.

Referenced by EGS_RadionuclideSource::resetCounter(), and EGS_Application::resetCounter().

EGS_BaseSource * EGS_BaseSource::createSource ( EGS_Input i)
static

Create sources from the information pointed to by input.

This static function creates all sources specified by the information stored in an EGS_Input object and pointed to by inp. It looks for a composite property source definition in the input tree. If such property exists, it looks for sub-properties source and for each such property that contains a library and name key-value pairs, loads the DSO specified by the library key, resolves the address of the createSource function that must be provided by the DSO and calls this function passing the source property to it. If the source property contains a valid information sufficient to create a particle source of the given type, the createSource creates the source and returns a pointer to it. The process is continued until there are no further source properties in the source definition input. All sources created in this way are added to a global list list of particle sources and can be retrieved later by name using the getSource() static function. The return value of this function is

  • null, if there was no valid source input
  • A pointer to the last source created, if there was no simulation source key in source definition
  • A pointer to the source specified by name using the simulation source or null, if such source does not exist.

Definition at line 58 of file egs_base_source.cpp.

Referenced by EGS_DynamicSource::EGS_DynamicSource(), EGS_SimpleApplication::EGS_SimpleApplication(), EGS_SourceCollection::EGS_SourceCollection(), EGS_TransformedSource::EGS_TransformedSource(), and EGS_Application::initSource().

EGS_BaseSource * EGS_BaseSource::getSource ( const string &  Name)
static

Get a pointer to the source named Name.

A static list of sources created so far is maintained internally and this method can be used to get a source with a given name. Returns a pointer to the soure, if a source named Name exists, null otherwise.

Definition at line 65 of file egs_base_source.cpp.

References egsWarning, and EGS_Object::getObjectType().

Referenced by EGS_DynamicSource::EGS_DynamicSource(), EGS_RadionuclideSource::EGS_RadionuclideSource(), EGS_SourceCollection::EGS_SourceCollection(), and EGS_TransformedSource::EGS_TransformedSource().

void EGS_BaseSource::addKnownSource ( EGS_BaseSource o)
static

Add a known source object to the source factory.

This function adds the object o to the list of known sources maintained internally by the static source factory. That way, an application can define its own particle sources (in addition to the sources provided by egspp) and use them.

Definition at line 80 of file egs_base_source.cpp.

References egsInformation, and EGS_Object::getObjectType().

void EGS_BaseSource::addKnownTypeId ( const char *  name)
static

Add a known source object typeid to the source factory.

For whatever reason dynamic_cast to EGS_BaseSource* from EGS_Object* fails when an application is made into a shared library and dynamically loads a source DSO. I'm therefore adding this method so that source classes can add their typeid to allow for an additional check in such cases.

Definition at line 86 of file egs_base_source.cpp.

Referenced by createSourceTemplate().

Member Data Documentation

string EGS_BaseSource::description
protected

A short source description.

Derived source classes should set this data member to a short descriptive string.

Examples:
sources/egs_point_source/egs_point_source.cpp.

Definition at line 313 of file egs_base_source.h.

Referenced by EGS_BeamSource::EGS_BeamSource(), EGS_PhspSource::EGS_PhspSource(), IAEA_PhspSource::IAEA_PhspSource(), and EGS_PointSource::setUp().


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