Utility user actions

These are a miscellaneous set of user actions that add some functionality. As for any user action, filters can be assigned to them to select for which type of tracks they will be activated and in some cases classifiers may be used to classify the output tables.

Counting the number of tracks and events

This utility prints a line every N events with the event number, the number of tracks in this event and the accumulated number of tracks in all events:

%%% EVENT 0 NTRACKS 4 TOTAL NTRACKS 4
%%% EVENT 1000 NTRACKS 6 TOTAL NTRACKS 4663
%%% EVENT 2000 NTRACKS 4 TOTAL NTRACKS 9440

Its main use is to inform the user of the progress of the job in interactive running. To activate this utility use the command:

/gamos/userAction GmCountTracksUA

The user can control the interval of events as well as the first event to start printing with the parameters:

/gamos/setParam USER_ACTION_NAME:EachNEvent NEV

/gamos/setParam USER_ACTION_NAME:FirstEvent NEV

These parameters have a default value of 10 and 0 respectively.

This utility distinguishes for the ionisation and bremsstrahlung processes those cases when a secondary particle is emitted and those when the step is limited to assure a correct energy loss and multiple scattering but no secondary particle is emitted (it adds _NoSeco at the end of the process name).

Counting the processes

To activate this utility use the command:

/gamos/userAction GmCountProcessesUA

It prints four tables:

  • At the beginning of run all the active processes for each particle type:

    PROC_LIST e+ : Transportation
    PROC_LIST e+ : annihil
    PROC_LIST e+ : eBrem
    PROC_LIST e+ : eBrem_NoSeco
    PROC_LIST e+ : eIoni
    PROC_LIST e+ : eIoni_NoSeco
    PROC_LIST e+ : msc
    PROC_LIST e- : Transportation
    PROC_LIST e- : eBrem
    PROC_LIST e- : eBrem_NoSeco
    PROC_LIST e- : eIoni
    PROC_LIST e- : eIoni_NoSeco
    PROC_LIST e- : msc
    PROC_LIST gamma : Rayl
    PROC_LIST gamma : Transportation
    PROC_LIST gamma : compt
    PROC_LIST gamma : conv
    PROC_LIST gamma : phot
    

    This list may not be printed unless you set the parameter. /gamos/setParam USER_ACTION_NAME:PrintProcList 1

  • At the end of run how many times a process determined the step for each particle type:

    PROC_COUNT e+ : Transportation = 1870
    PROC_COUNT e+ : annihil = 728
    PROC_COUNT e+ : eBrem = 86
    PROC_COUNT e+ : eBrem_NoSeco = 5
    PROC_COUNT e+ : eIoni = 861
    PROC_COUNT e+ : eIoni_NoSeco = 864
    PROC_COUNT e+ : msc = 5531
    PROC_COUNT e+ : ALL = 9945
    PROC_COUNT e- : Transportation = 1977
    PROC_COUNT e- : eBrem = 142
    PROC_COUNT e- : eBrem_NoSeco = 10
    PROC_COUNT e- : eIoni = 1736
    PROC_COUNT e- : eIoni_NoSeco = 9812
    PROC_COUNT e- : msc = 25744
    PROC_COUNT e- : ALL = 39421
    PROC_COUNT gamma : Rayl = 4
    PROC_COUNT gamma : Transportation = 4657
    PROC_COUNT gamma : compt = 53
    PROC_COUNT gamma : phot = 125
    PROC_COUNT gamma : ALL = 4839
    
  • At the end of run how many times a process was the creator of a particle for each particle type:

    PROC_CREATOR_COUNT e+ : Primary = 1000
    PROC_CREATOR_COUNT e- : Primary = 1000
    PROC_CREATOR_COUNT e- : compt = 53
    PROC_CREATOR_COUNT e- : eIoni = 2597
    PROC_CREATOR_COUNT e- : phot = 125
    PROC_CREATOR_COUNT gamma : annihil = 1456
    PROC_CREATOR_COUNT gamma : eBrem = 228
    

You may choose to print the creator model name together with the creator process name (separated by a “_”), by setting the parameter

