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

A phase space scoring object: header. More...

#include <egs_phsp_scoring.h>

Inheritance diagram for EGS_PhspScoring:
EGS_AusgabObject EGS_Object

Classes

struct  egs_phsp_write_struct
 
struct  Particle
 

Public Member Functions

 EGS_PhspScoring (const string &Name="", EGS_ObjectFactory *f=0)
 
int processEvent (EGS_Application::AusgabCall iarg)
 
int processEvent (EGS_Application::AusgabCall iarg, int ir)
 
bool needsCall (EGS_Application::AusgabCall iarg) const
 
void setCurrentCase (EGS_I64 ncase)
 
void setGeom (EGS_BaseGeometry *phspgeom)
 
void setEntryExitReg (const vector< int > from_reg, const vector< int > to_reg)
 
void setOType (const int phspouttype)
 
void setOutDir (const string outdir)
 
void setParticleType (const int ptype)
 
void setScoreDir (const int sdir)
 
void setMuScore (const int imuscore)
 
void setScoreMC (const int iscoremc)
 
void setXYZconst (bool xyzisconst[3], float xyzconst[3])
 
void storeParticle (EGS_I64 ncase)
 
int flushBuffer () const
 
void openPhspFile () const
 
void setApplication (EGS_Application *App)
 
void reportResults ()
 
bool storeState (ostream &data) const
 
bool setState (istream &data)
 
bool addState (istream &data)
 
- Public Member Functions inherited from EGS_AusgabObject
 EGS_AusgabObject (const string &Name="", EGS_ObjectFactory *f=0)
 Construct an ausgab object named Name.
 
 EGS_AusgabObject (EGS_Input *input, EGS_ObjectFactory *f=0)
 Construct an ausgab object from the input pointed to by inp. More...
 
const char * getObjectDescription () const
 Get a short description of this ausgab object. More...
 
virtual void resetCounter ()
 Reset the ausgab object 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 Protected Member Functions

static unsigned int bclr ()
 
static unsigned int bsqe ()
 
static unsigned int bsqp ()
 
static unsigned int bsmc ()
 

Protected Attributes

bool score_mc
 
int iaea_id
 
int latch_ind
 
int mu_ind
 
int iaea_n_extra_float
 
int iaea_n_extra_long
 
int iaea_i_latch
 
int iaea_i_mu
 
int iaea_q_type [3]
 
bool xyz_is_const [3]
 
float xyzscore [3]
 
int len
 
char * phsp_fname_char
 
bool score_mu
 
float pmu
 
Particlep_stack
 
int phsp_index
 
int store_max
 
fstream phsp_file
 
EGS_I64 count
 
EGS_I64 countg
 
float emin
 
float emax
 
bool first_flush
 
bool is_restart
 
EGS_I64 countprev
 
EGS_I64 last_case
 
EGS_I64 current_case
 
int oformat
 
int ocharge
 
string phsp_fname
 
string phspoutdir
 
int score_type
 
EGS_BaseGeometryphsp_geom
 
int scoredir
 
bool phsp_before
 
bool phsp_after
 
vector< int > fromreg
 
vector< int > toreg
 
vector< vector< int > > from_to
 
int ir_before
 
int ir_after
 
- Protected Attributes inherited from EGS_AusgabObject
string description
 A short ausgab object description. More...
 
EGS_Applicationapp
 The application this object belongs to.
 
- 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.
 

Additional Inherited Members

- Static Public Member Functions inherited from EGS_AusgabObject
static void createAusgabObjects (EGS_Input *)
 Create ausgab objects from the information pointed to by input. More...
 
static EGS_AusgabObjectgetAusgabObject (const string &Name)
 Get a pointer to the ausgab object named Name. More...
 
static void addKnownAusgabObject (EGS_AusgabObject *o)
 Add a known ausgab object to the ausgab object factory. More...
 
static void addKnownTypeId (const char *name)
 Add a known ausgab object typeid to the ausgab object factory. More...
 
static int nObjects ()
 Returns the number of ausgab objects in the internal list.
 
static EGS_AusgabObjectgetObject (int j)
 Returns the j'th ausgab object in the internal list.
 
- 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...
 

Detailed Description

A phase space scoring object: header.

This ausgab object generates phase space data for particles using one of two methods:

  1. Scores particles exiting and/or entering all surfaces of a predefined geometry. The geometry can be a component of the simulation geometry or coincident with a surface in the simulation geometry.
  2. Scores particles on exiting one user-specified region and entering another. The user can specify multiple exit/entry region pairs.

Phase space data can be scored in one of 2 possible formats:

EGSnrc format: E,x,y,u,v,wt,latch IAEA format: iq,E,[x],[y],[z],u,v,wt,latch,[mu]

Note that in IAEA format, the user has the option of specifying a fixed x, y, and/or z coordinate of the scoring plane/line/point, in which case the fixed coordinates shall not be scored for each particle but will be specified in the header (.IAEAheader) file. Also, in this format, the user has the option of scoring the synchronization parameter, mu, passed from the source.

Can be used in any C++ user code by entering the proper input block in the ausgab object definition block.

:start ausgab object definition:
      :start ausgab object:
          library                  = egs_phsp_scoring
          name                     = some_name
          output format            = EGSnrc or IAEA
          constant X               = X value (cm) at which all particles are scored (IAEA format only)
          constant Y               = Y value (cm) at which all particles are scored (IAEA format only)
          constant Z               = Z value (cm) at which all particles are scored (IAEA format only)
          particle type            = all, photons, or charged
          score mu                 = yes or no [default] (IAEA format only)
          score multiple crossers  = no (default) or yes (EGSnrc format only)
          output directory         = name of output directory

     and one of two methods of scoring particles:

     Method 1: score particles on entry to/exit from a predefined geometry
          phase space geometry     = name of previously defined geometry
          score particles on       = entry, exit, entry and exit [default]

     Method 2: score particles on exiting one region and entering another
          from regions             = list of exit region numbers
          to regions               = list of entry region numbers

      :stop ausgab object:
