Phase-Space Track Analysis

Phase-space track analysis is a special CIRSOS/GRAS module developed under the ESA AREMBES project for the simulation of the background of the ATHENA x-ray telescope - the ESA L2 mission of the Cosmic Vision programme. The purpose of this analysis module is to record to an output file the range of parameters defining individual particle tracks which cross one or more sensitive volumes (SV) of the Geant4 geometry. These parameters include particle type, charge, position, momentum direction cosines, kinetic energy, physical volume, etc. In addition, details of the primary particles generating these interactions are also recorded. The results are stored to the ROOT file used by GRAS for analysis output, but can then be translated into a FITS-file format by the ConvertPSTrackROOTtoFITS application [REF NEEDED].

How to define a phase-space track analysis

The phase-space track analysis is implemented as a standard GRAS analysis module, with the basic steps for defining such an analysis best illustrated with the G4 macro example below.

/gras/analysis/PSTrack/addModule pst1
/gras/analysis/PSTrack/pst1/addVolume vSiDetector1_PV 3
/gras/analysis/PSTrack/pst1/addVolume vSiDetector1_PV 5
/gras/analysis/PSTrack/pst1/addVolume vScintillator1_PV
/gras/analysis/PSTrack/pst2/stepLength vSiDetector2_PV 1.0 nm
/gras/analysis/PSTrack/pst2/stepLength vScintillator2_PV 1.0 cm

/gras/analysis/PSTrack/addModule pst2
/gras/analysis/PSTrack/pst2/addVolume vSiDetector2_PV
/gras/analysis/PSTrack/pst2/addVolume vScintillator2_PV
/gras/analysis/PSTrack/pst1/minEvent 4000
/gras/analysis/PSTrack/pst1/maxEvent 7000

/gras/analysis/PSTrack/saveModulo 1000

1. Add a new module of your given name; in the above case, two PSTrack modules are added, called pst1 and pst2.

2. Select a physical volumes in which they are to apply. Note the next field to the volume selection box is for specifying the copy number of the volume. If omitted, all copies of the physical volume with this name are added. In the example, events will be tallied only in copies 3, 5 and 6 of physical volume vSiDetector1_PV for PSTrack module pst1, whilst events for all copies of vScintillator1_PV will be tallied in pst1 and, likewise, all copies of vSiDetector2_PV and vScintillator2_PV will be used to tally events for pst2.

3. A minimum step length can be applied for each volume, as shown in the definition of pst1. By default, no details of the steps taken within the volume are recorded in the phase-space output, only the entrance and exit to the SV, or particles generated or terminated within the SV (i.e. begin-of-track and end-of-track events), as well as the details of the source particles. In the definition of pst1 above, the end-of-step information is recorded if the distance since the last recorded step equals or exceeds 1.0 nm in vSiDetector1_PV or 1.0 cm in vScintillator1_PV. (See Note A below)

4. User can define the minimum and maximum range of events for which phase-space information will be stored, i.e. the simulation may be run for 10,000 events, but for the case of pst2 phase-space details are recorded for events 4,000 to 7,000.

5. The user can define the number of events in each batch using the gras/analysis/PSTrack/saveModulo command, so that after each batch the ROOT file is updated with new phase space information. This events-per-batch quantity is distinct from the save modulo information used elsewhere in GRAS, since saving PSTrack information can be very I/O-intensive. For simplicity, the same batch interval is used for all phase-space track modules. (See Note B below)

Note A

minimum step length

For the “minimum step length” option, currently the copy number of the volume is not used. Therefore, for multiple entries of a volume with different copy numbers, the last specification is applied for all volume+copy combinations.

Note B

large runs

It is recommended that for large runs, the events per batch should be set so that the total number of batches (total-events/events-per-batch) is approximately 100, and should not be significantly larger than this value. The maximum number of batches is capped by the GRAS simulation at 250.

Phase Space Track information stored in ROOT file

For each phase-space track module defined in the GRAS input, a set of volume information N-tuples is created within the ROOT file, together with one or more collections of phase-space track N-tuples is created giving the results of the simulation.

The volume information N-tuple set takes the name <moduleName>_tuple_PSTrackVolumeInfo where <moduleName> is the name assigned by the user (pst1 or pst2 in the example above). This contains all the information relevant to the physical volumes assigned to the phase-space track module. This includes full information about the parent, grandparent, great-grandparent, etc. physical volumes in order to unambiguously identify the location of the SV within the geometry hierarchy. The N-tuple set is recorded to the ROOT file just before executing the first event, therefore even if no phase-space track information is recorded, the volume information will still be saved.