/gamos/setParam USER_ACTION_NAME:PrintCreatorModel TRUE

  • At the end of run how many particles of each type were created:

    PART_LIST: e+ = 1000
    PART_LIST: e- = 1485
    PART_LIST: gamma = 2285
    

The eIoni_NoSeco and eBrem_NoSeco refer to the cases when ionisation or bremsstrahlung processes limit the step but no secondary particle is produced. The reason for this limitation is to guarantee that the step are not too big so that physics precision may be spoiled. You may have a look for example at http://fismed.ciemat.es/GAMOS/RToptim/ParameterHelp.html for a description of the Geant4 electromagnetic physics parameters.

This user action may be combined with filters and classifiers.

Shower shape studies

GAMOS offers an utility to help in doing shower shape studies. To use is it is enough to active the user action

/gamos/userAction GmShowerShapeUA

Each time a new track step satisfies the conditions of the filters associated to this action a new shower is started, and the user action accumulates all the energy deposits of all the children created from this track step. This means that each track step that passes the filter initiates a new shower, unless the track is a children of a track which has already initiated a shower. But you should not forget the logic of the user actions and filters: the user action GmShowerShapeUA will only be invoked for the steps that pass the associated filters; i.e. if one of the children track steps does not pass the filter, it will not be included in the shower. If this behaviour does not provide you with the expected results, you may consider using the filter GmAncestorsFilter (see section of Filters).

As we just mentioned each step of a track may initiate a new shower, but if you want to include all the steps of the same track (and their children) in a unique shower, you have to set the parameter:

/gamos/setParam USER_ACTION_NAME:IncludeOtherStepsOfFirstTrack TRUE

At the end of each event, the showers are analysed and several variables are calculated for each of them:

  • Total energy: sum of the deposited energies of all steps belonging to the shower
  • Shower direction: two options are provided to define the shower direction. The first one (default) is to take the direction of the particle that initiated the shower; this is the direction of th PreStepPoint of the first track step. The second option is to calculate a shower ‘average’ direction, formed joining the point where the track is initiated and an ‘average’ shower point. This ‘average’ point is calculating as the sum of all the shower step points weighted with the energy deposited at each step. To use this second definition instead of the first one, you have to set the parameter: /gamos/setParam USER_ACTION_NAME:ShowerDirection Shower
  • Step point longitudinal length: distance from an step position to the initial shower point along the shower direction
  • Step point transversal length: minimum distance from an step position to the line built from the initial shower point and the shower direction

From the above two definitions several shower variables are calculated:

  • Maximum longitudinal length: maximum of the step point longitudinal lengths
  • Maximum transversal length: maximum of the step point transversal lengths
  • Average longitudinal length: average of the step point longitudinal lengths, weighted with the energy deposits
  • Average transversal length: average of the step point transversal lengths, weighted with the energy deposits

The deposition of energy in the step is actually done in small quantities approximately uniformly distributed along the step. As it would be too CPU time consuming to simulate each of these interactions, we just consider a deposition point, making a linear interpolation between the two steps edges; in other words, we use as energy deposit point the average of the PreStepPoint and PostStepPoint. If you want to use instead the PreStepPoint or PostStepPoint, you have to use the parameter:

/gamos/setParam USER_ACTION_NAME:StepPointToUse TYPE

where TYPE can be Pre, Post or Linear (the default choice). Other algorithms may be implemented in the future at user request.

