geant4/examples/extended/medical/fanoCavity2/README

$Id: README,v 1.8 2007/11/12 18:19:30 maire Exp $
-------------------------------------------------------------------

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

                            fanoCavity2
                            -----------

    This program computes the dose deposited in an ionization chamber by an
    extended (one dimensional) monoenergetic electron source.
    The geometry of the chamber satisfies the conditions of charged particle
    equilibrium. Hence, under idealized conditions, the ratio of the dose 
    deposited over the beam energy fluence must be equal to 1.
    This variante of the Fano cavity test make use of an reciprocity theorem.
    
    J.Sempau and P.Andreo, Phys. Med. Biol. 51 (2006) 3533        
	
 1- GEOMETRY
 
    The chamber is modelized as a cylinder with a cavity in it.
     	
    5 parameters define the geometry :
      - the radius of the chamber (must be big)
      - the material of the wall
      - the thickness of the wall
      - the material of the cavity
      - the thickness of the cavity

    Wall and cavity must be made of the same material, but with different
    density.
    Radius must be bigger than range of electrons in cavity. 	 	
 	
    All above parameters can be redifined via the UI commands built in 
    DetectorMessenger class.
    
			_________________
     radius (infinite)	|     |   |	|
			|     |   | 	|    
			|     |   |	|
			|     |   | 	|      
	   		|     | <-+-----+--- cavity     
	     		|     |   | 	|
	     		|     |   | 	|
		---------------------------- cylinder axis = e- source
	     	  	|     |   | 	|
	     	  	|     |   | 	|
		  	|     |   | 	|
		  	|wall |   |wall |
		  	|     |   |	|			
		  	|     |   |	|
		  	|     |   |	|
		  	-----------------
			
 2- BEAM
  
    Monoenergetic (E0) incident electron source is uniformly distribued along
    cylinder axis, within wall and cavity, with constant lineic density
    per mass: I.
    An effective wall thickness is defined from the range of e- at energy E0.
     
    Beam_energy_fluence is E0*I
    
 3- PURPOSE OF THE PROGRAM
    
    The program computes the dose deposited in the cavity and the ratio
    Dose/Beam_energy_fluence. This ratio must be 1.
 
    The program needs high statistic to reach precision on the computed dose.
    The UI command /testem/event/printModulo allows to survey the convergence of
    the dose calculation.
    
    The simplest way to study the effect of e- tracking parameters on dose 
    deposition is to use the command /testem/stepMax.
    	 			 	
 4- PHYSICS
 
    The physics list contains the standard electromagnetic processes, with few 
    modifications listed here.
    
    - Bremsstrahlung : Fano conditions imply no energy transfer via
    bremsstrahlung radiation. Therefore this process is not registered in the
    physics list. However, it is always possible to include it via an UI
    command. See PhysicsListMessenger class.
    
    - Ionization : In order to have same stopping power in wall and cavity, one
    must cancel the density correction term in the dedx formula. This is done in
    a specific MollerBhabha model (MyMollerBhabhaModel) which inherites from 
    G4MollerBhabhaModel.
    
    To prevent explicit generation of delta-rays, the default production
    threshold (i.e. cut) is set to 10 km (CSDA condition).
    
    The finalRange of the step function is set to 10 um, which more on less
    correspond to a tracking cut in water of about 20 keV. See emOptions.
    Once again, the above parameters can be controled via UI commands.
    
    - Multiple scattering : is switched in single Coulomb scattering mode near
    boundaries. This is selected via EM options in PhysicsList, and can be
    controled with UI commands.
    
    - All PhysicsTables are built with 100 bins per decade.  
     	
 5- HISTOGRAMS
 
   fanoCavity2 has several predefined 1D histograms : 
  
      1 : emission point of e+-
      2 : energy spectrum of e+-
      3 : theta distribution of e+-
      4 : emission point of e+- hitting cavity
      5 : energy spectrum of e+- when entering in cavity
      6 : theta distribution of e+- before enter in cavity
      7 : theta distribution of e+- at first step in cavity      
      8 : track segment of e+- in cavity
      9 : step size of e+- in wall
     10 : step size of e+- in cavity
     11 : energy deposit in cavity per track
                
   The histograms are managed by the HistoManager class and its Messenger. 
   The histos can be individually activated with the command :
   /testem/histo/setHisto id nbBins  valMin valMax unit 
   where unit is the desired unit for the histo (MeV or keV, deg or mrad, etc..)
   
   One can control the name of the histograms file with the command:
   /testem/histo/setFileName  name  (default fanoCavity)
   
   It is possible to choose the format of the histogram file (hbook, root, XML)
   with the command /testem/histo/setFileType (hbook by default)
   
   It is also possible to print selected histograms on an ascii file:
   /testem/histo/printHisto id
   All selected histos will be written on a file name.ascii (default fanocavity2) 
       
   Note that, by default, histograms are disabled. To activate them, uncomment
   the flag G4ANALYSIS_USE in GNUmakefile.
 	
 6- HOW TO START ?
 
 	- compile and link to generate an executable
 		% cd geant4/examples/extended/medical/fanoCavity2
 		% gmake
 		
 	- execute fanoCavity2 in 'batch' mode from macro files
 		% fanoCavity2   run01.mac
 		
 	- execute fanoCavity2 in 'interactive mode' with visualization
 		% fanoCavity2
 		....
 		Idle> type your commands
 		....
 		Idle> exit
		 
 7- USING HISTOGRAMS

  To use histograms, at least one of the AIDA implementations should be 
  available (see http://aida.freehep.org).
  
 8a - PI 

  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 running the example the command should be issued:
  eval `aida-config --runtime csh`

 8b -  OpenScientist

  OpenScientist is available at http://OpenScientist.lal.in2p3.fr.

  You have to "setup" the OpenScientist AIDA implementation before compiling
  (then with G4ANALYSIS_USE set) and running your Geant4 application.

 On UNIX you setup, with a csh flavoured shell : 
	csh> source <<OpenScientist install path>/aida-setup.csh 
        or with a sh flavoured shell : 
	sh> . <<OpenScientist install path>/aida-setup.sh
 On Windows : 
	DOS> call <<OpenScientist install path>/aida-setup.bat 

  You can use various file formats for writing (AIDA-XML, hbook, root).
  These formats are readable by the Lab onx interactive program
  or the OpenPAW application. See the web pages.


  With OpenPAW, on a run.hbook file, one can view the histograms
  with something like :
	OS> opaw 
        opaw> h/file 1 run.hbook  ( or opaw> h/file 1 run.aida or run.root)  
	opaw> zone 2 2 
	opaw> h/plot 1 
	opaw> h/plot 2