source: trunk/examples/advanced/raredecay_calorimetry/README @ 1288

$Id: README,v 1.4 2005/12/09 16:44:21 mkossov Exp $
-------------------------------------------------------------------

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

     Photon_Inefficiency (raredecay_calorimetry) advanced example
     ------------------------------------------------------------


     This example simulates a simplified sandwitch calorimeter (developed from N07).
     The main features in this example to be demonstrated are:

     1. How to use a user's run class derived from the G4Run base class for accumulating
        physics values and hits to make the run result;

     2. How to change calorimeter geometry without re-building a world volume;

     3. How to change materials which are used in parameterized volumes;

     4. How to instantiate more than one sensitive detectors with different
        module names from only one sensitive detector class;

     5. How to define geometrical regions and set production thresholds for each readout
        region;

     6. How to Estimate importance of photonuclear reactions for photon inefficiency of
        calorimeters;

     7. How to compare effectiveness of different absorbers to reduce photon inefficiency.

     8. How to use macro files in the batch and interactive modes.

     9. How to make the user's UI commands (/PhotIn/ in this example).

 1- Utilizing a run class derived from the G4Run base class for accumulating energy
    depositions and hits for the run result:
 
    G4Run is a class which users can inherit and create their own class for accumulating
    useful information. It has a virtual method RecordEvent(const G4Event*), which is
    called by G4RunManager class at the end of event processing. By implemeting this method
    in the user's run class, one can store information associated with G4Event class and
    hit collections attached to the G4Event class. The PhotInRun class is a class derived
    from the G4Run class. In the PhotInRun::RecordEvent(const G4Event*) method events are
    counted and all hit collections are accessed to accumulate energy depositions, step
    lengths and numbers of steps.

    When users create run classes, objects of these classes must be instantiated in the
    GenerateRun() method of the class derived from G4UserRunAction base class. The pointer
    to the run object must be returned by this method. A PhotInRunAction class instantiates
    PhotInRun class object. In the PhotInRunAction::EndOfRunAction(const G4Run*) method,
    PhotInRun object is analized to make the output run summary.

    Generated secondary particles is collected in the PhotInStackinAction class instead of
    the sensitive detector class. A PhotInStackingAction::ClassifyNewTrack(const G4Track*)
    method is used not for tracks which are sent to the stack, but for accessing all
    secondaries generated in the event. 
         
 2- Changing calorimeter geometry without re-building a world volume:

    In PhotINDetectorConstruction, all solids, logical and physical volumes are constructed
    only once in the first Constuct() method. Positions and numbers of slices are changed
    not by re-constructing new objects but by modifying data members of already existing
    objects as it's implemented in the PhotInDetectorConstruction::SetNumberOfLayers(G4int)
    method for showing how to change the number of the parameterized volumes, and also in
    the PhotInDetectorConstruction::SetSerialGeometry(G4bool) method as an example of
    changing positions of the placed volumes.
 
 3- Changing materials already used in parameterized volumes:
        
    Materials of absorbers and of the sensitive gap in the calorimeter are defined by the
    PhotInGapParameterisation::ComputeMaterial(const G4int,G4VPhysicalVolume*) method.
    Positions of each layer in the calorimeter have to be defined by the method
    PhotInGapParameterisation::ComputeTransformation(const G4int,G4VPhysicalVolume*).

 4- Instantiating more than one sensitive detectors with different module names using only
    one sensitive detector class:

    The PhotInCalorimeterSD class is constructed three times with deferent module names in
    the PhotInDetectorConstruction::Construct() method. Each detector creates two hits
    collections (PhotInCalorHit class). In total six hits collections of the same type are
    created for each event. To access each of six collections in the PhotInEventAction
    method both the module name and the collection name are used.

 5- Defining geometrical regions and setting production thresholds for each region:

    Setting production thresholds (so-called production cuts) to individual region of the
    detector geometry is a new feature provided by Geant4 5.1 release. This feature is also
    called as "Cuts per region". Please, note that this new feature is supporsed to be used
    only by users,
     a) who are simulating complex geometry (such as LHC detectors);
     b) and who has enough experience of simulating EM showers in matter.
    It is strongly recommended to compare simulated results of this new feature with the
    results of the same geometry but with uniform production thresholds. Setting different
    cuts for each region may break coherent and comprehensive accuracy of simulation. Such
    regional cuts must be carefully optimized by users comparing results with uniform cuts.

    In the PhotInDetectorConstruction::Construct(), three objects of the G4Region class are
    instantiated and set to the logical volumes of each of three calorimeter modules. Also,
    these individual logical volumes are registered as "root logical volumes" so that all
    daghter volumes in the logical volumes are also affected by the corresponding regions.

    In the PhotInPhysicsList::SetCuts() method, in addition to set of the default threshold
    values for the world volume, three thresholds are set to three calorimeter regions
    respectively. Setting a production threshold to a region, gamma, electron, or positron
    are not generated as a secondary if its range is shorter than the production threshold
    for the particular region. Please note, that at present some EM processes still
    generate such secondaries below threshold.

 6- Estimating importance of photonuclear reactions for photon inefficiency of detectors:

           User can switch on or off the photo- (and electro-) nuclear processes for the run.

 7- Compare effectiveness of different absorbers to reduce the photon inefficiency:

    User can compare results of simulation for different materials of absorbers.

 8- Macro files:

    Batch mode: ">./PhotIn < PhotIn.in" (It creates a reference output file PhotIn.out)

    Interactive mode: ">./PhotIn".
                      Print "/control/execute sample.mac" when "Idle>" prompt appears.
    or (as the sam="/control/execute sample.mac" alias is define in vis.mac)
                      Print "Idle> sam"

    Setting visualization parameters: The "vis.mac" macro file will be called automatically
    when the interactive execution starts.

 9- UI commands defined in the "Photon_inefficiency" example:

    --------------------------------------------------
 
    Command : /PhotIn/projParticle
    Guidance: Select Incident Beam Particle.

    Parameter     : particle
    Parameter type: s
    Omittable     : False
    Candidates    : < List of all Geant4 particles> 

    --------------------------------------------------

    Command : /PhotIn/projEnergy
    Guidance: Select Energy for the Beam Particle.

    Parameter     : Energy
    Parameter type: d
    Omittable     : False

    --------------------------------------------------

    Command : /PhotIn/setAbsMat
    Guidance: Select Material of the Absorber.

    Parameter     : choice
    Parameter type: s
    Omittable     : False
    Candidates    : Aluminium liquidArgon Lead Water Scintillator Air Galactic 

    --------------------------------------------------

    Command : /PhotIn/setGapMat
    Guidance: Select Material of the Gap.

    Parameter     : choice
    Parameter type: s
    Omittable     : False
    Candidates    : Aluminium liquidArgon Lead Water Scintillator Air Galactic 

    --------------------------------------------------

    Command : /PhoyIn/numberOfLayers
    Guidance: Set number of layers.
    Range of parameters : nl>0

    Parameter     : nl
    Parameter type: i
    Omittable     : False

    --------------------------------------------------

    Command : /PhoyIn/numberOfSlabs
    Guidance: Set number of slabs in a layer.
    Range of parameters : nl>0

    Parameter     : nl
    Parameter type: i
    Omittable     : False

    --------------------------------------------------

    Command : /PhotIn/serialGeometry
    Guidance: Select calorimeters to be placed in serial or parallel.

    Parameter     : serialize
    Parameter type: b
    Omittable     : False

    --------------------------------------------------

    Command : /PhotIn/verbose
    Guidance: Set verbosity of each event.
    Range of parameters : vl>=0 && vl<10

    Parameter     : vl
    Parameter type: i
    Omittable     : True
    Default value : taken from the current value

    --------------------------------------------------

