Analysis of data output

Introduction: GAMOS data

There is a big variety of data that can be extracted out of a simulation (position, energy lost, event ID, particle name, angle between primary and secondary, …). We have transformed each of these data into a plug-in, so that it can be used with a user command to fill an histogram, be dumped into a text or binary file, filter on an interval of its values, make a classification as a function of the data value intervals or use them for importance sampling.

A GAMOS data plug-in may return a different value depending on when it is called. The following options are possible:

  • At each track step

  • At the beginning of a track

  • At the end of a track

  • At the beginning of a event

  • At the end of a event

  • At the beginning of a run

  • At the end of a run

  • When a secondary track is created (this case is used for relating the variables of an initial track and the secondary tracks it creates)

Each of the GAMOS data does not have to implement the methods to return a value in all cases, as in some cases it has no meaning. Examples can be the position for a run, the final energy for a secondary track (which has not been started to be tracked) or the track ID for an event. If a data is used when the case has no meaning, it will return an exception.

For many types of data one can make a distinction between the Initial and the Final values. This again has a different meaning depending on when it is called:

  • Track step: Initial refers to the data at PreStepPoint (i.e. at the first point of the step). Final refers to the data at PostStepPoint (i.e. at the second point of the step)

  • Track: Initial refers to the data at vertex. Final refers to the data at the current point

  • Event: Initial refers to the data of the first particle in the event. Final has no meaning

  • Run: Initial has no meaning. Final has no meaning

  • Secondary tracks: Initial refers to the data when the particle is created (not being tracked yet). Final has no meaning

The data of these type have in their name the word Initial or Final.

Other data are of type Change, because they return the data at the Final point minus the data at the Initial point. Of course, these data can only have sense for Step and Track. The data of these type have in their name the word Change.

Still other data are of type Accumulated, because they return the data accumulated along the steps. The data of these type have in their name the word Accumulated. Their behaviour depends on when they are called:

  • Track step: the value of the step itself.

  • Track: the value summed up of all the step of the track.

  • Event: the value summed up of all the tracks of the event.

  • Run: the value summed up of all the events of the run.

  • Secondary tracks: it has no meaning.

Be aware of the behaviour of the filters when you use data of type Accumulated with a user action. If an step does not pass a filter, the data will not be accumulated, and when the value is printed at the end of the track, event or run it may give a wrong result. You may want to use the option to switch off the filters at stepping with the parameter:

/gamos/setParam USER_ACTION_NAME:ApplyFiltersToStepping false

See section on Filters for more details on this option.

Another source of classification of data is their C++ type: double, int or string. The behaviour of double and integer data is very similar, the main difference being that in a binary file they are written in different format, and occupy a different number of bytes. Each string data has a variable that defines the number of characters that will be used when writing a binary file. The string data cannot be used to fill an histogram.

It is possible to use at the same time several data to fill 2D, 1D profile or 2D profile histograms. To do it the data has to be separated by .vs. if it is for a 2D histogram, .prof. if it is for a 1D profile histogram and both .vs. and .prof. if it is for a 2D profile histogram. See section on Data users for examples on this.

Data can also be used in mathematical expressions, for example log10(InitialKineticEnergy), sqrt(2*FinalPosX*FinalPosY), …

Each data has as a property the histogram number of bins (that for all is 100), the minimum and maximum. In case it is a composed data, i.e. using mathematical expressions, the minimum and maximum will be calculated with the same formula used for the data. If you want to avoid this calculation the following parameter must be set:

/gamos/setParam GmVData:ComposeHistoLimits 0

These values can be changed as for any histogram (see section on Histograms).

Data users

The data users are user actions that use the data to fill histograms or to dump them in text or binary files or dump them in the screen. There is one user action for each of the five types of information objects (step, track, event, run and secondary tracks), and one user action for each of the four actions, making in total twenty user actions. There is also a user action to dump data in a ROOT Tree; its behaviour is explained in a dedicated section below. We will describe in this section the available data users and how they behave with the different data types mentioned above.

The data can also be used to filter on an interval of values, in classifiers to give a different classification index in different user-defined intervals and in scorers to score the data values. These three usages are explained in the corresponding sections.

The behaviour of each of the data users depends on one side on the type of information object they manage and on the other side on the type of output provided.

Behaviour as a function of information object

The behaviour of each of the data users for each of the information objects is the following:

  • The Step data users implement a UserSteppingAction method, which extracts the data at each track step, from the G4Step object.

  • The Track data users implement a PostUserTrackingAction method, which extracts the data at the end of the current track step, from the G4Track object (equal to the current track status). For the data of type Initial the data is extracted from the vertex information of the G4Track object. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a PreUserTrackingAction, which initializes the data to 0; the PostUserTrackingAction uses the accumulated data, instead of extracting the data from the G4Track object.

  • The SecondaryTrack data users implement a UserSteppingAction method, which extracts the data at each track step, from the G4Track object of all secondary tracks created in the step. When setting filters or classifiers to one of these data users you have to remember that they are applied by default to the primary tracks; if you want to applied them to the secondary tracks you have to explicitly do it (see sections on Filters and Classifiers)

  • The Stack data users implement a ClassifyNewTrack method, which extracts the data when the tracks are taken from the stack, from the G4Track object.

  • The Event data users implement a EndOfEventAction method, which extracts the data at the end of the event, from the G4Event object. For the data of type Initial the data is extracted from the information of the first primary particle of the first primary vertex. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a BeginOfEventAction, which initializes the data to 0; the EndOfEventAction uses the accumulated data, instead of extracting the data from the G4Event object.

  • The Run data users implement a EndOfRunAction method, which extracts the data at the end of the run, from the G4Run object. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a BeginOfRunAction, which initializes the data to 0; the EndOfRunAction uses the accumulated data, instead of extracting the data from the G4Run object.