N-tuple for ROOT Volume information

Variable(s)	Variable Type	Comments
uniqueID	Int_t	Unique integer identifier for volume (see Note C)
level	Int_t	Level of physical volume in geometry (see Note C)
PVname	std::string	Physical volume name
instanceID	Int_t	Physical volume instance ID (i.e. index of physical volume in the G4Physi calVolumeStore)
copyNo	Int_t	Physical volume copy number
mPVname	std::string	Name of mother physical volume
mInstanceID	Int_t	Mother physical volume instance ID
mCopyNo	Int_t	Mother physical volume copy number
key	std::string	Unique key identifying all antecedents (see Note C )
tX,tY,tZ (3 fields)	Double_t	Coordinates for location (translation) of physical volume in mother volume [mm].
rXX,rXY ,rXZ,rYX,rYY,rY Z,rZX,rZY,rZZ (9 fields)	Double_t	Coordinates for orientation (3D-rotation) of physical volume in mother volume.

Note C

Antecedent Identification

uniqueID is introduced as an index which provides a completely unique reference to a specific (sensitive) physical volume and copy number within the geometry. key is a string variable which describes the hierarchical location of the SV in the geometry. key follows the pattern “/N4.0/N3.M3/N2.M2/N1.M1/N0.M0” where the Ns are the G4 instance numbers of the physical volumes, and Ms are the copy numbers, so that volume N0.M0 is inside N1.M1 which is inside N2.M2 which is inside M3.N3 etc. In this example N4.0 would represent the world-volume of the geometry. Overall this approach is similar to a computer directory structure in both format and logic. As recent addition to treat layered mass (parallel) worlds, the level of each physical volume in the geometry is identified with level =0 indicating the Mother mass geometry and negative levels indicating the top level of each of the parallel worlds (level =-1 for the first layered mass world, level =-2 the second layered mass world, etc).

Phase-space track information N-tuple sets have the name(s) <moduleName>_tuple_PSTrack_<IB> where <IB> is the event batch number (starting at zero). This N-tuple contains the particle parameter data including particle name, SV, position, momentum direction cosine, kinetic energy, etc. To improve efficiency of writing the phase-space information, the data are saved in <IB> batches, and the user can control the number of events per batch as discussed in the previous section.

The table below describes the fields within the phase-space track N-tuple. Each record in the collection corresponds to one of the following types of event (see subsequent table, “N-tuple for ROOT phase-space track information record types”):

• Begin of event, identifying the properties of the primary particle.

• Particle entering a sensitive volume (SV);

• Particle leaving a SV;

• New Geant4 track within the SV (e.g. secondary particle production in SV);

• End of Geant4 track in the SV (e.g. particle slows and stops in SV);

• Geant4 step within the SV.

N-tuple for ROOT phase-space track information