With the above-mentioned histograms variables a file named shower.root / csv is written with the following histograms (the second name is the type of histogram for histogram limits setting (see section on Using a common histogram class):

  • Total energy (” Total Energy”)(“E”)
  • Maximum longitudinal length (” Maximum R transv”)(“Pos”)
  • Maximum transversal length (” Maximum R transv”)(“Pos”)
  • Average longitudinal length (” Maximum R transv”)(“Pos”)
  • Average transversal length (” Maximum R transv”)(“Pos”)
  • Shower direction theta angle (” Shower direction theta”)(“Angle”)
  • Shower direction phi angle (” Shower direction phi”)(“Angle”)

The sum of energy deposits inside a certain transversal distance (a radius) is calculated and an histogram is filled. By default the list of radii is: 0.1, 0.3, 0.5, 1., 5. mm and infinite (DBL_MAX). You may change this list with the parameter:

/gamos/setParam USER_ACTION_NAME:Radii RADIUS_1 RADIUS_2 …

With these variables two sets of histograms are filled:

  • Energy inside radius (“Energy inside radius”)(“E”)
  • Energy inside radius divided by total shower energy (” Relative energy inside radius”)(“E”)

Killing all tracks

The action

/gamos/userAction GmKillAtStackingActionUA

serves to kill all particles at the stacking action G4ClassificationOfNewTrack method, i.e. before they start being tracked. You may use it in combination with one or several filters to kill only the particles that are accepted by them. For example,

/gamos/userAction GmKillAtStackingActionUA GmElectronFilter

will only kill electrons.

If you want to apply the killing at stepping action, probably because you want to apply some step filter, you can use the user action:

/gamos/userAction GmKillAtSteppingActionUA

It is also possible to kill at the beginning of tracking action (when the track starts). The difference with respect to killing at stacking action is that at least a first step is done for each track, and you can get some information of each track. To do this, you can use the user actions:

/gamos/userAction GmKillAtTrackingActionUA

Table of tracks and steps

You may get a table of the number of tracks and steps by instantiating the user action

/gamos/userAction GmCountTracksAndStepsUA

It will produce a table with the number of tracks and steps in the whole run. You may get more details by using it with filters and classifiers. For example the command:

/gamos/userAction GmCountTracksAndStepsUA GmClassifierByParticle

will produce a table similar to this one

%%% COUNT_TRACKS_AND_STEPS: GmClassifierByParticle
%%% COUNT_TRACKS: gamma = 100
%%% COUNT_TRACKS: e- = 8
%%% COUNT_TRACKS: e+ = 1
%%% COUNT_TRACKS: ALL = 109
%%% COUNT_NSTEPS: gamma = 399
%%% COUNT_NSTEPS: e- = 29
%%% COUNT_NSTEPS: e+ = 4
%%% COUNT_STEPS: ALL = 432

Material budget studies

The action

/gamos/userAction GmMaterialBudgetUA

serves to make an study of the material budget of your geometry. We compute the material budget of a geometry along a line by integrating the radiation length of each volume traversed multiplied by the length of the line segment in that volume. This user action may be useful for checking your geometry.

The usual way to use this user action is to send parallel geantinos (the Geant4 particle that does not interact, only traverses the geometry) starting in a plane perpendicular to the geantino direction and computing the material budget for each of them

The user action GmMaterialBudgetUA computes the material budget along each track and writes in the file matbud.root / csv the following histograms:

  • 1D Profile histogram of material budget in position X (” Position X”)
  • 1D Profile histogram of material budget in position Y (” Position Y”)
  • 1D Profile histogram of material budget in position Z (” Position Z”)
  • 2D Profile histogram of material budget in positions X and Y (” Position XY”)
  • 2D Profile histogram of material budget in positions X and Z(” Position XZ”)
  • 2D Profile histogram of material budget in positions Y and Z(” Position YZ”)

Detailed report of where CPU time is spent

You may get a detailed report of where the CPU time is spent by instantiating the user action

/gamos/userAction GmTimeStudyUA CLASSIFIER_1 CLASSIFIER_2 …

By selecting different classifiers you can get a report of the time spent by each particle, in each logical volume, in each energy bin, etc. (see section on Classifiers).

The table will have a format similar to the following one:

%%%%% TIMING RESULTS for timer GmTimeStudyUA_ClassifierByParticleAndKinE
GmTimeStudyUA_GmClassifierByParticle_GmClassifierByKineticEnergy
e+/0.0001-0.001:   User=0  Real=0  Sys=0.01
e+/0.001-0.01:   User=0.07  Real=0.16  Sys=0
e+/0.01-0.1:   User=1.3  Real=1.48  Sys=0.04
e+/0.1-1:   User=74.66  Real=78.74  Sys=1.17
e+/1e-05-0.0001:   User=0  Real=0  Sys=0
e+/1e-06-1e-05:   User=0  Real=0  Sys=0
e-/0.0001-0.001:   User=0.53  Real=0.37  Sys=0.02
e-/0.001-0.01:   User=12.42  Real=13.58  Sys=0.29
e-/0.01-0.1:   User=5.98  Real=6.42  Sys=0.16
e-/0.1-1:   User=7.78  Real=8.8  Sys=0.22
e-/1-10:   User=0  Real=0  Sys=0
e-/1e-05-0.0001:   User=0  Real=0  Sys=0
e-/1e-06-1e-05:   User=0  Real=0  Sys=0
gamma/0.001-0.01:   User=1.29  Real=1.49  Sys=0.02
gamma/0.01-0.1:   User=0.63  Real=0.58  Sys=0.01
gamma/0.1-1:   User=27.95  Real=29.7  Sys=0.48
gamma/1-10:   User=0.38  Real=0.36  Sys=0

which can be obtained with the commands

/gamos/classifier ClassifierByParticleAndKinE GmCompoundClassifier GmClassifierByParticle GmClassifierByKineticEnergy

/gamos/userAction GmTimeStudyUA ClassifierByParticleAndKinE

The time in each category is the time counted at each step. Exactly it is the counting from the beginning to the end of the method G4SteppingManager::Stepping(). To do this without modifying the Geant4 class, the class GmTimeStudyMgr inherits from G4VSteppingVerbose and it is set as the stepping verbose class, substituting the class G4SteppingVerbose class, that is the one that controls the verbosity of the command /tracking/verbose. This means that this command will have no effect and if you want to use it you should do with the parameter

/gamos/setParam GmTimeStudyUA:G4VerboseLevel VERB

You may observe that the time summed over all the categories is smaller than the run time given by the command /run/verbose 1. This is because the time is only the time spent at the method mentioned above, which does not take into account the initialisation and termination times of each track, event and run.

Changing the weight using a distribution

The command /gamos/userAction GmChangeWeightUA changes the weight at each step or track following a GAMOS distribution. You have to set the distribution with the parameter:

/gamos/setParam USER_ACTION_NAME:Distribution DIST_NAME

Copying the weight to the secondary particles

Geant4 usually copies the weight of a track to the secondary tracks that it creates. But in the process is RadioactiveDecay, this does not work. Therefore if you are using radioactive decay and need this feature you have to activate the user action :

/gamos/userAction GmCopyWeightToSecondaryUA

Stopping run after a certain CPU time

There may be some times when you want to limit the CPU time so that the job stops even if all the events demanded have not run. To do it you can use the user action /gamos/userAction GmStopRunAfterTimeUA. The time is limited with the parameter:

/gamos/setParam USER_ACTION_NAME:Time TIME

In fact, the time is only checked after each event, so you may find that the time it actually stops is bigger than what you demanded.

Visualising only a set of events

This utility is designed for the case when you want to visualise only a few events but not the rest (e.g. because the interesting event happens after many others and storing them all occupies a log of space in the visualization file). To do this you have to select the user action:

/gamos/userAction GmVisStoreTrajUA

You can set the list of events that you want to visualise with the parameter

/gamos/setParam USER_ACTION_NAME:EventLis EVENT_1 EVENT_2 …

And starting by one event in the list you can select how many events are to be visualised with the parameter:

/gamos/setParam USER_ACTION_NAME:NEvents NEVENTS

Setting the correlation between the gammas of a radioactive decay chain

The user action:

/gamos/userAction GmRadDecayGammaAngleCorrelationUA

is a prototype class to allow the user to set the correlation between the gammas produced in a decay chain. As of now it only sets the correlations for the two gammas, of energies 1.1732 and 1.3325 MeV of the decay chain of the Cobalt 60 radioisotope, and the correlation is a random one. If you are interested in this feature please contact the GAMOS team.

Printing electromagnetic parameters

The user action:

/gamos/userAction GmPrintEMParamsUA

serves to print the current electromagnetic parameters. See the Geant4 documentation to understand the meaning of each one.