$Id: README,v 1.11 2001/12/07 12:57:30 pfeiffer Exp $
-------------------------------------------------------------------

     =========================================================
     Geant4 - an Object-Oriented Toolkit for Simulation in HEP
     =========================================================

                            gammaray_telescope
                            ------------------
                     F.Longo, R.Giannitrapani & G.Santin
                     December 2000

--------------------------------------------------------------
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 2.2 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 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    
  (IMPORTANT: Do not set G4ANALYSIS_USE_NTUPLE	when using XM!)
	

 - 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

  To be sure to have the right compilation and link flags, the 
  'aida-config' command, provided by an AIDA compliant implementation
  must be up and running ; in particular 'aida-config --cflags' and
  'aida-config --libs' must be active.

 - Set up for analysis using Anaphe/Lizard 

  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 # To store Ntuples 

  (IMPORTANT: Do not set G4UI_USE_XM when using Ntuples!)

  and be sure to have the right path to the Lizard library, inserting this
  on the .tcshrc:

 (on a CERN machine with the gcc-2.95 compiler)
  
  setenv PATH ${PATH}:/afs/cern.ch/sw/lhcxx/specific/redhat61/gcc-2.95.2/3.6.5/bin
  source /afs/cern.ch/sw/lhcxx/share/LHCXX/3.6.5/install/sharedstart.csh

 (on a CERN machine with the egcs-2.91.66 compiler (G4SYSTEM Linux-egcs)

  setenv PATH ${PATH}:/afs/cern.ch/sw/lhcxx/specific/redhat61/egcs_1.1.2/3.6.5-sec/bin
  source /afs/cern.ch/sw/lhcxx/share/LHCXX/3.6.5-sec/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).


 ATTENTION:
 If you use analysis with Lizard, you have to remove any hbook file in the 
 example directory obtained in previous Geant4 sessions. This issues will be 
 solved in future releases. Note also that the following error can be reported
 during run with analysis activated

 ***** ERROR in HLNEXT : Bad sequence for RZ : ID=       1 
	
 Ignore this message; histograms (and ntuples) are correctly saved in the hbook files.
			
	
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
----------------

 At present there are two options for analysis packages: either 
 explicitely the Anaphe 3.6.5 (or compatible) version is selected, 
 or any AIDA-2.2 compliant analysis system is chosen.  This dual
 approach will be removed in the next release when only the AIDA
 compliant version will be present. Presently, the OpenScientist 
 package (version 8) provides an implementation of AIDA 2.2, 
 other packages as Anaphe and JAS will follow soon. 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.

9. Histogramming
----------------

 Some hits information can be visualized runtime using Lizard (if it is 
 available on the user platform); two 2D histograms and two 1D histograms 
 can be visualized and saved (as PostScript files) during the simulation
 run. The 2D histograms contain the hits positions on the TKR projected on 
 the XZ plane and the YZ plane; 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 that this 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); in particular
 it is possible to enable or disable the drawing of the 1D and 2D histograms 
 at every event and to enable or disable the saving of PostScript files at the 
 end of each run. 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










