source: trunk/examples/novice/N07/README @ 1319

$Id: README,v 1.5 2007/05/04 01:49:28 asaim Exp $
-------------------------------------------------------------------

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

                            ExampleN07
                            ----------


     This example simulates three simplified sandwitch calorimeters.
     The main features demonstrated in this example are :

     1. Utilizing a concrete run class derived from G4Run base class for
       accumulating physics quantities for a run
     2. Changing calorimeter geometries without re-building a world volume
     3. Defining geometrical regions and setting production thresholds
       for each region
     4. Demonstrating the use of primitive scorer and filter classes without
       implementing sensitive detector class
     5. Demonstrating the use of parallel scoring geometry and associating
       parallel world scoring process
     6. Measuring the timing spent for each region, both for all particle
       types and for e+/e-

     **********************************************************************
     Note: Since this example utilizes its own ExN07SteppingVerbose for the
       timing measurement, the user cannot get the ordinary verbosity with
       /tracking/verbose.
     **********************************************************************

 1- Utilizing a concrete run class derived from G4Run base class for
    accumulating physics quantities for a run
 
    G4Run is a class the user can inherit and create his/her own concrete
    class for accumulating information useful to him/her. It has a virtual
    method RecordEvent(const G4Event*), which will be invoked by G4RunManager
    at the end of processing each event. By implemeting this method in the
    user'r concrete run class, he/she can store information associating with
    G4Event class itself and hits collections attached with G4Event. In this
    example, ExN07Run is the class derived from G4Run. In the method
    ExN07Run::RecordEvent(const G4Event*), in addition to counting the
    number of events, all hits collections are accessed to accumulate
    energy depositions, step lengths and number of steps.

    In case the user create his/her own run class, an object of this class
    must be instantiated in the method GenerateRun() of his/her concrete
    class derived from G4UserRunAction base class. The pointer to this run
    object must be returned by this method. In this example, ExN07RunAction
    is the class which instantiating ExN07Run class object.  In
    ExN07RunAction::EndOfRunAction(const G4Run*) method, ExN07Run object
    is analized to output the run summary.

    It should be noted that some information about generated secondaries
    are collected in ExN07StackinAction instead of sensitive detector class.
    ExN07StackingAction::ClassifyNewTrack(const G4Track*) method is used
    not for classifying tracks sent to the stack, but for accessing to all
    secondaries generated in an event. 
         
 2- Changing calorimeter geometries without re-building a world volume

    In ExN07DetectorConstruction, all solids, logical and physical volumes
    are constructed only once at the first invocation of Constuct() method.
    Positions and number of slices are changed not by re-constructing another
    objects but by modifying data members of already existing objects as
    it is implemented in ExN07DetectorConstruction::SetNumberOfLayers(G4int)
    for changing the number of parameterized volumes, and also
    ExN07DetectorConstruction::SetSerialGeometry(G4bool) for changing the
    position of placed volumes.
 
 3- Defining geometrical regions and setting production thresholds
    for each region

    Setting production thresholds (so-called production cuts) to individual
    region of a detector geometry is the 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 the
    users,
     a) who is simulating most complex geometry such as an LHC detector,
     b) and who has enough experience of simulating EM showers in matter.
    We strongly recommend to compare the simulated results of this new
    feature with the results of the same geometry but having uniform 
    production thresholds. Setting completely different cut values for
    individual region may break the coherent and comprehensive accuracy
    of the simulation. Thus such cut values should be carefully optimized
    by the user with comparison with results of uniform cuts.

    In ExN07DetectorConstruction::Construct(), Three objects of 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 volume" so that all daghter volumes in
    these logical volumes are also affected by the corresponding regions.

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

 4- Demonstrating the use of primitive scorer and filter classes without
    implementing sensitive detector class

    In ExN07DetectorConstruction::SetupDetector() method, concrete classes
    G4PSEnergyDeposit, G4PSNofSecondary, G4PSTrackLength, G4PSNofStep and
    G4PSMinKinEAtGeneration, all of thich are derivalable of G4VPrimitiveScorer,
    are used to define the sensitivity of the calorimeter. All of them are
    registered to G4MultiFunctionalDetector and this detector object is set
    to the logical volume. G4SDParticleFilter is used to define the particle
    type(s) to be scored.

    In ExN07Run::RecordEvent() method, the way of retreiving G4THitsMap
    from each primitive scorer via G4HCofThisEvent is demonstrated.
    In ExN07RunAction::EndOfRunAction(), Run is summarized with data kept
    in ExN07Run class object.

 5- Demonstrating the use of parallel scoring geometry and associating
    parallel world scoring process

    In ExN07PhysicsList::ConstructGeneral(), G4ParallelWorldScoringProcess is
    assigned to all the particle types. This process invokes sensitive detectors
    (and scorers) defined in the parallel world "ParallelScoringWorld", the
    name of the parallel world which is defined in main() (exampleN07.cc) as
    an argument of ExN07ParallelWorld constructor.
    
    As implemented in ExN07ParallelWorld::SetupGeometry(), the world volume of
    the parallel world is obtained by GetWorld() method as a clone copy of the
    world volume of the mass geometry. The user should not create the world volume.

    ExN07ParallelWorld defines three cylindrical volumes, each of them is
    located at the same position as three sandwitch calorimeters defined
    in the mass geometry (ExN07DetectorConstruction). Each cylinder is replicated
    in Rho to define 20 layers, and scores the same quantities as the mass geometry.
    These three cylinders are relocated accordingly when the mass geometry is
    modified by ExN07DetectorConstruction::SetSerialGeometry().

 6- Measuring the timing spent for each region, both for all particle
    types and for e+/e-
 
    ExN07SteppingVerbose class has two G4SliceTimer class objects for each
    detector region. One G4SliceTimer is measuring the time spent by a step
    in a region for all types of particles, and another is measuring for
    e+/e- only. 

    ExN07SteppingVerbose::InitializeTimers() is invoked by ExN07RunAction::
    BeginOfRunAction(), and checks the number of regions appear in the
    geometry and instantiates the necessary number of timers. Thus, this
    ExN07SteppingVerbose class can be used for any kind of geometry the user
    defines without any modification. Given G4VSteppingVerbose is not invoked
    if the verbosity of G4SteppingManager is 0, this verbosity is set to 1.

    NewStep() and StepInfo() are the methods defined in G4VSteppingVerbose
    base class, and they are invoked at the beginning and the end of every
    step, respectively, from G4SteppingManager. Thus, these methods are
    utilized in ExN07SteppingVerbose to start/resume and pause the timer.

    ExN07SteppingVerbose::Report() method is used by ExN07RunAction::
    EndOfRunAction() to get the timing measured.

 7- Macro files

  exampleN07.in
    To be used for batch mode. The reference output file is made by this
    macro file.

  sample.mac
    To be used for interactive mode. Issue "/control/execute sample.mac"
    when "Idle>" prompt appears.

  vis.mac
    Setting visualization parameters. This macro file will be called 
    automatically when interactive execution starts.

 8- UI commands defined in this example
 
Command /N07/setAbsMat
Guidance :
Select Material of the Absorber.

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



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

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



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

Parameter : nl
 Parameter type  : i
 Omittable       : False



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

Parameter : serialize
 Parameter type  : b
 Omittable       : False