Note: the data of type Initial is printed (or used to fill an histogram) at the end of track, event or run, with the aim of having together all the information relevant to an object. This behaviour can be changed, so that this data is print at the start with the parameter

/gamos/setParam DATA_USER_NAME:UseAtInitial 1

Behaviour as a function of output format

The behaviour of each of the data users for each of the output type provided is the following:

  • Histograms: the histogram data users (i.e. GmStepDataHistosUA, GmTrackDataHistosUA, GmSecondaryTrackDataHistosUA, GmStackDataHistosUA, GmEventDataHistosUA, GmRunDataHistosUA,) fill histograms with the data values. By default 1-dimensional histograms are filled but if several data are used at the same type other histogram types are possible: if a 2-dimensional histogram is required the names of the two data have to be separated by .vs.; if a 1-dimensional profile histogram is required the names of the two data have to be separated by .prof.; if a 2-dimensional profile histogram is required the names of the three data have to be separated by .vs. and .prof.. For example: FinalKineticEnergy.vs.InitialKineticEnergy will fill a 2D histogram. FinalKineticEnergy.prof.InitialKineticEnergy will fill a 1D profile histogram. FinalKineticEnergy.vs.InitialKineticEnergy.prof.InitialPositionZ will fill a 2D profile histogram. The name of the histogram file is given by the name of the data user plus the filters and classifiers plus the histogram type (i.e. .root or .csv. It can be changed with the parameter: /gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME For example: /gamos/userAction GmStepDataHistosUA GmGammaFilter will produce a file named GmStepDataHistosUA_GmGammaFilter.root, whose name can be changed with the command: /gamos/setParam GmStepDataHistosUA_GmGammaFilter:FileName NEW_FILE_NAME to produce a file named NEW_FILE_NAME.root

  • Text files: These data users (i.e. GmStepDataTextFileUA, GmTrackDataTextFileUA, GmSecondaryTrackDataTextFileUA, GmStackDataTextFileUA, GmEventDataTextFileUA, GmRunDataTextFileUA) dump the data values into text files. A line is written for each call to the data user object (i.e. each G4Step, G4Track, …). The text file is indeed a CSV (Comma Separated Value) file; this means that values are separated by commas and string values are surrounded by double quotes. Optionally a header line can be written containing the names and order of the data to be written. With the aim of clearly distinguishing it, the first word of the header is always HEADER:. The second word is the number of words, and then the data names. To select this option the following parameter has to be used: /gamos/setParam FILE_NAME:WriteHeaderData 1 The name of the text file is given by the name of the data user plus the filters and classifiers plus (i.e. .out. It can be changed with the parameter: /gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME For example: /gamos/userAction GmStepDataTextFileUA GmGammaFilter will produce a file named GmStepDataTextFileUA_GmGammaFilter.out, whose name can be changed with the command: /gamos/setParam GmStepDataTextFileUA_GmGammaFilter:FileName NEW_FILE_NAME to produce a file named NEW_FILE_NAME.out

  • Binary files: These data users (i.e. GmStepDataBinFileUA, GmTrackDataBinFileUA, GmSecondaryTrackDataBinFileUA, GmStackDataBinFileUA, GmEventDataBinFileUA, GmRunDataBinFileUA,) dump the data values into binary files. Data of integer type are written as int, occupying four bytes. Data of double type are written as float (for space savings), occupying four bytes (NOTE: in case you want to write all your data as double, you just have to replace float by double in the four WriteBin(…) methods in the file GamosCore/GamosData/Data/src/GmVData.cc, and recompile GAMOS). Data of string type are written as a list of char; each string data has a default number of characters, that can be overridden with the parameter: /gamos/setParam DATA_NAME:NumberOfChars NCHARS To allow checking the format when the file is read back, specially useful if the file is read in a different computer system than the one where it was written, or by another program than GAMOS, a check line is read. This check line consists on first an L or B character, depending on whether the computer system uses little endian or big endian; second the integer 1234567890 is written, occupying four bytes; third the float 3.40282e+38 is written, occupying four bytes, last the double 1.79769e+308 is written, occupying eight bytes. Optionally four other headers can be written after the first check line. If any header is being written before then four integer numbers are always written, whose values are 0 or 1 depending if the corresponding header is written. The first optional header serves to check that your software system is able to read the file, which you may have written using another system. It writes first a char equal to L or B depending if the system uses little endian or big endian convention. Then it writes as an int the number 1234567890, as a float the number 3.40282e+38 and as a double the number 1.79769e+308. You should check that you read back those numbers when reading your file. To write this header the following parameter has to be used: /gamos/setParam FILE_NAME:WriteHeaderCheck 1 The second optional header contains the names and order of the data to be written; the first word is an integer with the number of data; then for each data it is written an integer with the number of characters of the data name, the data name itself with this number of characters, the number of characters of the data C++ type, and finally the C++ type itself with this number of characters (which can be int, float or char). To write this header the following parameter has to be used: /gamos/setParam FILE_NAME:WriteHeaderData 1 The third optional header is a float containing the number of events used in the job (see for example the section on Radiotherapy phase space reading or using files as generator for the exact meaning of the number of events in these cases). To write this header the following parameter has to be used: /gamos/setParam FILE_NAME:WriteHeaderNEvents 1 The fourth optional header is an integer containing the number of calls to the data user object. To write this header the following parameter has to be used: /gamos/setParam FILE_NAME:WriteHeaderNCalls 1 The name of the binary file is given by the name of the data user plus the filters and classifiers plus (i.e. .out. It can be changed with the parameter: /gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME For example: /gamos/userAction GmStepDataBinFileUA GmGammaFilter will produce a file named GmStepDataBinFileUA_GmGammaFilter.out, whose name can be changed with the command: /gamos/setParam GmStepDataBinFileUA_GmGammaFilter:FileName NEW_FILE_NAME to produce a file named NEW_FILE_NAME.out

  • Cout: These data users (i.e. GmStepDataCoutUA, GmTrackDataCoutUA, GmSecondaryTrackDataCoutUA, GmStackDataCoutUA, GmEventDataCoutUA, GmRunDataCoutUA) dump the data values into the standard output (they may be helpful to debug an application, together with the command /tracking/verbose 1. Similarly to the text file data users, a line is written for each call to the data user object (i.e. each G4Step, G4Track, …). The text file is indeed a CSV (Comma Separated Value) file; this means that values are separated by commas and string values are surrounded by double quotes.

Selection of data list for a data user

Each data user has a default list of data, that we will enumerate below. This list can be changed with the parameter:

/gamos/setParam DATA_USER_NAME:DataList DATA_1 DATA_2 …

For example, if we use:

/gamos/userAction GmStepDataBinFileUA GmGammaFilter

the data list may be changed with the parameter:

/gamos/setParam GmStepDataBinFileUA_GmGammaFilter:DataList TrackID FinalPosX sqrt(2*FinalPosX*FinalPosY) InitialKineticEnergy

Default data list for each data user

The default data list of each of the fifteen data users are:

  • GmStepDataHistosUA:

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulatedEnergyLost

  • AccumulatedEnergyDeposited

  • GmStepDataTextFileUA:

  • EventID

  • TrackID

  • Particle

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulateEnergyLost

  • AccumulateEnergyDeposited

  • GmStepDataBinFileUA:

  • EventID

  • TrackID

  • Particle

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulateEnergyLost

  • AccumulateEnergyDeposited

  • GmTrackDataHistosUA:

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulatedEnergyLost

  • AccumulatedEnergyDeposited

  • GmTrackDataTextFileUA:

  • EventID

  • TrackID

  • Particle

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulateEnergyLost

  • AccumulateEnergyDeposited

  • GmTrackDataBinFileUA:

  • EventID

  • TrackID

  • Particle

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • AccumulateEnergyLost

  • AccumulateEnergyDeposited

  • GmEventDataHistosUA:

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmEventDataTextFileUA:

  • EventID

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmEventDataBinFileUA:

  • EventID

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmRunDataHistosUA:

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmRunDataTextFileUA:

  • RunID

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmRunDataBinFileUA:

  • RunID

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • GmSecondaryTrackDataHistosUA:

  • TrackID

  • InitialPrimMinusSecoKineticEnergy

  • FinalPrimMinusSecoKineticEnergy

  • SecoDividedInitialPrimKineticEnergy

  • SecoKineticEnergy

  • PrimSecoAngleChange

  • InitialPrimKineticEnergy

  • FinalPrimKineticEnergy

  • GmSecondaryTrackDataTextFileUA:

  • EventID

  • TrackID

  • InitialPrimMinusSecoKineticEnergy

  • FinalPrimMinusSecoKineticEnergy

  • SecoDividedInitialPrimKineticEnergy

  • SecoKineticEnergy

  • PrimSecoAngleChange

  • InitialPrimKineticEnergy

  • FinalPrimKineticEnergy

  • GmSecondaryTrackDataBinFileUA:

  • TrackID

  • InitialPrimMinusSecoKineticEnergy

  • FinalPrimMinusSecoKineticEnergy

  • SecoDividedInitialPrimKineticEnergy

  • SecoKineticEnergy

  • PrimSecoAngleChange

  • InitialPrimKineticEnergy

  • FinalPrimKineticEnergy

Saving GAMOS data in a ROOT TTree

The GmDataTTreeUA data user sorts GAMOS data in a ROOT TTree structure and save the new TTree in a ROOT TFile. The GmDataTTreeUA is invoked with the usual command:

/gamos/userAction GmDataTTreeUA

By default the TTree is created with the GmDataTTree name and saved in the GmDataTTree.root file. The following command can be used to modify both both TFile and TTree names:

/gamos/setParam DATA_USER_NAME:TreeFileName NEW_NAME

Four categories of GAMOS data can be saved in the TTree: Event data, Track data, Secondary Track data, and Step data. GAMOS users can select one list of data for each one of the four categories. If data with no meaning for a given category are included in the correspondent list (e.g. adding trackID data to the Event data list), an exception will be returned. By default, the four data lists are empty and nothing is saved in the TTree unless otherwise specified. The four data lists are selected as follows:

/gamos/setParam DATA_USER_NAME:EventDataList EVENT_DATA_1 EVENT_DATA_2 …

/gamos/setParam DATA_USER_NAME:TrackDataList TRACK_DATA_1 TRACK_DATA_2 …

/gamos/setParam DATA_USER_NAME:SecondaryTrackDataList SECO_DATA_1 SECO_DATA_2 …

/gamos/setParam DATA_USER_NAME:StepDataList STEP_DATA_1 STEP_DATA_2 …

DATA_USER_NAME is the name of the user action, i.e. the word GmDataTreeUA plus the name of filters and classifier

The TTree is filled at the end of each GAMOS event and contains a number of entries equal to the number of simulated events. Each of the selected GAMOS data is stored in an independent TBranch inside the TTree.

Data are saved as integers, doubles, or strings. For each TTree entry, each of the selected GAMOS data is stored in a std::vector, apart from Event data that correspond to single values. The size of a std::vector varies in accordance with the corresponding category: track data vectors contain a number of elements equal to the number of tracks for a given event; step and secondary track data vectors equal to the number of steps for the same event.

Filter from data

It is possible to use any GAMOS data to filter on its value (see chapter on Filters). To use it you have to use the command to define a filter, using the filter named GmNumericDataFilter if the data is of numeric type (int or float) and GmStringDataFilter if the data is of string type and passing the following arguments:

GmNumericDataFilter: In this case after the filter name you have to give the the minimum and maximum value of the data. For example:

/gamos/filter dataF GmNumericDataFilter InitialKineticEnergy 0. 0.3

GmStringDataFilter: In this case after the filter name, you have to give the list of accepted values. For example:

/gamos/filter dataF GmStringDataFilter InitialLogicalVolume detector world

Classifier by data

It is possible to use any GAMOS data to classify on its value (see chapter on Classifiers). To use it you have to use the command to define a classifier, using the classifier named GmClassifierByNumericData if the data is of numeric type (int or float) and GmClassifierByStringData if the data is of string type and passing the following arguments:

  • Data is integer or float: In this case after the classifier name you have to give the number of intervals, the minimum data limit and the maximum data limit. For example to define 20 energy intervals between 0 and 10 : /gamos/classifier dataC GmClassifierByData InitialKineticEnergy 20 0. 10. GAMOS will check if the data value is inside the interval defined by the minimum and maximum. If it is smaller, it will assign an index 0, if it is bigger it will assign an index INT_MAX (2^32). In both cases a warning will be printed. If you do not want to allow this behaviour, but you want that the job is stopped if the data is out of limits, you have to set the parameter: /gamos/setParam CLASSIFIER_NAME:AllowOutOfLimits 0

  • Data is string: In this case no argument is needed after the classifier name. For example: /gamos/classifier dataC GmClassifierByData InitialLogicalVolume If you want to assign different indices than 0 to N, you may use the command : /gamos/classifier/setIndices VALUE_1 INDEX_1 VALUE_2 INDEX_2 See section on Setting indices to classifiers for further details on this feature.

Primitive scorer from data

It is possible to use any GAMOS data, if its type is integer of float, to build an scorer on its value (see chapter on Scorers). To use it you have to use the command to define a scorer, using the scorer named GmG4PSData and passing to it the data name and the minimum and maximum value of the data. For example:

/gamos/scoring/createMFDetector contDet container

/gamos/scoring/addScorer2MFD dataScorer GmG4PSData contDet InitialKineticEnergy

List of available data

There are over one hundred types of data currently available in GAMOS. We list here them all, mentioning for each one if it is of type double (default, not needed to be indicated), int of string, if it is of type Accumulated (Initial, Final or Change is in the data name), the minimum and maximum values if an histogram is filled with it, and if it is not available for Step, Track, Event , Run, or Secondary track.

For each data we explain how its value is obtained for each of these five cases, if the value is not evident (i.e. the behaviour of FinalKineticEnergy should be evident for what we have explained above if called for a Step or a Track).

We may also get a list of available data for a GAMOS release by typing in your terminal window (after GAMOS has been configured)

SealPluginDump | grep GmData

For a better description of the available data we have classified them in several groups

Position data

The position is a 3-dimensional vector, so the following data can be obtained from it:

  • X: projection on X axis

  • Y: projection on Y axis

  • Z: projection on Z axis

  • Mag: magnitude

  • Perp: perpendicular projection (i.e. sqrt(X*X+Y*Y) )

  • Phi: phi angle (in degrees)

  • Theta: theta angle (in degrees)

All these data can be of type Initial, Final or Change. The Initial data are available for all information objects except Run, while the Final and Change data are available only for Step and Track. There are other data that calculate the local position, i.e. the global position transformed into the local frame of the volume the particle is in. The InitialLocalPos data for a Step object calculates the transformation in the volume the track step has just traversed, while for a Track object calculates the transformation in the volume where the track was initiated. The FinalLocalPos data for a Step object calculate the transformation in the volume the track step is going to enter, the same as for a Track object. You may be interested in getting the transformation in the volume the track step has just traversed, but using the position and the end of the step. In this case you can use another set of data, called LocalInPre. For a Track object these data use the current position of the track, but the volume where the track was initiated. If you want to get the vertex position for a step (for a track is obtained as InitialPos) you may use the data Vertex; this data are useful for StackData data users, as the initial or final positions are not calculated at stacking action. Another set of data, RandomPos select randomly a point in the line joining the PreStepPoint and PostStepPoint.

The histogram limits for X, Y and Z are -1000 (mm) to 1000 (mm), for Mag and Perp are 0 to 1000 (mm), for Phi are 0 to 360 (deg) and for Theta are 0 to 180 (deg). The position data are:

  • InitialPosX

  • InitialPosY

  • InitialPosZ

  • InitialPosMag

  • InitialPosPerp

  • InitialPosPhi

  • InitialPosTheta

  • FinalPosX

  • FinalPosY

  • FinalPosZ

  • FinalPosMag

  • FinalPosPerp

  • FinalPosPhi

  • FinalPosTheta

  • InitialLocalPosX

  • InitialLocalPosY

  • InitialLocalPosZ

  • InitialLocalPosMag

  • InitialLocalPosPerp

  • InitialLocalPosPhi

  • InitialLocalPosTheta

  • FinalLocalPosX

  • FinalLocalPosY

  • FinalLocalPosZ

  • FinalLocalPosMag

  • FinalLocalPosPerp

  • FinalLocalPosPhi

  • FinalLocalPosTheta

  • FinalLocalInPrePosX

  • FinalLocalInPrePosY

  • FinalLocalInPrePosZ

  • FinalLocalInPrePosMag

  • FinalLocalInPrePosPerp

  • FinalLocalInPrePosPhi

  • FinalLocalInPrePosTheta

  • RandomPosX

  • RandomPosY

  • RandomPosZ

  • RandomPosMag

  • RandomPosPerp

  • RandomPosPhi

  • RandomPosTheta

  • VertexPosX

  • VertexPosY

  • VertexPosZ

  • VertexPosMag

  • VertexPosPerp

  • VertexPosPhi

  • VertexPosTheta

  • PosChangeX

  • PosChangeY

  • PosChangeZ

  • PosChangeMag

  • PosChangePerp

  • PosChangePhi

  • PosChangeTheta

The Pos positions are calculated in the global reference frame, the LocalPos are calculated in the reference frame of the volume the step or track is in.

Direction data

The direction data are very similar to the position data, so that all what was said for position data is also valid for them. The main different is the histogram limits, which are for X, Y and Z are -1 (MeV) to 1 (MeV), for Mag and Perp are 0 (MeV) to 1 (MeV), for Phi are 0 (deg) to 360 (deg) and for Theta are 0 (MeV) to 180 (deg). Another difference is that the InitialDirMag and FinalDirMag do not exists, because their value would always be one. The direction data are:

  • InitialDirX

  • InitialDirY

  • InitialDirZ

  • InitialDirPerp

  • InitialDirPhi

  • InitialDirTheta

  • FinalDirX

  • FinalDirY

  • FinalDirZ

  • FinalDirPerp

  • FinalDirPhi

  • FinalDirTheta

  • InitialLocalDirX

  • InitialLocalDirY

  • InitialLocalDirZ

  • InitialLocalDirPerp

  • InitialLocalDirPhi

  • InitialLocalDirTheta

  • FinalLocalDirX

  • FinalLocalDirY

  • FinalLocalDirZ

  • FinalLocalDirPerp

  • FinalLocalDirPhi

  • FinalLocalDirTheta

  • FinalLocalInPreDirX

  • FinalLocalInPreDirY

  • FinalLocalInPreDirZ

  • FinalLocalInPreDirPerp

  • FinalLocalInPreDirPhi

  • FinalLocalInPreDirTheta

  • VertexDirX

  • VertexDirY

  • VertexDirZ

  • VertexDirMag

  • VertexDirPerp

  • VertexDirPhi

  • VertexDirTheta

  • DirChangeX

  • DirChangeY

  • DirChangeZ

  • DirChangeMag

  • DirChangePerp

  • DirChangePhi

  • DirChangeTheta

  • AngleChange This data represents the angle between the initial and the final directions (i.e. acos(InitialDir*FinalDir) ). In contrast, the DirChangeXXX are calculated subtraction the final minus the initial direction, what gives a 3-dimensional vector, from which the X, Y, Z, Mag, … magnitudes are obtained

Momentum data

The momentum data are very similar to the position data, so that all what was said for position data is also valid for them. The main different is the histogram limits, which are for X, Y and Z are 0 to 1 (MeV), for Mag and Perp are 0 to 1 (MeV), for Phi are 0 to 360 (deg) and for Theta are 0 to 180 (deg). The momentum data are:

  • InitialMomX

  • InitialMomY

  • InitialMomZ

  • InitialMomMag

  • InitialMomPerp

  • InitialMomPhi

  • InitialMomTheta

  • FinalMomX

  • FinalMomY

  • FinalMomZ

  • FinalMomMag

  • FinalMomPerp

  • FinalMomPhi

  • FinalMomTheta

  • VertexMomX

  • VertexMomY

  • VertexMomZ

  • VertexMomMag

  • VertexMomPerp

  • VertexMomPhi

  • VertexMomTheta

  • MomChangeX

  • MomChangeY

  • MomChangeZ

  • MomChangeMag

  • MomChangePerp

  • MomChangePhi

  • MomChangeTheta

Energy data

The energy data are a miscellaneous set of data that extract some information about energy. They have in common that the histogram limits are 0 (MeV) to 1 (MeV). They are the following:

  • InitialKineticEnergy

  • FinalKineticEnergy

  • KineticEnergyChange

  • InitialTotalEnergy

  • FinalTotalEnergy

  • VertexKineticEnergy

  • InitialDEDX This is not exactly the energy lost divided by the path length, as one may think from its name, but the dE/dX, i.e. the fraction of energy lost per distance travelled as calcualted by the Geant4 utilities with the final kinetic energy in the volume material the PreStepPoint (or track vertex) is in .

  • FinalDEDX Similar as above.

Plus some data of type Accumulated:

  • AccumulateEnergyLost

  • AccumulatedEnergyDeposited

  • AccumulatedDose: This is the energy deposited divided by the volume mass

  • AccumulatedKerma: This is the sum of energies of the charged secondary particles produced by non-charged particles, divided by the volume mass

  • InitialGammaEquivalentDose Calculates the equivalent dose multiplying the volume flux (step length divided by cubic volue) by flux to equivalent dose conversion factor read from an input file. These factors are by default the ICRU report 57, and they are read from the file MY_GAMOS_DIR/data/Flux2Dose.gamma.ICRU57.lis. You may change the input file with the paremeter: /gamos/setParam GmDataInitialGammaEquivalentDose:Flux2DoseFileName NEW_FILE_NAME You may select to calculate the personale equivalent dose, AccumulatedKerma: You may select the magnitude to use, H*(10) (default), Hp(10,0), Hp(10,15), Hp(10,30), Hp(10,45), Hp(10,60), Hp(10,75) with the parameter: /gamos/setParam GmDataInitialGammaEquivalentDose:EquivDoseType TYPE where TYPE may be Hstar, Hp0, Hp15, Hp30, Hp45, Hp60, H75

  • FinalGammaEquivalentDose Similar as above

  • InitialNeutronEquivalentDose Calculates the equivalent dose multiplying the volume flux (step length divided by cubic volue) by flux to equivalent dose conversion factor read from an input file. These factors are by default the ICRU report 57, and they are read from the file MY_GAMOS_DIR/data/Flux2Dose.neutron.ICRU57.lis. You may select the magnitude to use, H*(10) (default), Hp(10,0), Hp(10,15), Hp(10,30), Hp(10,45), Hp(10,60), Hp(10,75) with the parameter: /gamos/setParam GmDataInitialNeutronEquivalentDose:EquivDoseType TYPE where TYPE may be Hstar, Hp0, Hp15, Hp30, Hp45, Hp60, H75

  • FinalNeutronEquivalentDose Similar as above

Geometrical objects data

These are string data that extract the name of different geometrical objects, and also the type of solids (Box, Tubs, Polycone, …). All of them have 25 characters when written in a binary file. There is also an integer data for the copy number of physical volumes. They are the following:

  • InitialSolid

  • FinalSolid

  • InitialLogicalVolume

  • FinalLogicalVolume

  • InitialPhysicalVolume

  • FinalPhysicalVolume

  • InitialTouchable

  • FinalTouchable

  • InitialRegion

  • FinalRegion

  • InitialMaterial

  • FinalMaterial

  • InitialSolidType

  • FinalSolidType

  • InitialPVCopyNumber

  • FinalPVCopyNumber

Material data

These are numeric data that are related to the material. They are the following:

  • InitialDensity

  • FinalDensity

  • InitialPressure

  • FinalPressure

  • InitialTemperature

  • FinalTemperature

  • InitialRadLength

  • FinalRadLength

  • InitialNuclearInterLength

  • FinalNuclearInterLength

  • InitialElectronDensity

  • FinalElectronDensity

Particle and process data

These are string data that extract the name of the particle and the processes, and also data about the particle properties. They are only available for Step, Track and Secondary Track. All of them have 25 characters when written in a binary file. They are the following:

  • Particle

  • InitialProcess. Name of process that defined the point PreStepPoint. Only available for Step

  • FinalProcess. Name of process that defined the point PostStepPoint. Only available for Step

  • CreatorProcess. Name of process that created the particle track. Not available for Event nor Run

  • NProcesses. Number of time processes have occurred. This data needs that previously the list of processes are set with the parameter /gamos/setParam GmDataNProcesses:Processes PROCESS_1 PROCESS_2 …

  • ParticlePDGEncoding. Particle code following the Particle Data Group numbering

  • ParticleCharge

  • ParticleMass

  • ParticleLifeTime

  • ParticleWidth

  • ParticleStable. 1 if stable, 0 if unstable

  • ParticleType

  • ParticleSubType. The particles types and subtypes are listed below

Geant4 particle types and subtypes

G4Particle Type Subtypegamma gamma photon e+ lepton e e- lepton e proton baryon nucleon neutron baryon nucleon deuteron nucleus static triton nucleus static He3 nucleus static alpha nucleus static GenericIon nucleus generic mu+ lepton mu mu- lepton mu tau+ lepton tau tau- lepton tau nu_e lepton e nu_mu lepton mu nu_tau lepton tau anti_nu_e lepton e anti_nu_mu lepton mu anti_nu_tau lepton tau anti_neutron baryon nucleon anti_proton baryon nucleon pi+ meson pi pi- meson pi pi0 meson pi B+ meson B B- meson B B0 meson B Bs0 meson Bs D+ meson D D- meson D D0 meson D Ds+ meson Ds Ds- meson Ds J/psi meson J/psi anti_B0 meson B anti_Bs0 meson Bs anti_D0 meson D anti_kaon0 meson kaon eta meson eta eta_prime meson eta_prime kaon+ meson kaon kaon- meson kaon kaon0 meson kaon kaon0L meson kaon kaon0S meson kaon B+ meson B B- meson B B0 meson B Bs0 meson Bs D+ meson D D- meson D D0 meson D Ds+ meson Ds Ds- meson Ds J/psi meson J/psi anti_B0 meson B anti_Bs0 meson Bs anti_D0 meson D anti_kaon0 meson kaon eta meson eta eta_prime meson eta_prime kaon+ meson kaon kaon- meson kaon kaon0 meson kaon kaon0L meson kaon kaon0S meson kaon anti_lambda baryon lambda anti_lambda_c+ baryon lambda_c anti_omega- baryon omega anti_omega_c0 baryon omega_c anti_sigma+ baryon sigma anti_sigma- baryon sigma anti_sigma0 baryon sigma anti_sigma_c+ baryon sigma_c anti_sigma_c++ baryon sigma_c anti_sigma_c0 baryon sigma_c anti_xi- baryon xi anti_xi0 baryon xi anti_xi_c+ baryon xi_c anti_xi_c0 baryon xi_c lambda baryon lambda lambda_c+ baryon lambda_c omega- baryon omega omega_c0 baryon omega_c opticalphoton opticalphoton photon sigma+ baryon sigma sigma- baryon sigma sigma0 baryon sigma sigma_c+ baryon sigma_c sigma_c++ baryon sigma_c sigma_c0 baryon sigma_c xi- baryon xi xi0 baryon xi xi_c+ baryon xi_c xi_c0 baryon xi_c geantino geantino geantino chargedgeantino geantino geantino

Secondary tracks data

These are data that give information about the secondary particles or the primary particle when secondary particles are created. They are only available for Secondary Track. They are the following:

  • PrimParticle. Primary particle name

  • FinalPrimMinusSecoKineticEnergy. Primary particle PostStepPoint minus secondary kinetic energies

  • SecoDividedInitialPrimKineticEnergy. Fraction of kinetic energy of primary at PreStepPoint taken by a secondary particle

  • SecoKineticEnergy. Secondary particle kinetic energy

  • SecoDirTheta. Secondary direction angle theta

  • FinalPrimSecoAngle. Angle between secondary particle and Primary particle at PostStepPoint

  • InitialPrimKineticEnergy. Primary particle PreStepPoint kinetic energy when a secondary particle is emitted

  • FinalPrimKineticEnergy. Primary particle PostStepPoint kinetic energy when a secondary particle is emitted

  • VertexPrimKineticEnergy. Primary particle vertex kinetic energy when a secondary particle is emitted

Ancestor data

It is also possible to get data from an ancestor step (a previous step of the current track or of any of the tracks that is an ancestor of the current track. It is just enough to add the name AncestorStep in the name of the data.

Other data

These are miscellaneous data:

  • TrackID: ID of track. It is of integer type. Only available for Step, Track and Secondary Track

  • ParentTrackID: ID of parent track. It is of integer type. Only available for Step, Track and Secondary Track

  • EventID: ID of event. It is of integer type. Only available for Step, Track and Event.

  • RunID: ID of run. It is of integer type. Not available for Secondary Track.

  • StepNumber: number of step. It is of integer type. Only available for Step and Track

  • InitialWeight: initial track weight. Not available for Event nor Run

  • FinalWeight: final track weight. Not available for Secondary Track nor Event nor Run

  • AccumulatedLength: Accumulated step length. Not available for Secondary Track

  • TrackLength: step length for Step and track length for Track. Gives same result than AccumulatedLength but is faster

  • NofSecondaries: number of secondary tracks produced. Only available for Step and Track

  • SumSecoKineticEnergy: sum of the kinetic energies of all secondary particles produced. Only available for Step and Track

  • InitialTime: initial global time

  • FinalTime: final global time

  • InitialLocalTime: initial local time

  • FinalLocalTime: initial local time

  • InitialProperTime: initial proper time

  • FinalProperTime: final proper time

  • TimeChange: Global time change. Only available for Step

  • InitialGammaAttLength: gamma attenuation length

  • FinalGammaAttLength: gamma attenuation length

  • *InitialVelocity

  • *FinalVelocity

  • NofHits: number of hits. Only available for tracks and events

Output file names

Each user action has a default name for the output file it produces (histogram, text or binary file), as it is explained in the corresponding section of this guide. As these classes are user actions, they can be used with filters and classifiers and in this cases, to the default file name it is added the name of the filters and classifier. This default file name can be changed with the parameter

/gamos/setParam FILE_NAME:FileName NEW_FILE_NAME

If you are running a job and you want to identify all your output files with a characteristic prefix or suffix (for example to differentiate them from the files from another job), you may do it by defining the parameters:

/gamos/setParam GmAnalysisMgr:FileNamePrefix PREFIX

the name PREFIX will be added at the beggining of all output file names.

/gamos/setParam GmAnalysisMgr:FileNameSuffix SUFFIX

the name SUFFIX will be added at the end of all output file names, before the file type (.root or .csv).

In the case of other output files (or input), like the text or binary files with several kinds of data that are explained in different sections of this guide, you can also add a prefix or suffix with the above commands to all of them, as all the input and output of these classes is controlled in GAMOS through a common base class.

Merging results from different jobs

When running an application you may get a table of the different types of results. It is usual that you run different jobs with the same setup to accumulate statistics or with different setups to study the dependency of your results with some parameters. In the analysis directory of your GAMOS distribution there are specific utilities for specific outputs, for example, RTPhaseSpace/sumPS, RTDose/sumSqdose, RTDose/sum3ddose, Shielding/sumScores, Shielding/sumActivation, NuclMed/PET/sumProjdata; they are described in the corresponding section of this manual. In this section we will describe an utility to analyse the output tables produced from various runs (extract, sum or compare results) and also how to merge and analyse the output files of good events

If you have run one or several jobs and produced a table with the statistics of good events, we describe here an utility that allows to process these results and present them in a more convenient way. This utiltiy analyses the files containing the output tables and allows you to extract the desired numbers out of them and present them together in a single table, with the possibility to add the numbers from different tables. We will describe the steps you should follow to do this and illustrate them with an example.

The first thing you should do is to write a file that describe what you want to do with the output files. In the first section of this file you should list the names of the files to be used. For each file there should be a line containing two words: the first must be :FILE_TXT and the second the file name. For example if you have run three jobs with three different energy resolution values, you may put in your file

:FILE_TXT out.pet.5
:FILE_TXT out.pet.10
:FILE_TXT out.pet.15

After this you should describe the actions to be taken. Several actions can be done, for each one you have to write a line in which you describe which lines are going to be processed, which words in these lines and which action is done (print value, sum values from different files, ..)

In this action line you should first describe the criteria to identify which lines in each file are to be processed. This can be done by setting which words in the line are going to be looked for. Instead of setting the full word one can set the starting characters (prefix) or the ending characters (suffix). To set the list of prefixes you add the words:

:PRE or :PREFIX followed by a list of pairs: word position numbers and word characters. For example

:PRE 1 Events 2 PET

will look for the lines in which the first word starts by Events and the second word starts by PET.

In a similar way it can be done with the suffixes:

:SUF or :SUFFIX followed by a list of pairs: word position numbers and word characters.

If there are several lines in a file satisfying the prefix and suffix conditions, you may set that only one line or a few of them are processed, by using the word :L or :LINE followed by the list of numbers corresponding to the time order the line appears. For example:

:PRE 1 Events 2 PET :L 1

will only process the first line found.

Then you have to define which are the words in the line that are going to be processed by using the word :W or :WORD followed by the list of numbers of the words in the lines. For example:

:PRE 1 Events 2 PET :L 1 :W 3 4

will process the third and fourth words of the lines selected.

After you have to define the kind of treatment to be done to the words, by using the word :T or :TREATMENT followed by the treatment type. For example:

:PRE 1 Events 2 PET :L 1 :W 3 4 :T PT

The treatment type can be one of the following ones:

  • P or PRINT: print the words found at each line of each file, each one in a line

  • PT or PRINT_TOGETHER: print the words found at each line of each file, putting in one line the words extracted from each file (i.e. all the words found corresponding to the same instruction line together)

  • S or SUM: print the sum of the values of the words found in any line of any file

  • M or MEAN: print the mean of the values of the words found in any line of any file

Finally you may write a message that will be printed together with the results, that may serve you to identify the output. For example:

:PRE 1 Events 2 PET :L 1 :W 3 4 :T PT :M PET_EVENTS

Example of Analysing text output files

As an example of this utility, we will analyse three PET output files and extract some information from the table of PET events classification. Let’s take an output file with a table similar to this one:

---------------------------------------------
Events PET               :  862   8.62 %
--------------- Good PET -------------
ALL                          :  93   0.93 %
(   1) PET 2 recHits close to vtx   :  0   0 %
(   2) PET 2 recHits far from vtx   :  93   0.93 %
(  11) PET 3->2 recHit close to vtx :  0   0 %
(  12) PET 3->2 recHit far from vtx :  0   0 %
--------------- Random Coincidences -------------
ALL                          :  769   7.69 %
( 101) PET 2 recHits close to vtx   :  0   0 %
( 102) PET 2 recHits far from vtx   :  769   7.69 %
( 111) PET 3->2 recHit close to vtx :  0   0 %
( 112) PET 3->2 recHit far from vtx :  0   0 %
...

We have three files that we have run with different random seeds and we want to extract the following information:

  • Sum of total number of PET events in the three files

  • Mean number of good PET events in each of the three files

  • List of numbers of random coincidences PET events in each of the three files

The file to obtain these results, that we name anaout.is: may look like this:

:FILE_TXT out.exercise3c.1
:FILE_TXT out.exercise3c.2
:FILE_TXT out.exercise3c.3
:PRE 1 Events 2 PET :W 4 :T S :M "Events"
:PRE 1 ALL :L 1 :W 3 :T M :M "Good PET Events"
:PRE 1 ALL :L 2 :W 3 :T PT :M "Mean Random coincidences PET Events"

And if you run the command:

analysOutput anaout.lis

Then you may get a result like this:

Events 2596
Good PET Events 92.6667
Mean Random coincidences PET Events      769      765      763