$Id: README,v 1.18 2002/12/08 18:08:10 flongo Exp $
-------------------------------------------------------------------
=========================================================
Geant4 - an Object-Oriented Toolkit for Simulation in HEP
=========================================================
gammaray_telescope
------------------
F.Longo, R.Giannitrapani & G.Santin
December 2002
--------------------------------------------------------------
Acknowledgments to GEANT4 people, in particular to R.Nartallo,
A.Pfeiffer, M.G.Pia and G.Cosmo
--------------------------------------------------------------
GammaRayTel is an example of application of Geant4 in a space
envinronment. It simulates a typical telescope for gamma ray analysis;
the detector setup is composed by a tracker made with silicon planes,
subdivided in ladders and strips, a CsI calorimeter and an
anticoincidence system. In this version, the three detectors are made
sensitive but only the hits on the tracker strips are registered and relevant
information (energy deposition, position etc) are dumped to an external
ASCII file for subsequent analysis. If the user has set up the
AIDA (version 3.0 or compatible) environment or Anaphe/Lizard is available,
then some histograms with relevant hits information are displayed
and saved as PostScript files, and histograms and ntuples with
relevant information are stored on a HBOOK file.
The main features of this example are
a) Macros for the visualization of geometry and tracks with
OpenGL, VRML and DAWN drivers
b) Implementation of messengers to change some parameters of
the detector geometry, the particle generator and the analysis
manager (if present) runtime
c) Readout geometry mechanism to describe an high number of
subdivisions of the planes of the tracker (strips) without
affecting in a relevant way the simulation performances
d) Histograming facilities are presently provided for the Linux
environment either by using the AIDA interfaces, or through
the Anaphe/Lizard system. The AIDA compliant version has not
been tested by the developers and is here as a example of
"forward compatibility" on how to use analysis.
e) User interfaces via Xmotif or normal terminal provided
1. Setting up the environment variables
---------------------------------------
- Setup for storing ASCII data
If you want to store the output data in an ASCII file 'Tracks_x.dat'
where x stays for the run number. You should specify the environment
variable:
setenv G4STORE_DATA 1
- Setup for Visualization
IMPORTANT: be sure that your Geant4 installation has been done
with the proper visualization drivers; for details please see the
file geant4/source/visualization/README.
To use the visualization drivers set the following variables in
your local environment:
setenv G4VIS_USE_OPENGLX 1 # OpenGL visualization
setenv G4VIS_USE_DAWNFILE 1 # DAWN file
setenv G4VIS_USE_VRMLFILE 1 # VRML file
setenv G4VRMLFILE_VIEWER vrmlview # If installed
- Setup for Xmotif user interface
setenv G4UI_USE_XM 1
- Set up for analysis using AIDA
To compile the GammaRayTel example with the analysis tools activated,
set the following variables
setenv G4ANALYSIS_USE 1 # Use the analysis tools
setenv G4ANALYSIS_USE_NTUPLE 1 # Use the ntuple
and be sure to have the right path to the Anaphe library (or to another AIDA
compliant implementation), inserting this on the .tcshrc:
(on a CERN machine with the gcc-2.95 compiler)
ln -s /afs/cern.ch/sw/lhcxx/share/LHCXX/5.0.2/scripts/* ~/bin/.
(to be done once)
setenv PATH ${PATH}:/afs/cern.ch/sw/lhcxx/specific/redhat61/gcc-2.95.2/5.0.2/bin
source /afs/cern.ch/sw/lhcxx/share/LHCXX/5.0.2/install/sharedstart.csh
2. Sample run
-------------
To run a sample simulation with gamma tracks interacting with
the detector in its standard configuration and without any
visualization, execute the following command in the example main
directory:
$G4WORKDIR/bin/$G4SYSTEM/GammaRayTel
It is possible also to run three different configuration defined in
macro1.mac, macro2.mac and macro3.mac for visualization (OpenGL, VRML
and DAWN respectively) with the following command
$G4WORKDIR/bin/$G4SYSTEM/GammaRayTel macroX.mac
where X can be 1, 2 or 3. Be sure to have the right environment (see
the preceding section) and the proper visualization driver enabled in
your local G4 installation (see geant4/source/visualization/README for
more information).
3. Detector description
-----------------------
The detector is defined in GammaRayTelDetectorConstruction.cc
It is composed of a Payload with three main detectors, a Tracker (TKR), a
Calorimeter (CAL) and an Anticoincidence system (ACD).
The standard configuration is made of a TKR of 15 Layers of Si detectors,
with Lead converter, and a CAL of 8 layers of CsI. 4 lateral panels and a
top layer of plastic scintillator (ACT and ACL) complete the configuration.
The Si detectors are composed of two silicon planes subdivided in strips
aligned along the X axis in one plane and along the Y axis for the other.
It is possible to modify in some way this configuration using the
commands defined in GammaRayTelDetectorMessenger.
This feature is available in the UI throught the commands subtree
"/payload/" (see the help command in the UI for more information).
4. Physics processes
--------------------
This example uses the standard Electromagnetic processes.
5. Particle Generator
---------------------
The GammaRayTelParticleGenerationAction and its Messenger let the user define
the incident flux of particles, from a specific direction or from an
isotropic background. The user can define also between two spectral options:
monochromatic or with a power-law dependence. The particle
generator parameters are accessible throught the UI tree "/gun/" (use the
UI help for more information). We are planning to include, in the next
release of this example, the new General Particle Source module of G4.
6. ReadOutGeometry
------------------
The tracker is made of Silicon Microstrips detectors. The ReadOut geometry
provides the description of the strips.
7. Hit
------
In this version the hits from the TKR the CAL and the ACD are generated.
Only the hit from the TRK are saved. Each TKR hit contains the following
information
a) ID of the event (this is important for multiple events run)
b) Energy deposition of the particle in the strip (keV)
c) Number of the strip
d) Number of the plane
e) Type of the plane (1=X 0=Y)
f) Position of the hit (x,y,z) in the reference frame of the payload
The hit information are saved on an ASCII file named Tracks_N.dat, where
N is the progressive ID number associated to the run.
8. Analysis
----------------
The analysis part of GammaRayTel is based on the AIDA interfaces and their
implementation in Anaphe; please look at their documentation for more details.
Keep in mind that the actual implementation of the analysis tools in GammaRayTel
is of a pedagogical nature, so we kept it as simple as possible.
Further improvements will follow in future releases. The actual analysis produces
some histograms (see next section) and an ntuple. Both the histograms and
the ntuple are saved at the end of the run in the file "gammaraytel.hbook". You
can than analyze offline the contents of such a file; the GammaRayTel contains
also a very simple python script that can be used with Lizard to plot the
histograms See the Lizard documentation on how to access the ntuple.
Please note that in a multiple run session, the last run always override the
hbook file.
9. Histogramming
----------------
Some hits information can be visualized runtime using the Anaphe Plotter
(if it is available on the user platform); two 1D histograms can be
visualized during the simulation run.
The 1D histograms contain the energy deposition in the last X plane of
the TKR and the hits distribution along the X planes of the TKR
(note again that these histograms have been chosen more for pedagogical
motivation than for physical one).
These histograms are filled and updated at every event and are initialized
with each new run; the scale of the histograms is automatically derived from
the detector geometry.
Throught a messenger it is possible to set some options with
the UI subtree "/analysis/" (use the UI help for more info);
If you feel that the simulation is too slow with the
histograms updated every event, you can disable the drawing and retain
the saving. Please note that the updating of the histograms is triggered
only when there is some hit in an event.
In this example we only show the use of very basic feature of this new
simulation/analysis framework; histogramming and analysis in Geant4
are in an evolving phase, so expect some changes and/or improvements
for next releases.
10. Digi
--------
For the TKR also the digits corresponding to the Hits are generated.
A digi is generated when the hit energy deposit is greater than a threshold
(in this example setted at 120 keV).
The TKR digi information are stored on the same file Tracks_N.dat and contain:
a) ID of the event (this is important for multiple events run)
b) Number of the strip
c) Number of the plane
d) Type of the plane (1=X 0=Y)
11. Classes Overview
-------------------
This is the overview of the classes defined in this example
GammaRayTelPrimaryGeneratorAction
User action for primaries generator
GammaRayTelPrimaryGeneratorMessenger
Messenger for interactive particle generator
parameters modification via the User Interface
GammaRayTelPhysicsList
Determination of particles and processes active in this
example
GammaRayTelTelVisManager
Visualization manager class
GammaRayTelDetectorConstruction
Geometry and material definitions for the detector
GammaRayTelDetectorMessenger
Messenger for interactive geometry parameters
modification via the User Interface
GammaRayTelAnalysis
Analysis manager class with Lizard tool (experimental)
GammaRayTelAnalysisMessenger
Messenger for interactive analysis options modification
via the User Interface
GammaRayTelRunAction
User run action class
GammaRayTelEventAction
User event action class
GammaRayTelTrackerHit
Description of the hits on the tracker
GammaRayTelDigi
Description of the digi on the tracker
GammaRayTelDigitizer
Description of the digitizer for the tracker
GammaRayTelTrackerROGeometry
Description of the readout geometry for strips subdivision
GammaRayTelTrackerSD
Description of the TKR sensitive detector
GammaRayTelAnticoincidenceHit
Description of the hits on the anticoincidence
GammaRayTelAnticoincidenceSD
Description of the ACD sensitive detector
GammaRayTelCalorimeterHit
Description of the hits on the calorimeter
GammaRayTelCalorimeterSD
Description of the CAL sensitive detector
Gabriele Cosmo