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

#include <egs_base_source.h>

Inheritance diagram for EGS_BaseSource:

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_Object *	createObject (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_BaseSource *	createSource (EGS_Input *)
	Create sources from the information pointed to by input. More...

static EGS_BaseSource *	getSource (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_ObjectFactory *	factory
	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

getEmax(): returns the maximum energy of the source
getFluence(): returns the fluence the source has emitted so far
getSourceDescription(): returns a string describing the source
storeState(), setState(), resetCounter(), addState(): these are functions needed for restarting calculations or combining the results of parallel runs

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().