Geant4 Cross Reference

Cross-Referencing   Geant4
Geant4/examples/extended/eventgenerator/HepMC/MCTruth/

Version: [ ReleaseNotes ] [ 1.0 ] [ 1.1 ] [ 2.0 ] [ 3.0 ] [ 3.1 ] [ 3.2 ] [ 4.0 ] [ 4.0.p1 ] [ 4.0.p2 ] [ 4.1 ] [ 4.1.p1 ] [ 5.0 ] [ 5.0.p1 ] [ 5.1 ] [ 5.1.p1 ] [ 5.2 ] [ 5.2.p1 ] [ 5.2.p2 ] [ 6.0 ] [ 6.0.p1 ] [ 6.1 ] [ 6.2 ] [ 6.2.p1 ] [ 6.2.p2 ] [ 7.0 ] [ 7.0.p1 ] [ 7.1 ] [ 7.1.p1 ] [ 8.0 ] [ 8.0.p1 ] [ 8.1 ] [ 8.1.p1 ] [ 8.1.p2 ] [ 8.2 ] [ 8.2.p1 ] [ 8.3 ] [ 8.3.p1 ] [ 8.3.p2 ] [ 9.0 ] [ 9.0.p1 ] [ 9.0.p2 ] [ 9.1 ] [ 9.1.p1 ] [ 9.1.p2 ] [ 9.1.p3 ] [ 9.2 ] [ 9.2.p1 ] [ 9.2.p2 ] [ 9.2.p3 ] [ 9.2.p4 ] [ 9.3 ] [ 9.3.p1 ] [ 9.3.p2 ] [ 9.4 ] [ 9.4.p1 ] [ 9.4.p2 ] [ 9.4.p3 ] [ 9.4.p4 ] [ 9.5 ] [ 9.5.p1 ] [ 9.5.p2 ] [ 9.6 ] [ 9.6.p1 ] [ 9.6.p2 ] [ 9.6.p3 ] [ 9.6.p4 ] [ 10.0 ] [ 10.0.p1 ] [ 10.0.p2 ] [ 10.0.p3 ] [ 10.0.p4 ] [ 10.1 ] [ 10.1.p1 ] [ 10.1.p2 ] [ 10.1.p3 ] [ 10.2 ] [ 10.2.p1 ] [ 10.2.p2 ] [ 10.2.p3 ] [ 10.3 ] [ 10.3.p1 ] [ 10.3.p2 ] [ 10.3.p3 ] [ 10.4 ] [ 10.4.p1 ] [ 10.4.p2 ] [ 10.4.p3 ] [ 10.5 ] [ 10.5.p1 ] [ 10.6 ] [ 10.6.p1 ] [ 10.6.p2 ] [ 10.6.p3 ] [ 10.7 ] [ 10.7.p1 ] [ 10.7.p2 ] [ 10.7.p3 ] [ 10.7.p4 ] [ 11.0 ] [ 11.0.p1 ] [ 11.0.p2 ] [ 11.0.p3, ] [ 11.0.p4 ] [ 11.1 ] [ 11.1.1 ] [ 11.1.2 ] [ 11.1.3 ] [ 11.2 ] [ 11.2.1 ] [ 11.2.2 ] [ 11.3.0 ]

