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 ]
1 -------------------------------------------------------------------
2 -------------------------------------------------------------------
3
4 =========================================================
5 Geant4 - Composite calorimeter example
6 =========================================================
7
8 README
9 ---------------------
10
11 CompositeCalorimeter is an example of a test-beam simulation used
12 by the CMS Collaboration to validate Geant4 against real data taken
13 (in 1996) in a CMS Hadron calorimeter test-beam.
14 The name "Composite" for this example emphasizes that, although the
15 test-beam had the goal of studying the hadronic calorimeter response,
16 part of the data was taken with the presence of the electromagnetic
17 crystal calorimeter in front of the hadronic calorimeter, to better
18 reproduce the situation as in the real CMS experiment.
19 The geometry of the simulation has been setup in such a way to allow
20 very easily, at run time (therefore without need of changing any code;
21 see below for the details) the inclusion or exclusion of the
22 electromagnetic calorimeter part.
23 Although some important aspects, for a detailed comparison between
24 test-beam data and simulation, like beam profile, noise, and digitization,
25 have been omitted here (to avoid too many technical details),
26 nevertheless, this example is able to reproduce the main features of
27 most of the relevant observables as measured in the real test-beam.
28 The output of this example consists of a set of histograms
29 and one ntuple which are stored on a ROOT file (default).
30 In our opinion, the most original "lesson" which is offered by this
31 advanced example for the Geant4 user is to show how the Geometry and
32 the Sensitive/Hit part of the simulation is treated in a big experiment.
33 Although the details of how this is done vary from experiment to
34 experiment (it is worth, for instance, to compare with the Atlas-based
35 advanced example lAr_calorimeter), the main driving needs and goals
36 are quite general: to have consistency, but avoiding duplications
37 and couplings as much as possibile, between Simulation, Reconstruction,
38 and Visualization. Notice that the solution offered in this example
39 by CMS could appear "overdone" for the sake of simulating only a
40 relatively simple test-beam setup; but it should be kept in mind
41 that the same approach is used also for the full CMS detector
42 simulation, as well as for any subdetector.
43
44
45 1. Setting up the environment variables
46 ---------------------------------------
47
48 The user should first setup, as "usual", the Geant4 environmental
49 variables (e.g. the script produced by cmake)
50 Then the specific setup for this example should be run:
51
52 > source envExample.csh in the case of C-shell
53 or
54 > . envExample.sh in the case of bash-shell
55
56 The analysis part is based on the native g4analysis tools. As default
57 the output is a ROOT file. This can be changed to XML by changing the G4AnalysisManager default file type in CCalRunAction::BeginOfRunAction().
58
59
60 2. Sample run
61 -------------
62
63 Once the environmental variables are setup, you can get the executable
64 CompositeCalorimeter
65 by configuring with cmake and then running the compiler.
66 Then, you can execute it using the Geant4 macro command input file test.g4mac
67 as follows:
68
69 > ./CompositeCalorimeter test.g4mac
70
71 which simulate a few events, each being a 100 GeV pi- incident on the
72 electromagnetic crystal calorimeter followed by the hadronic calorimeter,
73 without magnetic field.
74 The output is the ROOT file "ccal.root" .
75 See part "8. Analysis / Histogramming" below for more details on the
76 content of that file.
77 If you run instead:
78
79 > ./CompositeCalorimeter
80
81 after having setup the Geant4 visualization variables and the PATH,
82 you can visualize the geometry of the apparatus, and also see some
83 events. Similarly, you can get a very simple graphical user interface
84 that allows to select the particle type, its energy, and the number
85 of events (between a limited number of possibilities).
86 For more details, see part "9. Visualization / GUI".
87
88
89 3. Detector description
90 -----------------------
91
92 Let's start with a brief description of the test-beam setup.
93
94 There are two possible configurations:
95 i) HCAL only, that is only the hadronic calorimeter is present;
96 ii) ECAL+HCAL, that is the electromagnetic calorimeter (ECAL)
97 is placed in front of the hadronic calorimeter.
98 ECAL is made of 23 cm long PbWO4 crystals (corresponding to about
99 25.8 radiation lengths, and 1.1 interaction lengths); for the
100 test beam a 7 x 7 = 49 matrix of crystals is used.
101 HCAL is a sampling calorimeter, with plastic scintillator as sensitive
102 part and copper as absorber. 28 scintillator plates were used with
103 absorber of varying thickness in between, and also varying thickness
104 and type of scintillator. More precisely:
105 --- layer 1: 2 cm of Copper
106 --- layer 2 to 7: 4 cm of Copper
107 --- layer 8 to 21: 6 cm of Copper
108 --- layer 22 to 27: 8 cm of Copper
109 For the scintillators: 2 mm passive Plastic; 4 mm active Plastic;
110 1 mm passive Plastic.
111 The total length of HCAL consists of 152 cm of Copper plus 189 mm of Plastic.
112 The dimension orthogonal to the beam direction is 64 cm x 64 cm.
113 The ECAL and HCAL considered here are prototypes for the Central and
114 Endcap calorimeters of the CMS detector (which covers the rapidity
115 region |eta| < 3.0 ; CMS has also a Forward calorimeter, which covers
116 the region 3.0 < |eta| < 5.0, but this part was not considered in
117 this test-beam setup). Notice, however, that there are more layers
118 (28 instead of 19 in the Barrel or 18 in the Endcap) of HCAL in the
119 test-beam setup than in the real CMS detector, in order to study
120 energy containment. Therefore, the ECAL+HCAL in the test-beam amounts
121 to more than 11 radiation lengths as for the real CMS detector (the
122 19 layers of the Barrel have each 6 cm of absorber, whereas the
123 18 layers of the Endcap have each 6.6 cm of absorber, so that the
124 number of interaction lengths are rougly the same).
125 Five values of the magnetic field (parallel to the face of the scintillators)
126 have been considered in the test-beam: 0.0 , 0.375 , 0.75 , 1.50 , 3.0 Tesla.
127
128 In order to set the magnetic field, you have to edit the file
129 dataglobal/fmap.tb96
130 and change the first number (which appears in the third line of
131 that file, on the first column; the unit being Tesla):
132 #. Field map
133 *DO FLDM
134 0.0 9 652.0
135 for example, if you want a magnetic field of 3.0 Tesla the last
136 line must be set as follows (the magnetic field unity is kilo Gauss).
137 30.0 9 652.0
138
139 In order to deactivate either the ECAL or the HCAL, it is enough
140 to comment out the corresponding line in the file g4testbeamhcal96.conf,
141 using "#" as the comment character. For instance, to have only the HCAL
142 without ECAL:
143 "HcalTB96" "tbhcal96" 1
144 #"CrystalMatrixModule" "tbhcal96xtal" 1
145
146
147 In this test-beam setup, at the back of ECAL, there is also some
148 material for support and readout, which has been considered in the
149 simulation. For the HCAL, only the fibres are close to the test-beam,
150 and because they have the same composition as the scintillators
151 they are adequately represented in the simulation; the remaining
152 of the readout, including the photomultipliers, are in readout boxes
153 far away from the HCAL, and hence are not present in the simulation.
154
155 Let's summarizes now the geometry description of the simulation.
156 As said in the introduction, this part is the most original and
157 important of this example, but it is quite complex and can be fully
158 appreciated only in the context of the CMS software framework, in
159 particular in the relation between Simulation, Reconstruction, and
160 Visualization. Therefore we limit ourself to only few considerations,
161 pointing to the internal CMS documentation for more details.
162
163 --- In order to share the same geometrical and physical information
164 about CMS between Simulation, Reconstruction, and Visualization,
165 avoiding inconsistencies, duplications, and unnecessary dependecies,
166 all these information is store, once for all, in common databases
167 (typically in XML format), instead of putting them inside C++ classes,
168 as usually done in simpler detector descriptions (in most of the
169 the Geant4 examples, novice or advanced, the geometry information
170 is kept inside the concrete class which inherits from
171 G4VUserDetectorConstruction). For simplicity, in this example,
172 these "databases" are nothing more than ASCII files:
173
174 datageom/ : tbhcal96.geom, tbhcal96hcal.geom, tbhcal96xtal.geom
175 store the information about the experimental Hall,
176 the HCAL, and the ECAL, respectively.
177
178 dataconf/ : g4testbeamhcal96.conf, testbeamhcal96.conf
179 store the information about which configuration
180 (HCAL only, or ECAL+HACL) is considered, in the
181 Simulation and Reconstruction, respectively.
182
183 dataglobal/ : fmap.tb96, material.cms, rotation.cms
184 The first one is the magnetic field map (how the
185 intensity of the magnetic field, in the direction
186 orthogonal to the beam direction, varies along
187 the beam axis). The second one, material.cms,
188 keeps the full collection of all materials used in
189 the CMS detector (not only in the calorimeters,
190 although we are simulating only them in this example!).
191 The third one, rotation.cms, collects a set of useful
192 rotation parameters (angles).
193
194 datavis/ : tbhcal96.vis, tbhcal96hcal.vis, tbhcal96xtal.vis
195 visualization information for, respectively, the
196 experimental Hall, HCAL, and ECAL.
197
198 --- In order to allow an high degree of flexibility, at the geometry
199 level the user can choose which subsystem of the detector setup
200 should be simulated and can activate or deactivate the sensitive
201 parts, subsystem by subsystem. This can be done at run time,
202 by modifying one of the above database information, without need
203 of putting the hands on the code, recompiling, etc.
204
205 --- There are two "parallel geometry factories": one described by "core"
206 classes, which are independent from the Simulation (and therefore
207 can be used, for instance, by the Reconstruction); and one which
208 is specific of the Simulation. In the latter case (Geant4 side of
209 the geometry model), all the geometry factories are derived from the
210 base class CCalG4Albe. Furthermore, using double inheritance, each
211 of them derives also from the counterpart in the "core" hierarchy.
212 The design of the CCalG4Able class helps a modular approach and easy
213 interchanging at the level of subdetectors, allowing a straightforward
214 transition from the simulation of the entire CMS detector to that of
215 just a part of it, or to a test-beam geometry, as indeed in this example.
216 Of course this modular, flexible, and general approach does not come
217 for free: the price to pay here is its complexity, which would be
218 otherwise unjustified if we limited ourself to the pure simulation
219 of a relatively simple test-beam setup.
220
221 --- See "10. Classes Overview" below for a schematic summary of the
222 various classes involved in the Geometry description of this example.
223
224
225 4. Physics processes
226 --------------------
227
228 The factory physics list is used, therefore the choice of the physics list
229 is steered by the environmental variable PHYSLIST.
230 (Note: if this environmental variable is not set, the default physics list
231 which is used is FTFP_BERT).
232
233
234 5. Particle Generator
235 ---------------------
236
237 The 1996 test-beam has been taken with the following particles:
238 --- 225 GeV muons (for calibration)
239 --- 10 to 300 GeV pions
240 --- 10 to 300 GeV electrons
241 therefore the standard Geant4 Particle Gun has been used as primary
242 generator. Notice that, for the sake of keeping the example not too
243 complicated, the proper simulation of the beam profile and
244 beam contamination have been neglected.
245
246
247 6. Hits
248 -------
249
250 In CMS there are two groups of hits: Tracker-like and Calorimeter-like.
251 Only the latter one appears in this example.
252 For the same reasons, as seen for the Geometry, of consistency without
253 duplication of information and unnecessary coupling between Simulation,
254 Reconstruction, and Visualization, the simulation calorimeter hit class,
255 CCalG4Hit, doubly inherits from the common Geant4 abstract class for
256 all hits, G4VHit, and from the "core" (i.e. simulation independent)
257 CMS calorimeter hit class, CCalHit.
258 A new Hit object is created
259 - for each new particle entering the calorimeter;
260 - for each detector unit (i.e cristal or fiber or scintillator layer);
261 - for each nanosecond of the shower development;
262 The information stored in each CCalHit object is the following:
263 - Entry : local coordinates of the entrance point of the particle
264 in the unit where the shower starts;
265 - the TrackID : Identification number of the incident particle;
266 - the IncidentEnergy : kinetic energy of that incident particle;
267 - the UnitID : the identification number of the detector unit
268 (crystal, or fiber, or scintillator layer);
269 - the TimeSlice : the time interval, in nanoseconds, in which the
270 hit has been created;
271 - the EnergyDeposit : the energy deposit in this hit.
272 Notice that all hit objects created for a given shower have the same
273 values for the first three pieces of information.
274
275
276 No Noise and Digitization
277 --------------------------
278
279 In order to keep the complexity of this example to a reasonable
280 level, both noise and digitization effects have not been included.
281
282
283 7. User Actions
284 ----------------
285
286 In this example. there have been used the following User Actions:
287
288 --- G4UserRunAction (the derived, concrete class is CCalRunAction):
289 it is used to invoke the Analysis object at the beginning of
290 the Run, to instantiate it and passing it the Run number, and
291 at the end of the Run, to inform it that the Run is finished
292 and therefore the histograms, ntuples, etc. must be closed.
293
294 --- G4UserEventAction (the derived, concrete class is CCalEndOfEventAction):
295 it is used to examine, at the end of the Event, all collected
296 (calorimeter) hits, extract the various observables which are
297 interesting (to the goal of understanding things like: the effect
298 of magnetic field on scintiallator; choice of the absorber
299 thickness by optimizing resolution versus containment; impact of
300 the absorber depth in the energy caontainment; electromagnetic
301 calorimeter contribution in the electron - pion separation; etc.)
302 and finally call the analysis object to store such selected
303 information on histograms and/or in the ntuple.
304 The name of the class "CCalEndOfEventAction" is motivated by the
305 fact that at the beginning of the Event nothing is done.
306
307 --- G4UserSteppingAction (the derived, concrete class is CCalSteppingAction):
308 it is used to extract some "unphysical" information (that is not
309 experimentally measurable, although interesting for a better
310 understanding of the shower development), namely the lateral profile
311 and the deposit as a function of the time (see "8.Analysis/Histogramming
312 for more details"), which is available only from simulation, and then,
313 at the end of Event, the analysis object is invoked to store such
314 information on histograms.
315 Please notice that the stepping action is not used to create hits.
316
317 --- G4UserStackingAction (the derived, concrete class is CCalStackingAction):
318 it is used to ensure that the same track ID of the particle
319 originating a shower appears in all hits (calorimeter hit objects
320 of class CCalHit) of the shower, in any calorimeter part.
321
322
323 8. Analysis / Histogramming
324 ----------------------------
325
326 The analysis part of CompositeCalorimeter is kept in class CCalAnalysis,
327 and is based on the g4tool interfaces.
328 Both the histograms and the ntuple are saved at the end of the run in the
329 ROOT file "ccal.root" (default: this can be changed to XML or to other
330 formats supported by the g4analysis tools).
331 Please note that in a multiple run session, the last run always overrides
332 the output file.
333 What the histograms and the variables of the ntuple represent is
334 explained below:
335
336 Histograms h100 - h127 : energy deposit (in GeV) in the sensitive part
337 (plastic scintillator layer) of one Hadronic
338 calorimeter module (there are 28 modules, numbered
339 from 0 to 27, and the corresponding histogram has
340 ID = 100 + number of module).
341 Ntuple variables hcal0 - hcal27 : provide the same information.
342
343 Histograms h200 - h248 : energy deposit (in GeV) in one crystal
344 electromagnetic towers (there are a matrix of
345 7 x 7 = 49 towers, numbered from 0 to 48, and
346 the corresponding histogram has
347 ID = 200 + number of tower).
348 Ntuple variables ecal0 - ecal48 : provide the same information.
349
350 Histograms h300 - h339 : total energy deposit (in GeV) in any
351 electromagnetic crystal tower or hadronic module
352 (either in a sensitive or insensitive layer)
353 in one of the 40 nanosecond time slices: in other
354 words, histogram 300+I , where I = 0 - 39,
355 contains the total deposit energy between
356 I and I+1 nanoseconds after the "collision".
357 (Notice that the time window considered,
358 40 nanoseconds, is larger than the LHC
359 bunch-crossing of 25 nanoseconds.)
360
361 Histograms h400 - h469 : energy profile (in GeV), summed over all layers
362 sensitive (plastic scintillator) and insensitive
363 (copper absorber), as a function of the radial
364 distance (in centimeter) from the beam axis
365 ( ID histo = 400 + radial distance in cm ).
366
367 Histogram h4000 : total energy deposit (in GeV) in the sensitive parts
368 of either the electromagnetic or hadronic calorimeters.
369 Ntuple variable edep provides the same information.
370
371 Other ntuple variables are the following:
372 --- elab : energy (in GeV) of the incident particle.
373 --- xpos, ypos, zpos : position (in mm) from where the projectile
374 has been shot.
375 --- edec, edhc : total energy deposit (in GeV) in the sensitive
376 parts of, respectively, the electromagnetic
377 and hadronic calorimeters. Notice that their
378 sum edec+edhc coincides with edep
379
380 Notice that lateral profile (400-469) and time-slice (300-339)
381 histograms show purely Monte Carlo quantities, which cannot be
382 experimentally measured.
383 Please be careful that the range of the histograms has been chosen
384 in such a way to contain most of the entries, but only few histograms
385 fill a large fraction of that range, whereas the remaining majority
386 fill only the first few bins (corresponding to lower energy), and,
387 therefore, when plotted they look almost empty, but they are not,
388 and the results are sensible. We suggest to plot the ntuple's variables,
389 rather than the histograms, when the same information is available
390 from the ntuple.
391
392
393 9. Visualization / GUI
394 -----------------------
395
396 If you setup one of the following Geant4 environmental variables:
397 G4VIS_USE_DAWN
398 G4VIS_USE_VRML
399 G4VIS_USE_OPENGLX
400 which correspond to the use of DAWN, VRML, and OPENGLX, respectively,
401 as visualization engine of Geant4, and set properly the corresponding
402 PATH as well, it is then possible to visualize the detector and also
403 some events.
404 To do so, you have to run
405 > ./CompositeCalorimeter
406 without input file: you then see the detector; after that,
407 you can select the particle gun and its energy, in the
408 case you want something different from the the default
409 (which is a 100 GeV pi-), for example:
410 Idle> /gun/particle e-
411 Idle> /gun/energy 200 GeV
412 and then run some events, for example:
413 Idle> /run/beamOn 3
414
415 The tracks that are shown include both charged and neutral particles
416 of any momentum: if you want instead only charged, or only neutral,
417 then you have simply to edit src/CCalEndOfEventAction.cc
418 at the end of the method EndOfEventAction and uncomment the line
419 where the condition on the charge is made (it should then be
420 straighforward to eventual add some other conditions, for example
421 if you want to see only those particles that satisfy certain
422 kinematic conditions).
423
424 Rather than to specify "by hand" the type of particle gun,
425 its energy, and the number of events, it is possible to have
426 a very simple GUI (graphical user interface) from which to make
427 such choices, between a limited set of possibilities, via menus.
428 Such GUI is based on Motif XmCommand widget, but it would be
429 straightforward, eventually, to make the necessary changes
430 in order to use a different one.
431 The only thing you need to do to get the GUI is to setup
432 the following Geant4 environmental variables:
433 G4UI_BUILD_XM_SESSION=1
434 G4UI_USE_XM=1
435 Then, if you run the executable without specifying a macro file
436 (like test.g4mac):
437 > $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter
438 a window automatically pops out, with the menus where you
439 can make your selection of particle type, energy, and number
440 of events to be run.
441
442
443 10. Classes Overview
444 ---------------------
445
446 This is a schematic overview of the classes defined in this example:
447
448 CCalPrimaryGeneratorAction
449 CCalPrimaryGeneratorMessenger
450 User action for primaries generator.
451
452 CCalDetectorConstruction
453 CCalAMaterial
454 CCalDataSet
455 CCalDetector
456 CCalEcal
457 CCalEcalOrganization
458 CCalG4Able
459 CCalG4Ecal
460 CCalG4Hall
461 CCalG4Hcal
462 CCalGeometryConfiguration
463 CCalHall
464 CCalHcal
465 CCalHcalOrganization
466 CCalMagneticField
467 CCalMaterial
468 CCalMaterialFactory
469 CCalRotationMatrixFactory
470 CCalVOrganization
471 CCalVisManager
472 CCalVisualisable
473 CCaloOrganization
474 CCalutils
475 Geometry and material definitions for the detector.
476 Notice in particular that:
477 CCalHall, CCalEcal, CCalHcal derive from CCalDetector;
478 CCalG4Hall, CCalG4Ecal, CCalG4Hcal derive from the above
479 corresponding classes and from CCalG4Able;
480 CCalEcalOrganization, CCalHcalOrganization derive from
481 CCalVOrganization : each sensitive cell has an unique
482 number for detector organization (this is a software
483 ID not an hardware/electronic one).
484
485 CCalHit
486 CCalG4Hit
487 CCalG4HitCollection
488 CCalSDList
489 CCalSensAssign
490 CCalSensitiveConfiguration
491 CCalSensitiveDetectors
492 CCaloSD
493 Hit and Sensitive Detectors.
494 Notice in particular that:
495 CCalG4Hit derives from G4VHit and CCalHit;
496 CCaloSD derives from G4VSensitiveDetector.
497
498 CCalActionInitializer
499 User-action initialization.
500
501 CCalAnalysis
502 Analysis manager class.
503
504 CCalRunAction
505 User run action class.
506
507 CCalEndOfEventAction
508 User event action class.
509
510 CCalStackingAction
511 User Stacking action class.
512
513 CCalSteppingAction
514 User Stepping action class.
515