Variable(s)	Variable type	Comments
recordType	std::string	Definition of type of record (N-tuple); options are defined in the next table.
eventID	Int_t	Geant4 index for event
trackID	Int_t	Geant4 index for track in current event; set to -1 if particle is a source and simulation has not yet started.
stepID	Int_t	Geant4 index for the step; set to: -1 if recordType = BeginTrackInVolume; 2147483647 if recordType EndTrackInVolume .
iVertex	Int_t	Index for the source vertex >=0 if recordType = BeginEvent otherwise iVertex =-1
particleID	Int_t	Index for particle generated at vertex iVertex; particleID >=0 if recordType = BeginEvent, otherwise particleID = -1
particleName	std::string	Conventional Geant4 name for particle.
PDGEncoding	Int_t	Geant4 PDG code for particle type.
Z	Int_t	Atomic number of ion.
A	Int_t	Nucleon number of ion.
Q	Double_t	Charge of particle.
excitation	Double_t	Excitation energy of ion [MeV].
weight	Double_t	Statistical weight of particle.
KE	Double_t	Kinetic energy of particle [MeV].
GT	Double_t	Global time associated with current particle step [s].
GX,GY,GZ (3 fields)	Double_t	Particle position in global frame (World physical volume) [mm].
LX,LY,LZ (3 fields)	Double_t	Particle position in local frame (current physical volume) [mm].
pGX,pGY,pGZ (3 fields)	Double_t	Particle momentum direction cosines.
Edep	Double_t	Cumulative energy deposition for the track within a SV [MeV]; set to 0.0 if recordType = BeginEvent.
process	std::string	Name of physical process which has created particle; set to “SOURCE” if the track has no parent.
pTrackID	Int_t	Geant4 index for track of the parent; set to -1 if the track has no parent.
pPDGEncoding	Int_t	Geant4 PDG code for parent particle type; set to 0 if track has no parent.
porigKE	Double_t	Kinetic energy of parent particle at the time of its creation [MeV]; set to 0.0 if track has no parent.
pKE	Double_t	Kinetic energy of parent particle at pre-step point just prior to creation of the current particle [MeV]; set to 0.0 if track has no parent.
uniqueID	Int_t	Unique integer identifier for volume (corresponds to the index used in the first row of previous table); set to -1 if recordType = BeginEvent.
PVname	std::string	Current physical volume name; set to “UNDEFINED” if recordType = BeginEvent.
instanceI	D Int_t	Current physical volume instance ID, i.e. index of physical volume in the G4Physi calVolumeStore; set to -1 if recordType = BeginEvent.
copyNo	Int_t	Copy number for current physical volume; set to -1 if recordType = BeginEvent.
mPVname	std::string	Name of mother physical volume for the current volume; set to “UNDEFINED” if recordType = BeginEvent.
mInstanceID	Int_t	Mother physical volume instance ID; set to -1 if recordType = BeginEvent.
mCopyNo	Int_t	Mother physical volume copy number; set to -1 if recordType = BeginEvent.

Note the following regarding the above table:

• particleName, Z and A may be considered superfluous given the PDG code for the particle is supplied. However, for now these fields are included to allow easy reading of the data.

• PVname, instanceID and copyNo as well as mPVname, mInstanceID and mCopyNo are not strictly necessary since uniqueID can be cross-referenced to the volume information N-tuple. Once again, these fields are retained for now to allow the data to be more readily understood.

• pTrackID, pPDGEncoding, and pKE (the parent particle ID, species, and kinetic energy, respectively) are repeated for each instance of the daughter track reported in the phase-space file. This is a little inefficient in terms of storage but has been done to avoid making the ROOT (and subsequent FITS) file structure too complicated.

N-tuple for ROOT phase-space track information record types

recordType value (std::string)	Definition
BeginEvent	Source particle prior to definition of track or any geometry navigation is performed.
EnteringVolume	Track enters one of the PVs associated with the module.
ExitingVolume	Track leaves PV.
BeginTrackInVolume	New track is created within the PV, e.g. particle created through interaction.
EndTrackInVolume	Track ends in PV, e.g. particle comes to rest.
StepInVolume	Particle takes a step in the volume.

Parent particle parameters

Each phase-space track record in the ROOT file includes the parent particle PDG code (pPDGEncoding) and the parent particle’s kinetic energies at the time of the parent’s creation (porigKE) and just prior to the creation of the tracked particle (pKE). For pKE, the energy is recorded at the pre-step point of the parent before the discrete or continuous interaction process. If the tracked particle is a primary and therefore has no parent, pPDGEncoding is set to 0 and porigKE and pKE are both set to 0.0.

Energy deposition (Edep) information

Each phase-space track tuple includes energy deposition information along a particle track as a function of sensitive volume. The field is Edep, and provides the cumulative energy deposition (in MeV) to the SV as a function of the track’s step. Note the following:

• The energy deposition is taken from the GRASinfo class, which it is understood comes from the G4Step::!GetTotalEnergyDeposit deposit member function. GRAS does not traditionally retain the information from non-ionising energy deposition along the step as well within the GRASinfo class or within GRASAnalysisManager, and therefore as a minor correction for the further deduction of the non-ionising energy from the step could also be included after discussion with ESA and other GRAS maintainers.

• The energy is cumulative, that is if track N passes through SV!#1 for the first time it’s energy deposition starts at 0 MeV and increases to E1 when it leaves. If it then passes through another SV (SV!#2) the energy deposition will start at zero and increase to E2 when it leaves. If the track then re-enters SV!#1, the energy deposition will start from E1 and increase until the particle leaves or stops.

• At the end of the event, the energy deposition in the SV from all tracks will equal the total KE of particles in the event which entered the SV minus the total KE of particles leaving the SV. A verification has been performed of this, in it appears accurate to within 10^-12 MeV.

---

GRAS/trunk/r2242