Name Size       Last modified (GMT) Description
Back Parent directory       2024-12-05 15:16:16
Folder include/       2024-12-05 15:16:16
Folder src/       2024-12-05 15:16:16
File CMakeLists.txt 2186 bytes       2024-12-05 15:16:16
File GNUmakefile 566 bytes       2024-12-05 15:16:16
File History 1527 bytes       2024-12-05 15:16:16
File README 8516 bytes       2024-12-05 15:16:16
C++ file mctruthex.cc 3181 bytes       2024-12-05 15:16:16

  1 -------------------------------------------------------------------
  2 
  3      =========================================================
  4      Geant4 - an Object-Oriented Toolkit for Simulation in HEP
  5      =========================================================
  6 
  7                           MCTRUTH using HepMC
  8                           -------------------
  9 
 10 This example demonstrates a mechanism for Monte Carlo truth handling
 11 using HepMC as the event record. The user does not interact directly
 12 with the HepMC classes but with the MCTruthManager class which takes
 13 care with storing all the necessary information about particles,
 14 vertices and relations between them. A specialized tracking action is
 15 used to test whether given particle is to be stored or not. The
 16 decision criteria for storing particle are configurable via the
 17 MCTruthConfig class. 
 18 
 19 HOW TO BUILD THE EXAMPLE ?
 20 
 21 - if you do not have it yet, install HepMC event record (tested with version 2.06.08)
 22 
 23 - set HEPMC_ROOT_DIR variable to point to the directory where HepMC is installed; 
 24   if the HepMC is installed in your system directory (/usr/local) you do not need to set anything
 25 
 26 - run the CMake configuration and build mctruthex target in your build directory
 27       
 28 - execute the application:
 29         % your_binary_directory/mctruthex
 30 
 31 DESCRIPTION OF THE MCTRUTH HANDLING MECHANISM
 32  
 33 The main element of the MC truth handling machinery is the
 34 MCTruthManager class. This class is responsible for all the
 35 interaction with the HepMC event and does not depend on Geant4. It is
 36 a singleton, therefore it is guaranteed to be instanciated only once
 37 and the static 'GetInstance' method allows to access it from anywhere
 38 in the code. It contains methods like 'NewEvent' to start a new event,
 39 'AddParticle' to add particle to the current event, as well as
 40 'PrintEvent' for the purpose of the debugging.  The core of the
 41 algorithm which deals with building up the MC truth event tree within
 42 the HepMC event is implemented in AddParticle method.
 43  
 44 The AddParticle method is called with the following arguments:
 45 four-momentum, production position and 'end' position of the particle,
 46 PDG code of the particle, as well as the particle ID (unique identifier,
 47 as we will see later, corresponding to Geant4 TrackID) and the ID of
 48 the mother. Finally, there is a boolean flag specifying whether the
 49 direct mother of the given particle has been stored, or not.
 50  
 51 The first step, which always takes place, is to instanciate a new
 52 HepMC::GenParticle with the barcode corresponding to particle ID, as
 53 well as to instanciate a new HepMC::GenVertex which will represent the
 54 'end' vertex of the particle. The barcode of the 'end vertex' is equal
 55 to minus the barcode of the particle.
 56  
 57 We can now distinguish several cases:
 58  
 59 1) the particle is a primary in the Geant4 language, i.e. its
 60    mother ID is 0
 61  
 62    This is the simplest case, we just instanciate a new 'primary'
 63    (without any incoming particles) GenVertex, we add to it the
 64    particle and we put it all in the event. Additionally we store the
 65    ID of the particle in a special vector, where all the IDs of
 66    primary particles will be stored, allowing quick access to each of
 67    the main 'branches' of the event. We return from the method.
 68  
 69 2) the particle is not a primary
 70 
 71    We use the 'event->barcode_to_particle(motherID)' method to get the
 72    pointer to its mother.
 73     
 74    We check if the 'end vertex' of the mother corresponds to the
 75    'production vertex' of the particle in question.
 76  
 77    2.1) If the two vertices do match, we attach the new particle to
 78         the 'end vertex' of the mother. We return from the method.
 79  
 80    2.2) If the two vertices do not match, i.e. the new particle is not
 81         a product of the 'end vertex' of the mother particle, we can
 82         have two cases:
 83                 
 84         2.2.1) The boolean flag says that the direct mother of the
 85                particle has _not_ been stored. This means that the
 86                particle has been 'adopted' by one of its ancestors, or
 87                in other words, the mother ID of the particle does not
 88                correspond to its direct mother (so clearly the
 89                vertices cannot match). This for instance could happen
 90                if we decided not to store gamma coming from pi0 decay
 91                but did decide to store e+/- coming from the gamma
 92                conversion (so the gamma between pi0 and e+/- was
 93                missing). In such a case we instanciate (or use one of
 94                the existing ones, if vertices match) a 'dummy'
 95                particle (with pdg = -999999) which then acts as the
 96                link between the 'adopted' particle and the
 97                (non-direct) mother. In such a way, the navigability up
 98                in the event is still possible, but in the same time,
 99                we can clearly see that the link is not a direct
100                one. We return from the method.
101  
102         2.2.2) The boolean flag says that direct mother of the
103                particle _has_ been stored. Taking into account that
104                the vertices do not match, it can mean only one
105                thing. The new particle has been produced 'on the
106                flight', i.e. somewhere 'before' the 'end vertex' of
107                the mother. This can be the case, for instace, for
108                delta electrons, bremsstrahlung gammas, etc.  In such a
109                situation, we 'split' the mother particle in two
110                particles and create a new vertex from which the
111                secondary will be going out. The complication, however,
112                arises when we have more than one generated 'on the
113                flight' particle attached to the same mother. In such a
114                case, for each secondary we need to locate the right
115                'segment' of the mother particle (i.e. we need to find
116                between which two vertices we need to add a new
117                one). To keep track of those segmentations we introduce
118                a map where each particle ID we map into the number of
119                existing segments (in the normal case one). Each new
120                'segment' gets barcode equal to the barcode of the
121                original particle + N*10000000, where N is the segment
122                number. In such a way, one can easily follow the
123                'segmentation' (if any) of each particle.  We return
124                from the method.
125  
126 This concludes the description of MCTruthManager. The MCTruthConfig
127 class is a collection of criteria (minimal energy, PDG, creator
128 process, etc) that we want to apply when deciding whether to store or
129 not given particle. These values are used by the
130 'MCTruthTrackingAction' which we describe below. This class can
131 certainly be extended with other members.
132  
133 The actual Geant4-dependent part of the MCTruth handling machinery
134 consists of a few 'G4 user actions' as well as an implementation of
135 G4VUserTrackInformation. The later one is, for the moment, used only
136 to store one boolean flag indicating whether the direct mother of the
137 given track has been stored or not.
138  
139 The first user action is MCTruthEventAction which is only reponsible
140 for calling MCTruthManager::GetInstance()->NewEvent() at the beginning
141 of each event. It can also be used for printing out events for the
142 purpose of debugging.
143  
144 The actual 'decision making' concerning which particle to store is
145 done in MCTruthTrackingAction. At the end of each track the method
146 trackToBeStored(track) is called to check for various characteristics
147 of the particle. These, for instance can be energy, particle ID,
148 creator process, etc.
149  
150 If the particle satisfies the conditions the
151 MCTruthManager::GetInstance()->AddParticle is called and all the
152 procedure described above is performed. The important element here is
153 that the Geant4 TrackID is used as the unique particle ID in
154 MCTruthManager and eventually as the barcode of the
155 HepMC::GenParticle.
156  
157 If the particle does not qualify to be stored, there are two actions
158 performed. First the 'ParentID' of the _daughters_ is set to the
159 'ParentID' of the currenly processed particle. In other words, the
160 'ParentID' of the daughters is set to the ID of the last stored
161 particle. Second, the 'directParent' flag from MCTruthTrackInformation
162 of the __daughters__ is set to FALSE. In such a way, one is still able
163 to navigate up in the event (to get the ancestors of the particle),
164 but in the same time, the particle is flagged as 'not having direct
165 parent'.