------------------------------------------------------------------- $Id: README,v 1.12 2006/07/25 11:02:56 gcosmo Exp $ ------------------------------------------------------------------- ========================================================= Geant4 - Composite calorimeter example ========================================================= README --------------------- CompositeCalorimeter is an example of a test-beam simulation used by the CMS Collaboration to validate Geant4 against real data taken (in 1996) in a CMS Hadron calorimeter test-beam. The name "Composite" for this example emphasizes that, although the test-beam had the goal of studying the hadronic calorimeter response, part of the data was taken with the presence of the electromagnetic crystal calorimeter in front of the hadronic calorimeter, to better reproduce the situation as in the real CMS experiment. The geometry of the simulation has been setup in such a way to allow very easily, at run time (therefore without need of changing any code; see below for the details) the inclusion or exclusion of the electromagnetic calorimeter part. Although some important aspects, for a detailed comparison between test-beam data and simulation, like beam profile, noise, and digitization, have been omitted here (to avoid too many technical details), nevertheless, this example is able to reproduce the main features of most of the relevant observables as measured in the real test-beam. The output of this example, if the AIDA or Anaphe/Lizard environment has been properly setup (see below), consists of a set of histograms and one ntuple which are stored on a HBOOK file. In our opinion, the most original "lesson" which is offered by this advanced example for the Geant4 user is to show how the Geometry and the Sensitive/Hit part of the simulation is treated in a big experiment. Although the details of how this is done vary from experiment to experiment (it is worth, for instance, to compare with the Atlas-based advanced example lAr_calorimeter), the main driving needs and goals are quite general: to have consistency, but avoiding duplications and couplings as much as possibile, between Simulation, Reconstruction, and Visualization. Notice that the solution offered in this example by CMS could appear "overdone" for the sake of simulating only a relatively simple test-beam setup; but it should be kept in mind that the same approach is used also for the full CMS detector simulation, as well as for any subdetector. 1. Setting up the environment variables --------------------------------------- The user should first setup, as "usual", the Geant4 environmental variables (in particular, the variable G4ANALYSIS_USE must be set if you want to have the histograms and the ntuple). Then the specific setup for this example, including the AIDA/PI part used in the analysis, should be run: > source envExample.csh in the case of C-shell or > . envExample.sh in the case of bash-shell The analysis part is based on AIDA/PI. Please take a look to the web page: http://www.cern.ch/PI . 2. Sample run ------------- Once the environmental variables are setup, you can get the executable $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter by typing "gmake" on this directory. Then, you can execute it using the Geant4 macro command input file test.g4mac as follows: > $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter test.g4mac which simulate 10 events, each being a 100 GeV pi- incident on the electromagnetic crystal calorimeter followed by the hadronic calorimeter, without magnetic field. The output is the HBOOK file "ccal.his" , which can be seen either with Lizard (or any other AIDA-compliant package) or with Paw or Root. See part "8. Analysis / Histogramming" below for more details on the content of that file. If you run instead: > $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter after having setup the Geant4 visualization variables and the PATH, you can visualize the geometry of the apparatus, and also see some events. Similarly, you can get a very simple graphical user interface that allows to select the particle type, its energy, and the number of events (between a limited number of possibilities). For more details, see part "9. Visualization / GUI". 3. Detector description ----------------------- Let's start with a brief description of the test-beam setup. There are two possible configurations: i) HCAL only, that is only the hadronic calorimeter is present; ii) ECAL+HCAL, that is the electromagnetic calorimeter (ECAL) is placed in front of the hadronic calorimeter. ECAL is made of 23 cm long PbWO4 crystals (corresponding to about 25.8 radiation lengths, and 1.1 interaction lengths); for the test beam a 7 x 7 = 49 matrix of crystals is used. HCAL is a sampling calorimeter, with plastic scintillator as sensitive part and copper as absorber. 28 scintillator plates were used with absorber of varying thickness in between, and also varying thickness and type of scintillator. More precisely: --- layer 1: 2 cm of Copper --- layer 2 to 7: 4 cm of Copper --- layer 8 to 21: 6 cm of Copper --- layer 22 to 27: 8 cm of Copper For the scintillators: 2 mm passive Plastic; 4 mm active Plastic; 1 mm passive Plastic. The total length of HCAL consists of 152 cm of Copper plus 189 mm of Plastic. The dimension orthogonal to the beam direction is 64 cm x 64 cm. The ECAL and HCAL considered here are prototypes for the Central and Endcap calorimeters of the CMS detector (which covers the rapidity region |eta| < 3.0 ; CMS has also a Forward calorimeter, which covers the region 3.0 < |eta| < 5.0, but this part was not considered in this test-beam setup). Notice, however, that there are more layers (28 instead of 19 in the Barrel or 18 in the Endcap) of HCAL in the test-beam setup than in the real CMS detector, in order to study energy containment. Therefore, the ECAL+HCAL in the test-beam amounts to more than 11 radiation lengths as for the real CMS detector (the 19 layers of the Barrel have each 6 cm of absorber, whereas the 18 layers of the Endcap have each 6.6 cm of absorber, so that the number of interaction lengths are rougly the same). Five values of the magnetic field (parallel to the face of the scintillators) have been considered in the test-beam: 0.0 , 0.375 , 0.75 , 1.50 , 3.0 Tesla. In order to set the magnetic field, you have to edit the file dataglobal/fmap.tb96 and change the first number (which appears in the third line of that file, on the first column; the unit being Tesla): #. Field map *DO FLDM 0.0 9 652.0 for example, if you want a magnetic field of 3.0 Tesla the last line must be set as follows (the magnetic field unity is kilo Gauss). 30.0 9 652.0 The default stepper in magnetic field is G4ClassicalRK4, but other possibilities can be selected by editing the file src/CCalDetectorConstruction.cc (look at the string "***STEPPER***"). In order to deactivate either the ECAL or the HCAL, it is enough to comment out the corresponding line in the file g4testbeamhcal96.conf, using "#" as the comment character. For instance, to have only the HCAL without ECAL: "HcalTB96" "tbhcal96" 1 #"CrystalMatrixModule" "tbhcal96xtal" 1 In this test-beam setup, at the back of ECAL, there is also some material for support and readout, which has been considered in the simulation. For the HCAL, only the fibres are close to the test-beam, and because they have the same composition as the scintillators they are adequately represented in the simulation; the remaining of the readout, including the photomultipliers, are in readout boxes far away from the HCAL, and hence are not present in the simulation. Let's summarizes now the geometry description of the simulation. As said in the introduction, this part is the most original and important of this example, but it is quite complex and can be fully appreciated only in the context of the CMS software framework, in particular in the relation between Simulation, Reconstruction, and Visualization. Therefore we limit ourself to only few considerations, pointing to the internal CMS documentation for more details. --- In order to share the same geometrical and physical information about CMS between Simulation, Reconstruction, and Visualization, avoiding inconsistencies, duplications, and unnecessary dependecies, all these information is store, once for all, in common databases (typically in XML format), instead of putting them inside C++ classes, as usually done in simpler detector descriptions (in most of the the Geant4 examples, novice or advanced, the geometry information is kept inside the concrete class which inherits from G4VUserDetectorConstruction). For simplicity, in this example, these "databases" are nothing more than ASCII files: datageom/ : tbhcal96.geom, tbhcal96hcal.geom, tbhcal96xtal.geom store the information about the experimental Hall, the HCAL, and the ECAL, respectively. dataconf/ : g4testbeamhcal96.conf, testbeamhcal96.conf store the information about which configuration (HCAL only, or ECAL+HACL) is considered, in the Simulation and Reconstruction, respectively. dataglobal/ : fmap.tb96, material.cms, rotation.cms The first one is the magnetic field map (how the intensity of the magnetic field, in the direction orthogonal to the beam direction, varies along the beam axis). The second one, material.cms, keeps the full collection of all materials used in the CMS detector (not only in the calorimeters, although we are simulating only them in this example!). The third one, rotation.cms, collects a set of useful rotation parameters (angles). datavis/ : tbhcal96.vis, tbhcal96hcal.vis, tbhcal96xtal.vis visualization information for, respectively, the experimental Hall, HCAL, and ECAL. --- In order to allow an high degree of flexibility, at the geometry level the user can choose which subsystem of the detector setup should be simulated and can activate or deactivate the sensitive parts, subsystem by subsystem. This can be done at run time, by modifying one of the above database information, without need of putting the hands on the code, recompiling, etc. --- There are two "parallel geometry factories": one described by "core" classes, which are independent from the Simulation (and therefore can be used, for instance, by the Reconstruction); and one which is specific of the Simulation. In the latter case (Geant4 side of the geometry model), all the geometry factories are derived from the base class CCalG4Albe. Furthermore, using double inheritance, each of them derives also from the counterpart in the "core" hierarchy. The design of the CCalG4Able class helps a modular approach and easy interchanging at the level of subdetectors, allowing a straightforward transition from the simulation of the entire CMS detector to that of just a part of it, or to a test-beam geometry, as indeed in this example. Of course this modular, flexible, and general approach does not come for free: the price to pay here is its complexity, which would be otherwise unjustified if we limited ourself to the pure simulation of a relatively simple test-beam setup. --- See "10. Classes Overview" below for a schematic summary of the various classes involved in the Geometry description of this example. 4. Physics processes -------------------- By the default, one of the ufficial High Energy Physics List for Calorimetry, QGSC, is used in this example. However, it is very easy to use instead either LHEP or QGSP. To do so, it is enough to comment/uncomment a line in the main CompositeCalorimeter.cc : for example, if you want to use LHEP instead of the default QGSC you have to change it as follows: //***LOOKHERE*** CHOOSE THE PHYSICS LIST. runManager->SetUserInitialization(new LHEP); // LHEP // runManager->SetUserInitialization(new QGSP); // QGSP // runManager->SetUserInitialization(new QGSC); // QGSC //***endLOOKHERE*** Notice that, for most of the cases (and certainly also in this case in which we don't even take into account the beam profile, noise and digitization!) the faster LHEP Physics List would be good enough for calorimetry studies. However, we prefer to use, as default, the more sophisticated (but slower) QGSC Physics List for the learning purposes of this example. 5. Particle Generator --------------------- The 1996 test-beam has been taken with the following particles: --- 225 GeV muons (for calibration) --- 10 to 300 GeV pions --- 10 to 300 GeV electrons therefore the standard Geant4 Particle Gun has been used as primary generator. Notice that, for the sake of keeping the example not too complicated, the proper simulation of the beam profile and beam contamination have been neglected. 6. Hits ------- In CMS there are two groups of hits: Tracker-like and Calorimeter-like. Only the latter one appears in this example. For the same reasons, as seen for the Geometry, of consistency without duplication of information and unnecessary coupling between Simulation, Reconstruction, and Visualization, the simulation calorimeter hit class, CCalG4Hit, doubly inherits from the common Geant4 abstract class for all hits, G4VHit, and from the "core" (i.e. simulation independent) CMS calorimeter hit class, CCalHit. A new Hit object is created - for each new particle entering the calorimeter; - for each detector unit (i.e cristal or fiber or scintillator layer); - for each nanosecond of the shower development; The information stored in each CCalHit object is the following: - Entry : local coordinates of the entrance point of the particle in the unit where the shower starts; - the TrackID : Identification number of the incident particle; - the IncidentEnergy : kinetic energy of that incident particle; - the UnitID : the identification number of the detector unit (crystal, or fiber, or scintillator layer); - the TimeSlice : the time interval, in nanoseconds, in which the hit has been created; - the EnergyDeposit : the energy deposit in this hit. Notice that all hit objects created for a given shower have the same values for the first three pieces of information. No Noise and Digitization -------------------------- In order to keep the complexity of this example to a reasonable level, both noise and digitization effects have not been included. 7. User Actions ---------------- In this example. there have been used the following User Actions: --- G4UserRunAction (the derived, concrete class is CCalRunAction): it is used to invoke the Analysis object at the beginning of the Run, to instantiate it and passing it the Run number, and at the end of the Run, to inform it that the Run is finished and therefore the histograms, ntuples, etc. must be closed. --- G4UserEventAction (the derived, concrete class is CCalEndOfEventAction): it is used to examine, at the end of the Event, all collected (calorimeter) hits, extract the various observables which are interesting (to the goal of understanding things like: the effect of magnetic field on scintiallator; choice of the absorber thickness by optimizing resolution versus containment; impact of the absorber depth in the energy caontainment; electromagnetic calorimeter contribution in the electron - pion separation; etc.) and finally call the analysis object to store such selected information on histograms and/or in the ntuple. The name of the class "CCalEndOfEventAction" is motivated by the fact that at the beginning of the Event nothing is done. --- G4UserSteppingAction (the derived, concrete class is CCalSteppingAction): it is used to extract some "unphysical" information (that is not experimentally measurable, although interesting for a better understanding of the shower development), namely the lateral profile and the deposit as a function of the time (see "8.Analysis/Histogramming for more details"), which is available only from simulation, and then, at the end of Event, the analysis object is invoked to store such information on histograms. Please notice that the stepping action is not used to create hits. --- G4UserStackingAction (the derived, concrete class is CCalStackingAction): it is used to ensure that the same track ID of the particle originating a shower appears in all hits (calorimeter hit objects of class CCalHit) of the shower, in any calorimeter part. 8. Analysis / Histogramming ---------------------------- The analysis part of CompositeCalorimeter is kept in class CCalAnalysis, and is based on the AIDA interfaces and their implementation in PI. Please take a look to the web page: http://www.cern.ch/PI . Both the histograms and the ntuple are saved at the end of the run in the HBOOK file "ccal.his". You can than analyze offline the contents of such a file, using Lizard (or any other AIDA-compliant package) or with Paw or Root. Please note that in a multiple run session, the last run always override the HBOOK file. What the histograms and the variables of the ntuple represent is explained below: Histograms 100 - 127 : energy deposit (in GeV) in the sensitive part (plastic scintillator layer) of one Hadronic calorimeter module (there are 28 modules, numbered from 0 to 27, and the corresponding histogram has ID = 100 + number of module). Ntuple variables hcal0 - hcal27 : provide the same information. Histograms 200 - 248 : energy deposit (in GeV) in one crystal electromagnetic towers (there are a matrix of 7 x 7 = 49 towers, numbered from 0 to 48, and the corresponding histogram has ID = 200 + number of tower). Ntuple variables ecal0 - ecal48 : provide the same information. Histograms 300 - 339 : total energy deposit (in GeV) in any electromagnetic crystal tower or hadronic module (either in a sensitive or insensitive layer) in one of the 40 nanosecond time slices: in other words, histogram 300+I , where I = 0 - 39, contains the total deposit energy between I and I+1 nanoseconds after the "collision". (Notice that the time window considered, 40 nanoseconds, is larger than the LHC bunch-crossing of 25 nanoseconds.) Histograms 400 - 469 : energy profile (in GeV), summed over all layers sensitive (plastic scintillator) and insensitive (copper absorber), as a function of the radial distance (in centimeter) from the beam axis ( ID histo = 400 + radial distance in cm ). Histogram 4000 : total energy deposit (in GeV) in the sensitive parts of either the electromagnetic or hadronic calorimeters. Ntuple variable edep provides the same information. Other ntuple variables are the following: --- elab : energy (in GeV) of the incident particle. --- xpos, ypos, zpos : position (in mm) from where the projectile has been shot. --- edec, edhc : total energy deposit (in GeV) in the sensitive parts of, respectively, the electromagnetic and hadronic calorimeters. Notice that their sum edec+edhc coincides with edep Notice that lateral profile (400-469) and time-slice (300-339) histograms show purely Monte Carlo quantities, which cannot be experimentally measured. Please be careful that the range of the histograms has been chosen in such a way to contain most of the entries, but only few histograms fill a large fraction of that range, whereas the remaining majority fill only the first few bins (corresponding to lower energy), and, therefore, when plotted they look almost empty, but they are not, and the results are sensible. We suggest to plot the ntuple's variables, rather than the histograms, when the same information is available from the ntuple. 9. Visualization / GUI ----------------------- If you setup one of the following Geant4 environmental variables: G4VIS_USE_DAWN G4VIS_USE_VRML G4VIS_USE_OPENGLX which correspond to the use of DAWN, VRML, and OPENGLX, respectively, as visualization engine of Geant4, and set properly the corresponding PATH as well, it is then possible to visualize the detector and also some events. To do so, you have to run > $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter without input file: you then see the detector; after that, you can select the particle gun and its energy, in the case you want something different from the the default (which is a 100 GeV pi-), for example: Idle> /gun/particle e- Idle> /gun/energy 200 GeV and then run some events, for example: Idle> /run/beamOn 3 Notice that, by default, OGLIX is used for the visualization, because it is quite fast and it does not produce any files in output. However, you can always choose something else, for example VRML2FILE or DAWNFILE, either interactively as follows: Idle> /vis/open DAWNFILE or by changing the default, by editing the file (main program) CompositeCalorimeter.cc and comment/uncomment the lines in such a way to have, at the end: visCommand = "/vis/open DAWNFILE"; // visCommand = "/vis/open VRML2FILE"; // visCommand = "/vis/open OGLIX"; The tracks that are shown include both charged and neutral particles of any momentum: if you want instead only charged, or only neutral, then you have simply to edit src/CCalEndOfEventAction.cc at the end of the method EndOfEventAction and uncomment the line where the condition on the charge is made (it should then be straighforward to eventual add some other conditions, for example if you want to see only those particles that satisfy certain kinematic conditions). Rather than to specify "by hand" the type of particle gun, its energy, and the number of events, it is possible to have a very simple GUI (graphical user interface) from which to make such choices, between a limited set of possibilities, via menus. Such GUI is based on Motif XmCommand widget, but it would be straightforward, eventually, to make the necessary changes in order to use a different one. The only thing you need to do to get the GUI is to setup the following Geant4 environmental variables: G4UI_BUILD_XM_SESSION=1 G4UI_USE_XM=1 Then, if you run the executable without specifying a macro file (like test.g4mac): > $G4WORKDIR/bin/$G4SYSTEM/CompositeCalorimeter a window automatically pops out, with the menus where you can make your selection of particle type, energy, and number of events to be run. 10. Classes Overview --------------------- This is a schematic overview of the classes defined in this example: CCalPrimaryGeneratorAction CCalPrimaryGeneratorMessenger User action for primaries generator. CCalDetectorConstruction CCalAMaterial CCalDataSet CCalDetector CCalEcal CCalEcalOrganization CCalG4Able CCalG4Ecal CCalG4Hall CCalG4Hcal CCalGeometryConfiguration CCalHall CCalHcal CCalHcalOrganization CCalMagneticField CCalMaterial CCalMaterialFactory CCalRotationMatrixFactory CCalVOrganization CCalVisManager CCalVisualisable CCaloOrganization CCalutils Geometry and material definitions for the detector. Notice in particular that: CCalHall, CCalEcal, CCalHcal derive from CCalDetector; CCalG4Hall, CCalG4Ecal, CCalG4Hcal derive from the above corresponding classes and from CCalG4Able; CCalEcalOrganization, CCalHcalOrganization derive from CCalVOrganization : each sensitive cell has an unique number for detector organization (this is a software ID not an hardware/electronic one). CCalHit CCalG4Hit CCalG4HitCollection CCalSDList CCalSensAssign CCalSensitiveConfiguration CCalSensitiveDetectors CCaloSD Hit and Sensitive Detectors. Notice in particular that: CCalG4Hit derives from G4VHit and CCalHit; CCaloSD derives from G4VSensitiveDetector. CCalAnalysis Analysis manager class which uses Anaphe. CCalRunAction User run action class. CCalEndOfEventAction User event action class. CCalStackingAction User Stacking action class. CCalSteppingAction User Stepping action class.