:stop ausgab object definition:

Phase space data is output to the file some_name.egsphsp1 (EGSnrc format) or some_name.1.IAEAphsp and some_name.1.IAEAheader (IAEA format) Note that if the user specifies constant X/Y/Z, then particles are all assumed to be scored at the same X/Y/Z with this(ese) values output to .IAEAheader instead of being output for each particle to the .IAEAphsp file.

Particles of the type indicated by the "particle type" input are scored. If this input is omitted, then all particles are scored.

In IAEA-format phase space files, the user can opt to score the synchronization parameter, mu. This option will automatically be turned off if the parameter is not available from the source. Currently, this parameter can only be passed from egs_beam_source (only if the accelerator includes synchronized CMs), iaea_phsp_source (if scored using a BEAMnrc simulation with synchronized CMs or scored using this ausgab object with mu scoring turned on) and egs_dynamic_source (always available).

The default is to not score multiple crossers (and their descendents) and, indeed, this is, by definition, the protocol for IAEA format phase space files. However, if the user is scoring data in EGSnrc format, then they have the option to include multiple crossers and their descendents. Note that the marker for a particle having been scored is to set bit 31 of the particle's latch high. Thus, the marker is associated with the particle, not the scoring object. This has implications if the user wishes to have multiple phase space scoring objects in one run: a particle scored by one phase space scoring object will not subsequently be scored by another, unless the user has set "score multiple crossers = yes" in the latter.

If "output directory" is omitted or left blank then the output directory defaults to the application directory (i.e. $EGS_HOME/appname).

When using a phase space scoring geometry, particles can be scored on entering the phase space geometry, exiting the geometry, or both (the default). Be aware of how the "inside" and "outside" of the geometry are defined when using this option.

When using pairs of exit/entry regions, the number of regions specified by the "to regions" input must equal that of the "from regions" input. If the exit region number is equal to the entry region number, then the pair is deleted prior to the run.

A note on parallel runs: If a phase space file is being written during a parallel run, then each job, i, outputs its phase space data to some_name_wi.[egsphsp1][.1.IAEAheader/phsp]. Thus, the naming scheme is the same as that for other output files from a parallel run. These phase space files are not added automatically when the results of a parallel run are combined. The user must either use the addphsp tool or program their own concatenation routine.

Example: The following example input illustrates the two phase space scoring methods. In both cases, phase space is scored in planes perpendicular to the axis of a water/air cylinder.

:start geometry definition:
      :start geometry:
          library = egs_planes
          type = EGS_Zplanes
          positions = 21.0
          name = scoreplane
      :stop geometry:

      :start geometry:
          library = egs_planes
          type = EGS_Zplanes
          positions = 0.0 10.0 21.0
          name = cutplane
      :stop geometry:

      :start geometry:
          library = egs_cylinders
          type = EGS_ZCylinders
          name = cylinders
          radii = 1.0 5.0 15.0
          midpoint = 0
          :start media input:
             media = H2O521ICRU AIR521ICRU
             set medium = 0 0
             set medium = 1 1
             set medium = 2 0
          :stop media input:
      :stop geometry:

      :start geometry:
           name = maingeom
           library = egs_cdgeometry
           base geometry = cutplane
           set geometry = 0 cylinders
           set geometry = 1 cylinders
      :stop geometry:

      simulation geometry = maingeom
  :stop geometry definition:

  :start ausgab object definition:
      :start ausgab object:
        library = egs_phsp_scoring
        name = test
        from regions = 0 2
        to regions = 3 5
        output format = IAEA
        constant Z = 10.0
        particle type = all
        score mu = no
      :stop ausgab object:

      :start ausgab object:
        library = egs_phsp_scoring
        name = test2
        phase space geometry = scoreplane
        output format = EGSnrc
        particle type = all
        score particles on = entry
        score multiple crossers = yes
      :stop ausgab object:
:stop ausgab object definition:

The first ausgab object, "test," uses scoring method 2 (exit/entry region pairs) to score phase space data, in IAEA format, for all particles crossing a plane perpendicular to the cylinder and at the mid-point of the cylinder (Z=10 cm). Data will be scored for particles within the innermost cylinder (exit/entry regions 0/3) and within the outermost annulus (exit/entry regions 2/5). Note that the constant Z value of the scoring plane is input, so data will be in 2D format. Also note that IAEA format, by convention, does not score multiple crossers. The output will be to test.1.IAEAheader (header file) and test.1.IAEAphsp (phase space data).

The second ausgab object, "test2," uses scoring method 1 (predefined scoring geometry) to score phase space data, in EGSnrc format, for all particles crossing a single plane coincident with the bottom (Z=21 cm) of the cylinder. The scoring plane is given by the geometry, "scoreplane," which defines a single plane perpendicular to Z at Z=21 cm. Recall that a single plane defines a single region on the +ve normal side of the plane. In this example, a particle is considered "outside" scoreplane if Z < 21.0 and inside if Z > 21.0 and, thus, scoring particles on "entry" will collect data for all particles leaving out the bottom of the cylinder. In this case, however, the specification of scoring direction is moot, since particles leaving the bottom of the cylinder are effectively leaving the simulation geometry. Note that the option to score multiple crossers has been turned on. Otherwise, particles previously scored in "test" would not be scored by "test2." Phase space data will be output to test2.egsphsp1.

Definition at line 250 of file egs_phsp_scoring.h.


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