| Geant4 Cross Reference |
1 ---------------------------------------------- 1 -------------------------------------------------------------------
2 2
3 ========================================= 3 =========================================================
4 Geant4 - an Object-Oriented Toolkit for S 4 Geant4 - an Object-Oriented Toolkit for Simulation in HEP
5 ========================================= 5 =========================================================
6 6
7 Example HGCal_testbeam 7 Example HGCal_testbeam
8 ---------------------- 8 ----------------------
9 9
10 This example is based on the Geant4 standalon 10 This example is based on the Geant4 standalone application developed
11 by Thorben Quast for the CMS HGCal studies: 11 by Thorben Quast for the CMS HGCal studies:
12 https://github.com/ThorbenQuast/HGCal_TB_Gean 12 https://github.com/ThorbenQuast/HGCal_TB_Geant4.
13 13
14 The goal of this example is to demonstrate a 14 The goal of this example is to demonstrate a test beam setup used
15 in HEP experiments, and as a base for the val 15 in HEP experiments, and as a base for the validation studies and
16 comparison with experiment data. 16 comparison with experiment data.
17 17
18 It presents a test beam setup used in the HGC 18 It presents a test beam setup used in the HGCal studies in October
19 2018. It can be easily extended to other conf 19 2018. It can be easily extended to other configurations.
20 20
21 Details on the High Granularity Calorimeter ( 21 Details on the High Granularity Calorimeter (HGCal) can be found
22 i.a. in the Technical Design Report: 22 i.a. in the Technical Design Report:
23 https://cds.cern.ch/record/2293646/files/CMS- 23 https://cds.cern.ch/record/2293646/files/CMS-TDR-019.pdf
24 24
25 1. Detector description 25 1. Detector description
26 ----------------------- 26 -----------------------
27 27
28 Detector construction in this example assumes 28 Detector construction in this example assumes that the setup is
29 constructed with different elements placed on 29 constructed with different elements placed one behind another along
30 z axis (beam axis). 30 z axis (beam axis).
31 There are 3 configurations user can choose fr 31 There are 3 configurations user can choose from, and could be set
32 with UI command: 32 with UI command:
33 33
34 /HGCalTestbeam/setup/configuration <ID> 34 /HGCalTestbeam/setup/configuration <ID>
35 35
36 where <ID> by default is equal to 0, which me 36 where <ID> by default is equal to 0, which means the HGCal testbeam
37 setup used in October 2018. 37 setup used in October 2018.
38 <ID> 1 builds the same calorimeter setup, but 38 <ID> 1 builds the same calorimeter setup, but places in front of it
39 several beamline elements. 39 several beamline elements.
40 <ID> 2 builds a very simplistic test configur 40 <ID> 2 builds a very simplistic test configuration.
41 41
42 Whenever a silicon wafer or SiPM is placed in 42 Whenever a silicon wafer or SiPM is placed in the detector, a sensitive
43 volume is attached to it, and will be used to 43 volume is attached to it, and will be used to collect signal.
44 44
45 Silicon wafer is divided into cells (pixels), 45 Silicon wafer is divided into cells (pixels), and each individual pixel
46 can collect signal. 46 can collect signal.
47 47
48 In order to change the maximum step size allo 48 In order to change the maximum step size allowed in silicon pixels:
49 49
50 /HGCalTestbeam/setup/stepSilicon <STEP> 50 /HGCalTestbeam/setup/stepSilicon <STEP>
51 51
52 where <STEP> is value of the max step size in 52 where <STEP> is value of the max step size in micrometres. By default
53 <STEP> is equal to 30 um. 53 <STEP> is equal to 30 um.
54 54
55 2. Signal 55 2. Signal
56 --------- 56 ---------
57 57
58 Energy deposited within silicon pixels and Si 58 Energy deposited within silicon pixels and SiPMs is registered in the
59 sensitive detectors. Each deposit is added in 59 sensitive detectors. Each deposit is added individually to the vector
60 of hits, in order to allow the digitisation. 60 of hits, in order to allow the digitisation.
61 61
62 Digitisation is performed at the end of the e 62 Digitisation is performed at the end of the event. It accumulates the
63 energy deposits within pixels, taking into ac 63 energy deposits within pixels, taking into account the time cut on the
64 arrival of signal (global time of energy depo 64 arrival of signal (global time of energy deposit). By default no time
65 cut is applied which means all the deposits a 65 cut is applied which means all the deposits are counted. It can be set
66 using UI command: 66 using UI command:
67 67
68 /HGCalTestbeam/hits/timeCut <TIME> 68 /HGCalTestbeam/hits/timeCut <TIME>
69 69
70 where <TIME> is the maximum global time of th 70 where <TIME> is the maximum global time of the energy deposit that
71 would be counted into the signal within the p 71 would be counted into the signal within the pixel.
72 72
73 Another hit parameter is TOA (time of arrival 73 Another hit parameter is TOA (time of arrival) which is calculated
74 as time of the energy deposit which added to 74 as time of the energy deposit which added to the digitised pixel energy
75 exceeds the threshold. By default the thresho 75 exceeds the threshold. By default the threshold is equal to 0, which
76 means that any hit will exceed the value, so 76 means that any hit will exceed the value, so TOA of pixel equals to
77 the time of the first energy deposit. It can 77 the time of the first energy deposit. It can be set using UI command:
78 78
79 /HGCalTestbeam/hits/toaThreshold <ENERGY_THRE 79 /HGCalTestbeam/hits/toaThreshold <ENERGY_THRESHOLD>
80 80
81 where <ENERGY_THRESHOLD> indicates the thresh 81 where <ENERGY_THRESHOLD> indicates the threshold the sum of energy
82 needs to exceed to be counted as time of arri 82 needs to exceed to be counted as time of arrival.
83 83
84 Additionally, for silicon pixels, time of the 84 Additionally, for silicon pixels, time of the last energy deposit
85 (within the time window) is recorded. 85 (within the time window) is recorded.
86 86
87 3. Output 87 3. Output
88 --------- 88 ---------
89 89
90 Output with event signal is stored in ntuple 90 Output with event signal is stored in ntuple and saved to a ROOT file.
91 Its name can be set with UI command: 91 Its name can be set with UI command:
92 92
93 /HGCalTestbeam/output/file <NAME> 93 /HGCalTestbeam/output/file <NAME>
94 94
95 Created TTree "hits" contains following branc 95 Created TTree "hits" contains following branches:
96 96
97 +---------------------------------+----------- 97 +---------------------------------+-----------------+------+-------------------------------------------+
98 | Branch | Type 98 | Branch | Type | Unit | Description |
99 +---------------------------------+----------- 99 +---------------------------------+-----------------+------+-------------------------------------------+
100 | event | int 100 | event | int | - | |
101 | pdgID | vector<int 101 | pdgID | vector<int> | - | PDG code of primary particles |
102 | beamEnergy | vector<dou 102 | beamEnergy | vector<double> | GeV | initial energy of primaries |
103 | beamX_cm | vector<dou 103 | beamX_cm | vector<double> | cm | initial X position of primaries |
104 | beamY_cm | vector<dou 104 | beamY_cm | vector<double> | cm | initial Y position of primaries |
105 | beamZ_cm | vector<dou 105 | beamZ_cm | vector<double> | cm | initial Z position of primaries |
106 | siliconHits_ID | vector<int 106 | siliconHits_ID | vector<int> | - | ID of hits in Si (=1e3*waferID+cellID) |
107 | siliconHits_x_cm | vector<dou 107 | siliconHits_x_cm | vector<double> | cm | X position of Si pixel |
108 | siliconHits_y_cm | vector<dou 108 | siliconHits_y_cm | vector<double> | cm | Y position of Si pixel |
109 | siliconHits_z_cm | vector<dou 109 | siliconHits_z_cm | vector<double> | cm | Z position of Si pixel |
110 | siliconHits_Edep_keV | vector<dou 110 | siliconHits_Edep_keV | vector<double> | keV | energy deposited within Si pixel |
111 | siliconHits_EdepNonIonizing_keV | vector<dou 111 | siliconHits_EdepNonIonizing_keV | vector<double> | keV | non-ionizing energy deposit (Si) |
112 | siliconHits_TOA_ns | vector<dou 112 | siliconHits_TOA_ns | vector<double> | ns | time of arrival for Si pixel |
113 | siliconHits_TOA_last_ns | vector<dou 113 | siliconHits_TOA_last_ns | vector<double> | ns | time of last arrival for Si pixel |
114 | siliconHits_type | vector<int 114 | siliconHits_type | vector<int> | - | hit type for Si pixel (=0) |
115 | SiPMHits_ID | vector<int 115 | SiPMHits_ID | vector<int> | - | ID of hits in SiPM (=1e3*sensorID+cellID) |
116 | SiPMHits_x_cm | vector<dou 116 | SiPMHits_x_cm | vector<double> | cm | X position of SiPM |
117 | SiPMHits_y_cm | vector<dou 117 | SiPMHits_y_cm | vector<double> | cm | Y position of SiPM |
118 | SiPMHits_z_cm | vector<dou 118 | SiPMHits_z_cm | vector<double> | cm | Z position of SiPM |
119 | SiPMHits_Edep_keV | vector<dou 119 | SiPMHits_Edep_keV | vector<double> | keV | energy deposited within SiPM |
120 | SiPMHits_EdepNonIonizing_keV | vector<dou 120 | SiPMHits_EdepNonIonizing_keV | vector<double> | keV | non-ionizing energy deposit (SiPM) |
121 | SiPMHits_TOA_ns | vector<dou 121 | SiPMHits_TOA_ns | vector<double> | ns | time of arrival for SiPM |
122 | SiPMHits_type | vector<int 122 | SiPMHits_type | vector<int> | - | hit type for SiPM (= 1) |
123 | signalSum_HGCAL_GeV | double 123 | signalSum_HGCAL_GeV | double | GeV | sum of energy deposited in Si pixels |
124 | COGZ_HGCAL_cm | double 124 | COGZ_HGCAL_cm | double | cm | energy-weighted shower depth in z |
125 | NHits_HGCAL | int 125 | NHits_HGCAL | int | - | number of Si pixel hits |
126 | signalSum_AHCAL_GeV | double 126 | signalSum_AHCAL_GeV | double | GeV | sum of energy deposited in SiPMs |
127 | COGZ_AHCAL_cm | double 127 | COGZ_AHCAL_cm | double | cm | energy-weighted shower depth in z |
128 | NHits_AHCAL | int 128 | NHits_AHCAL | int | - | number of SiPM hits |
129 +---------------------------------+----------- 129 +---------------------------------+-----------------+------+-------------------------------------------+
130 130
131 4. Primary particle generator 131 4. Primary particle generator
132 ----------------------------- 132 -----------------------------
133 133
134 Particle gun is used as a default primary par 134 Particle gun is used as a default primary particle generator.
135 It can be controlled with standard UI command 135 It can be controlled with standard UI commands (/gun/) and with
136 additional ones introduced by the messenger: 136 additional ones introduced by the messenger:
137 137
138 /HGCalTestbeam/generator/momentumSpread <VALU 138 /HGCalTestbeam/generator/momentumSpread <VALUE>
139 to change constant particle energy to Gaussia 139 to change constant particle energy to Gaussian distribution with
140 sigma expressed in units of the initial energ 140 sigma expressed in units of the initial energy (e.g. <VALUE>=0.05
141 means sigma of 0.05 * E). By default it equal 141 means sigma of 0.05 * E). By default it equals to 0 and constant
142 energy value is used. 142 energy value is used.
143 143
144 /HGCalTestbeam/generator/beamSpread <none/Gau 144 /HGCalTestbeam/generator/beamSpread <none/Gaussian/flat>
145 to define type of beam position spread. By de 145 to define type of beam position spread. By default none is used.
146 146
147 /HGCalTestbeam/generator/beamSpreadX <SIZE> 147 /HGCalTestbeam/generator/beamSpreadX <SIZE>
148 to define size of beam spread along x axis. I 148 to define size of beam spread along x axis. It is sigma of a
149 Gaussian distribution, or half-width of a fla 149 Gaussian distribution, or half-width of a flat distribution.
150 150
151 /HGCalTestbeam/generator/beamSpreadY <SIZE> 151 /HGCalTestbeam/generator/beamSpreadY <SIZE>
152 to define size of beam spread along y axis. I 152 to define size of beam spread along y axis. It is sigma of a
153 Gaussian distribution, or half-width of a fla 153 Gaussian distribution, or half-width of a flat distribution.
154 154
155 /HGCalTestbeam/generator/fBeamZ0 <POSITION> 155 /HGCalTestbeam/generator/fBeamZ0 <POSITION>
156 to define beam position along z axis. By defa 156 to define beam position along z axis. By default edge of the
157 world volume is used. 157 world volume is used.
158 158
159 Additionally, if installation was done with R 159 Additionally, if installation was done with ROOT package (CMake
160 was able to locate it), an option of input re 160 was able to locate it), an option of input read from the ROOT file
161 is enabled. It can be activated with 161 is enabled. It can be activated with
162 162
163 /HGCalTestbeam/generator/fReadInputFile true 163 /HGCalTestbeam/generator/fReadInputFile true
164 164
165 /HGCalTestbeam/generator/fPathInputFile <FILE 165 /HGCalTestbeam/generator/fPathInputFile <FILE>
166 sets the path to the input file. 166 sets the path to the input file.
167 167
168 /HGCalTestbeam/generator/startFromEvent <N> 168 /HGCalTestbeam/generator/startFromEvent <N>
169 allows to start simulation from Nth event. 169 allows to start simulation from Nth event.
170 170
171 Please note that in current implementation in 171 Please note that in current implementation input from file needs to be
172 executed in a non-multithreaded mode (or with 172 executed in a non-multithreaded mode (or with 1 thread).
173 173
174 Input file needs to have following structure: 174 Input file needs to have following structure:
175 - TDirectory "VirtualDetector" 175 - TDirectory "VirtualDetector"
176 - TNtuple "HGCAL" with branches: 176 - TNtuple "HGCAL" with branches:
177 +---------+-------+------+--------------- 177 +---------+-------+------+-------------------------------+
178 | Branch | Type | Unit | Descr 178 | Branch | Type | Unit | Description |
179 +---------+-------+------+--------------- 179 +---------+-------+------+-------------------------------+
180 | EventID | float | - | ID of event 180 | EventID | float | - | ID of event |
181 | PDGid | float | - | Particle type 181 | PDGid | float | - | Particle type (PDG code) |
182 | x | float | mm | Initial X posi 182 | x | float | mm | Initial X position |
183 | y | float | mm | Initial Y posi 183 | y | float | mm | Initial Y position |
184 | Px | float | MeV | Initial moment 184 | Px | float | MeV | Initial momentum along X axis |
185 | Py | float | MeV | Initial moment 185 | Py | float | MeV | Initial momentum along Y axis |
186 | Pz | float | MeV | Initial moment 186 | Pz | float | MeV | Initial momentum along Z axis |
187 +---------+-------+------+--------------- 187 +---------+-------+------+-------------------------------+
188 188
189 Several particles may belong to the same even 189 Several particles may belong to the same event, in which case all
190 of them are read from the input file. 190 of them are read from the input file.
191 Z position is set to Z position of the entran 191 Z position is set to Z position of the entrance of the HGCal detector.
192 192
193 5. How to run the example 193 5. How to run the example
194 ------------------------- 194 -------------------------
195 195
196 Example can be run in interactive mode, with 196 Example can be run in interactive mode, with visualisation:
197 197
198 ./HGCal_testbeam 198 ./HGCal_testbeam
199 199
200 It will execute init_vis.mac and vis.mac. 200 It will execute init_vis.mac and vis.mac.
201 201
202 To run in a batch mode, specify the path to t 202 To run in a batch mode, specify the path to the macro:
203 203
204 ./HGCal_testbeam run.mac 204 ./HGCal_testbeam run.mac
205 205
206 which will run 10 single-electron events, wit 206 which will run 10 single-electron events, with beam energy of 30 GeV.
207 The beam position is smeared with Gaussian wi 207 The beam position is smeared with Gaussian with x/y sigma of 1.5 cm.
208 The momentum is smeared with Gaussian with si 208 The momentum is smeared with Gaussian with sigma of 5% (2.5 GeV).
209 Z beam position is set to -1 m. 209 Z beam position is set to -1 m.
210 Maximum step size in Si pixel is 20 um. 210 Maximum step size in Si pixel is 20 um.
211 The name of the created file is output_eM_sme 211 The name of the created file is output_eM_smeared_30GeV_10events.root.
212 212
213 6. Additional settings 213 6. Additional settings
214 ---------------------- 214 ----------------------
215 215
216 6.1. Particle input from ROOT file 216 6.1. Particle input from ROOT file
217 ---------------------------------- 217 ----------------------------------
218 218
219 If ROOT is found by CMake, it allows to use R 219 If ROOT is found by CMake, it allows to use ROOT file as the input to
220 the primary generator. See more in the descri 220 the primary generator. See more in the description of "4. Primary
221 particle generator". 221 particle generator".
222 222
223 ./HGCal_testbeam readFromFile.mac 223 ./HGCal_testbeam readFromFile.mac
224 224
225 Macro readFromFile.mac can be used but name 225 Macro readFromFile.mac can be used but name of the input file should
226 be specified (not provided with the example) 226 be specified (not provided with the example). This mode is meant to
227 be used in the validation with experimental 227 be used in the validation with experimental data with geant-val.