General comments about the structure of the example:
====================================================

0. In all .cc files the debug flags can be defined. To make program silent comment them.
   In some .cc files the errors flag is defined. It permits run time warnings (if ever).

1. All constants of the example, names, and default values for the variable parameters are
   collected in the include/PhotInConstants.hh header widely used in almost all classes.

2. The src/PhotInHit collection is practically a structure for three values: energy
   deposition of charged particles, track length of neutrons, and #of steps. Hits are
   collected PhotInCalorHitsCollection's defined in include/PhotInCalorHit.hh.

3. PhotInCalorimeterSD class defines and treats 6 (two per detector: one for absorber, one
   for the active slabs) hit collections, so absorber is defined as a sensitive detector.

4. All cuts are made in the PhotInPhysicsList::SetCuts(), while in future cuts can be more
   complicated than the scaling of the standard cuts and can be out of the Physics List.

The dependency structure (general Constants.hh and PhotIn prefix is skipped).
=============================================================================

    .____________________________________________________________Main________.
    |         /          /         /                  /          |  |        |
    |   VisManager  PhysicsList   /           DetectorMessenger  | RunAction |
    |                            /           / /       \     \   |  |        |
     \                 PrimaryGeneratorAction /         \     \  | Run*  EventAction
      \                         |            /           \     \ |  |   /   /
        -----------------DetectorConstruction             \ StackingAction /
                        /       |            \             \              /
   LayerParameterization  GapParameterization CalorimeerSD  \            /
                                                   |         \          /
    (defined in the "CalorHit" as a type) CalorHitsCollection \        /
                                                             \ \      /
                                                              CalorHit


* SteppingAction is a debuging tool which can be optionally attached to the RunManager
=========================================================================================

Description of classes:
=======================

"CalorHit" handles (Reset/Add/Get) EnergyDeposition, TrackLengt, NumberOfSteps of the Hit
(+ "CalorHitsCollection" a container for CalorHits in different parts of the detector)

"CalorimeerSD" SensetiveDetector, nLay & nSlab definition, Layers & Slabs HitsCollections

"LayerParameterization" & "GapParameterization" parameterization of Layers & Slabs

"DetectorConstruction" create, change, and replace three calorimeters of the example

"StackingAction" calculates number of each kind of particles, their min & max energies

"PrimaryGeneratorAction" ParticleGun of events changes kind of particle, energy, direction

"DetectorMessenger" on flight change of the detector geometry, regions, and HitsCollections

"Run" run manager which can treat/reset information about particles and their energy range

"EventAction" & "RunAction" treat of the collected information of simulation

"PhysicsList" defines physics (now is not used and ReferencePhysicsLists are used instead) 

"VisManager" defines a way of visualization of the particular/overlaped events