$Id: README,v 1.10 2006/11/22 18:58:25 vnivanch Exp $
-------------------------------------------------------------------

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

                            TestEm9
                            -------
     Demonstrate electromagnetic physics in crystal calorimeters.
     How to define cut-per-region.
     
 1- GEOMETRY DEFINITION

     The geometry consists of the vertex detector (VD), the electromagnetic
     calorimeter (EM), and the muon identifier (MU). Detector layout along
     the axis Z.

     VD consisted of 3 layers of Si with pads structured along the axis X.
     Between VD and EM there are 2 active absorbers (scintillators).
     EM is the matrix 5x5 of heavy crystals. MU consist of 2 active absorbers
     (scintillators) and the iron plate between.

     2 additional to the World regions are defined: VertexDetector and
     MuonDetector. For testing purposes first absorber of MU is included in
     the region of VD.

     Material of calorimiter and absorber can be choosen:
          Air Water lAr Al Fe BGO PbWO4 Pb.
     eg: /testem/det/CalMat PbWO4
         /testem/det/AbsMat Al

     The size of the detector can be changed also.

     eg: /testem/det/EcalLength   20  cm
         /testem/det/EcalWidth     5  cm
         /testem/det/update             ---> rebuild the geometry

 2- PHYSICS LISTS

    Physics Lists are based on modular design. Few modules are instantiated:
    1. Transporatation
    2. EM physics
    3. Decays
    4. StepMax - for steplimitation

    The following options for EM physics are available:	 
    - "standard"        the best standard EM physics (default)
    - "G4standard"      recommended standard EM physics for LHC
    - "G4standard_fast" the best CPU performance standard physics for LHC
    - "G4standard_exp"  experimental standard physics for LHC
    - "Livermore"       low-energy EM physics using Livermore data
    - "Penelope"        low-energy EM physics implementing Penelope models

    Optional components can be added:
    - "elastic"       elastic scattering of hadrons
    - "binary"        QBBC configuration of hadron/ion inelastic models
    - "gamma_nuc"     gamma- and electro-nuclear processes
    - "stopping"      stopping processes

 3- AN EVENT : THE PRIMARY GENERATOR

     The primary kinematic consists of a single particle which hits the
     cylinder perpendicular to the input face. The type of the particle
     and its energy are set in the PrimaryGeneratorAction class, and can
     changed via the G4 build-in commands of ParticleGun class.

 4- OUTPUT

     The batch regime of simulation can be started 
       $G4WORKDIR/bin/$G4SYSTEM/TestEm9 TestEm9.in
     where TestEm9.in is the example of macro file for batch job.

     As a result of simulation the number of secondaries produced
     in different regions are averaged. The average energy depositions
     in active absorbers and EM as well as RMS of these values are shown.
     The number of hits in pads of VD is printed out.

 5- VISUALISATION

     To use visualisation the environment variable G4_VIS_USE should be 
     defined. An interactive session starts if no macro file is specified 
     in the command line:
       $G4WORKDIR/bin/$G4SYSTEM/TestEm9

     To start visualisation one can issur 
     >/control/execute vis.mac
     >/run/beamOn 1

 6- ANALYSIS

     To create histograms/ntuple for further analysis one should define
     environment variable G4ANALYSIS_USE and setup local AIDA implementation.
     The example should be recompiled:

     gmake histclean
     gmake
      
     The macro file csi.mac can be used as exmple of macro for analysis. It
     can be executed in the following way:
     $G4WORKDIR/bin/$G4SYSTEM/TestEm9 csi.mac

 
 7- Using histograms
 ------------------- 

By default the histograms are not activated. To activate histograms
the environment variable G4ANALYSIS_USE should be defined. For instance
uncomment the flag G4ANALYSIS_USE in GNUmakefile.

To use histograms any of implementations of AIDA interfaces should
be available (see http://aida.freehep.org).

A package including AIDA and extended interfaces also using Python
is PI, available from: http://cern.ch/pi .

Once installed PI or PI-Lite in a specified local area $MYPY, it is
required to add the installation path to $PATH, i.e. for example,
for release 1.2.1 of PI:

setenv PATH ${PATH}:$MYPI/1.2.1/app/releases/PI/PI_1_2_1/rh73_gcc32/bin

CERN users can use the PATH to the LCG area on AFS.

Before compilation of the example it is optimal to clean up old 
files:

gmake histclean
gmake

Before running the example the command should be issued:

eval `aida-config --runtime csh`

It is possible to choose the format of the output file with 
histograms using UI command:

/testem/histo/setFileType type

The following types are available: hbook, root, xml.