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

                            electronScattering2   
                            ------------------

 Electron scattering benchmark variant 2 (Joseph Perl)

The two examples, electronScattering and electronScattering2 demonstrate how two alternate
approaches can be taken to simulating the same electron scattering benchmark experiment.

ElectronScattering2 simulates the experiment with a minimum of user code, whereas the other
version of this example shows how to do more of the work directly as the user.
In ElectronScattering2:
Primary generation relies on the G4GeneralParticleSource.
Material definitions are taken from the NIST database.
Visualization uses the standard G4VisExective.
Scoring is handled by the ready-made Geant4 scorer, G4PSCellFlux.

Both electronScattering and electronScattering2 simulate a precision electron scattering benchmark
experiment performed at NRCC Canada and published as:
"Measurement of multiple scattering of 13 and 20 MeV electrons by thin foils,"
by C. K. Ross, M. R. McEwen, A. F. McDonald, C. D. Cojocaru and B. A. Faddegon,
Med. Phys. Volume 35, Issue 9, pp. 4121-4131 (September 2008), DOI: 10.1118/1.2968095

The experiment represents the most accurate benchmark of its type.

A schematic of the experimental setup is shown in NRCC_electron_scat.pdf

The experimental data was itself published, as document number E-MPHYA6-35-034809 at http://www.aip.org/pubservs/epaps.html

The testing of three Monte Carlo simulation codes against this experimental benchmark has been
publshed as:
"The accuracy of EGSnrc, Geant4 and PENELOPE Monte Carlo systems for the simulation of electron 
scatter in external beam radiotherapy,"
by Bruce A Faddegon, Iwan Kawrakow, Yuri Kubyshin, Joseph Perl, Josep Sempau and Laszlo Urban,
Phys. Med. Biol. 54 (2009) 61516163, DOI:10.1088/0031-9155/54/20/008 

This present example, electronScattering2, was the Geant4 code used for this publication.

	
 1- GEOMETRY DEFINITION
 
 The geometry is described in the enclosed documument: NRCC_electron_scat.pdf
 - A "World" volume contains an Exit Window, Primary Foil, Monitor Chamber and Helium Bag.
 - The Helium Bag contains a Gas volume, which in turn contains 2 aluminium Rings
 - A scoring cylinder is defined near the end of the World.
 	
 The default geometry is constructed in the DetectorConstruction class.
 The parameters of the Primary Foil (material and thickness) are defined from macro commands.
 

 2- PHYSICS LIST
 
 Physics lists can be any of four options given in the G4 kernel
 physics_lists subdirectory, geant4/source/physics_lists/builders:	 
 - "emstandard_opt0"  recommended standard EM physics for HEP such as Large Hadron Collider
 - "emstandard_opt1"  best CPU performance standard physics for Large Hadron Collider
 - "emstandard_opt2"  latest experimental EM physics
 - "emstandard_opt3"  recommended for precision medical electron accelerator studies    
    
 Physics lists and options can be (re)set with UI commands
    
 Note that options set through G4EmProcessOPtions are global, eg for all particle types.
 In G4 builders, it is shown how to set options per particle type.

       	
 3- PRIMARY GENERATOR
 
 All of the work of the primary event generation is deferred to the G4GeneralParticleSource.
 The specific characteristics of the source are configured from the macro file, using
 /gps commands.
 Energy is set to either 13 or 20 MeV.
 Particle type is set to electron.
 Direction is set exactly orthogonal to the scattering foil.
 Source type is set to beam.
 Spatial distribution of the beam is set as a circle gassian sigma_r of 0.042 cm

 
 4- VISUALIZATION
 
 Visualization is controlled by the standard G4VisExecutive.
 The standard set of visualization options is supported.
 Example macros use HepRepFile. 	
  	

 5- SCORING
  	
 All of the work of the scoring is done by the standard Geant4 scorers, G4PSCellFlux and G4PSPopulation.
 Flux and population are scored in concentric rings at the scoring surface.
 Flux is corrected for ring area just before output (as PSCellFlux assumes the area is the complete
 area of the face of the cylinder, not the area of the one ring).


 6- MACROS

 Macros are provided for all of the 37 different combinations of scattering foils and beam energies
 that were used in the actual experiment.
 Separate directories of these macros are provided for the different EM Physics options, Opt0, 1, 2 and 3.

 	
 7- HOW TO START
 
 - execute electornScattering2 in 'batch' mode from macro files:
 	% electronScattering2 <macro_file> <starting_seed> <output_file>

 - for example, to run the Al1_13MeV case with physics option 2 and a starting random seed of 1:
 	% electronScattering2 macros/Opt2/Al1_13MeV.mac 1  output/Opt2/Al1_13MeV_1

 - if macro_file is not specfied, the job starts and then just waits for interactive commands
 
 - if starting_seed is not specified, it defaults to 1.
   Precision benchmark studies often involve running multiple long batch jobs and then combining the results.
   If you plan to combine more than one job with the same primary foil and energy, be sure to use different
   random seeds for each of the jobs.

 - if output_file is not specified, it defaults to output.csv in the current directory

 - to simplify batch submission of large numbers of jobs, a shell script is given called run.csh.
   The above submission could be done, for example, by:
	run.csh Opt2/Al1_13MeV 1

 - to run a basic visualization job, producing output to a HepRep file, use vis.mac, as in:
 	% electronScattering2 macros/vis.mac


 8- OUTPUT
	
  Results are given as comma-separated values (csv) files.
  The first column gives the CellFlux for all particles.
  The second column gives the CellFlux counting only electrons.
  The third column gives the population for all particles.
  The fourth column gives the populatin counting only electrons.
