$Id: README,v 1.20 2010-12-01 05:55:04 allison Exp $
-------------------------------------------------------------------

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

                            ExampleN03
                            ----------

	This example simulates a simple Sampling Calorimeter setup.
	(See also examples/extended/electromagnetic/TestEm3)
	
 1- GEOMETRY DEFINITION
 
   The calorimeter is a box made of a given number of layers. A layer
   consists of an absorber plate and of a detection gap. The layer is
   replicated.
 	
   Six parameters define the calorimeter :
        - the material of the absorber,
	- the thickness of an absorber plate,
 	- the material of the detection gap,
 	- the thickness of a  gap,
 	- the number of layers,
 	- the transverse size of the calorimeter (the input face is a square). 
 	
   In addition a transverse uniform magnetic field can be applied.
 	
   The default geometry is constructed in DetectorConstruction class,
   but all of the above parameters can be modified interactively via
   the commands defined in the DetectorMessenger class.


	|<----layer 0---------->|<----layer 1---------->|<----layer 2---------->|
	|			|			|			|
	==========================================================================
	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
	||   absorber 	|  gap	||   absorber 	|  gap	||   absorber 	|  gap	||
	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
 beam	||		|	||		|	||		|	||
======>	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
	||		|	||		|	||		|	||
	||    		| 	||    		| 	||    		| 	||
	==========================================================================
	
   NB. The thickness of the absorber or of the gap can be set to zero
       (but not together), and the number of layers to 1. In this case we
       have a unique homogeneous block of matter, which looks like
       a bubble chamber rather than a calorimeter ...
       (see the macro of commands: newgeom.mac)
	    
  A more general version of this geometry can be found in :
  examples/extended/electromagnetic/TestEm3   
 	    
 2- AN EVENT : THE PRIMARY GENERATOR
 
   The primary kinematic consists of a single particle which hits the
   calorimeter perpendicular to the input face. The type of the particle
   and its energy are set in the PrimaryGeneratorAction class, and can
   be changed via the G4 build-in commands of ParticleGun class (see
   the macros provided with this example).
 	
   In addition one can choose randomly the impact point of the incident
   particle. The corresponding interactive command is built in
   PrimaryGeneratorMessenger class (see run2.mac).
 	
   A RUN is a set of events.
	
 3- DETECTOR RESPONSE
 
   Per event, one wants record total energy deposit in Absober and Gap
   (total = sum of all layers), and also total track length of charged particles
   in Absober and Gap.
   
   Therefore, these 4 quantities are data members of class EventAction.  
   They are collected step by step in 
   SteppingAction::UserSteppingAction(), and passed to EventAction via methods
   AddAbs() and AddGap().
   
   In EndOfEventAction(), these quantities are printed and passed to RunAction
   to accumulate statistic and compute dispersion.
   
   It should be noticed that informations are collected and treated via 'direct'
   methods. One do not need to use (SensitiveDetector + HitsCollection) tool,
   though this can be done (see N02).
 	
 				
 4- VISUALIZATION
 
   The Visualization Manager is set in the main().
   The initialisation of the drawing is done via a set of /vis/ commands
   in the macro vis.mac. This macro is automatically read from 
   the main in case of interactive running mode.

   By default, vis.mac opens an OpenGL viewer.
   You can switch to other graphics systems by commenting out this line
   and instead uncommenting one of the other /vis/open statements, such as
   HepRepFile or DAWNFILE (which produce files that can be viewed with
   HepRApp and DAWN respectively).
	
   The DAWNFILE, HepRepFile drivers are always available 
   (since they require no external libraries), but the OGL driver requires:
     1- the visualisation & interfaces categories have been compiled
	with the environment variable G4VIS_BUILD_OPENGLX_DRIVER.
     2- exampleN03.cc has been compiled with G4VIS_USE_OPENGLX.
   (This is best done through Configure or CMake.)

   For more information on visualization, including information on how to
   install and run DAWN, OpenGL and HepRApp, see the visualization tutorials,
   for example,
   http://geant4.slac.stanford.edu/Presentations/vis/G4OpenGLTutorial/G4OpenGLTutorial.html
 	
   The detector has a default view which is a longitudinal view of the 
   calorimeter.
 	
   The tracks are drawn at the end of event, and accumulated to end of run.
   vis.mac shows how to draw and filter trajectories.
 	
   Additional visualization tutorial macros are available in the visTutor
   subdirectory.  They can be tried as:
               % $G4BINDIR/exampleN03
	       idle > /control/execute visTutor/exN03VisX.mac
   For details, see comment lines  described in the macro files.
   These macros are designed to help your understanding the User's Guide.


 5- PHYSICS DEMO
 
   The particle's type and the physic processes which will be available
   in this example are set in PhysicsList class.
 	
   In addition the build-in interactive command:
	         /process/(in)activate processName
   allows to activate/inactivate the processes one by one.
   Then one can well visualize the processes one by one, especially 
   in the bubble chamber setup with a transverse magnetic field.
   (see run2.mac and newgeom.mac)
 
   As a homework try to visualize a gamma conversion alone, 
   or the effect of the multiple scattering.
	
 6- RANDOM NUMBERS HANDLING
 
   CLHEP provides several random number engines. In this example the Ranecu
   engine is choosen at beginning of the main (exampleN03.cc).
	
   By default, G4RunManager does not save the rndm seed.
   To do so the user must set in BeginOfRunAction:
   G4RunManager::GetRunManager()->SetRandomNumberStore(true);
	
   Then the rndm seed is systematically saved at beginning of run
   (currentRun.rndm) and beginning of event (currentEvent.rndm)
   Therefore, in case of abnormal end, the seed of the last event processed
   is available in currentEvent.rndm
	
   Even in case of normal run processing, the user may wish to preserve the
   rndm seed of selected events. At any time in the event, put the
   following statement:
   if (condition) G4RunManager::GetRunManager()->rndmSaveThisEvent();
   currentEvent.rndm will be copied to runXXevntYY.rndm
   (see ExN03SteppingAction::UserSteppingAction() )
	
   To restart a run from a given rndm seed, use the UI command :
   /random/resetEngineFrom  fileName 
	
   The macro rndmSeed.mac shows how to save and reset the random number
   seed between runs, from UI commands.	
	
 7- USER INTERFACES
  
   The default command interface, called G4UIterminal, is done via
   standart cin/G4cout.
   On Linux and Sun-cc on can use a smarter command interface G4UItcsh.
   It is enough to set the environment variable G4UI_USE_TCSH
	
   On can use a Motif driven command interface (called G4UIXm) if:
    1- interfaces category has been compiled with G4UI_BUILD_XM_SESSION
    2- exampleN03.cc has been compiled with G4UI_USE_XM. 
 
      	
 8- HOW TO START ?
 
   - compile and link to generate an executable
 		% cd N03
 		% gmake
 		
   - execute N03 in 'batch' mode from macro files
 		% exampleN03   run1.mac
 		
   - execute N03 in 'interactive mode' with visualization
 		% exampleN03
 		....
 		Idle>      ---> type your commands. For instance:
		Idle> /run/beamOn 
		....
		Idle> /run/beamOn 10
		....				
 		Idle> /control/execute newgeom.mac
 		....
 		Idle> exit

 9- HISTOGRAMS
 
   There is no histograms in novice examples. For N03 + histograms, see
   examples/extended/analysis/AnaEx01 
   See also a more complete version of example N03 in 
   examples/extended/electromagnetic/TestEm3