
	     =========================================================
 		      	    Geant4 - Hadrontherapy example
     	     =========================================================


                                README file
                           ----------------------


Last revsion: G.A.P.Cirrone, November 2008;


                                    ACTUAL AUTHORS 

G.A.P. CIRRONE(*), G.CUTTONE, F. DI ROSA, F.ROMANO, G.RUSSO
M.RUSSO

Laboratori Nazionali del Sud - Istituto Nazionale di Fisica Nucleare
95123 Catania, Italy
* e-mail:cirrone@lns.infn.it

S.Guatelli
Istituto Nazionale di Fisica Nucleare, Sezione di Genova Via Dodecaneso, 33
16146, Genova, Italy

A. LECHNER (c)
CERN, Switzerland

                                   PAST AUTHORS

M.G. PIA
Istituto Nazionale di Fisica Nucleare, Sezione di Genova Via Dodecaneso, 33
16146, Genova, Italy


More informations on the Hadrontherapy example can be found in the 
Hadrontherapy Documentation available at http://geant4infn.wikispaces.com/HadrontherapyExample.

Alternatevely send an e-mail to cirrone@lns.infn.it.


----> 0. INTRODUCTION.                                                    
                                                                       
The hadrontherapy example simulates an hadron-therapy beam line. 
In particular the example models the specific proton therapy beam line
installed at Laboratori Nazionali del Sud (INFN) in Catania, Sicily (Italy).
For more information on the proton therapy center of Catania
or/and proton/hadron therapy in general, please visit the
pages:
http://www.lns.infn.it/catanaweb/catana/ 

Moreover, since the Release of December 2008, with this example is also possible the 
simulation of carbon ion beams as the correct physic models are inserted with the
builted-in physic list denominated "QGSP_BIC".

---->1. GEOMETRY SET-UP.
 
The elements simulated are:

1. A scattering system, to spread geometrically the beam;

2. A system of collimators, to avoid the scattering radiation;

3. A modulation system that spreads the beam in energy and
   produces the so-called spread out bragg peak;
   It is constituted by a rotating wheel of different thichnesses.
   The wheel rotates around is axis (parallel to the proton
   beam axis) and its movement can be obtained by means of a 
   messenger between runs.

4. A set of monitor chambers (special transmission ionisation 
   chambers used to control hadron flux during the irradiation);

5. A "nozzle" and a final collimator defining the final shape
   of the beam before reaching the patient.

6. A water phantom: it is a box of water where the energy deposit is 
   calculated.
   The use of  the water phantom is required by the international protocol
   on the measure of dose in the case of proton and ion beams (IAEA 398, 2000).


-------> 2. PHYSICS

A particular care is addressed to the simulation of the physic processes.

The User (since the December 2009 release) has the possibility to choice between two main
approaches to insert the physic models: 

Approach 1. The User can individually and selectively define all the models via macro command;
            
Approach 2. The User can choice a "built-in" physic package containing all the needed 
            models for the transport of proton and ion in the typical hadron-therapy range. 
            This second approach make the definition of the physic models simpler.  
            Developers strongly suggest the use of this second approach for Users are not
            specifically interested in the test of a specific physic model. Moreover they
            also suggest to send them results of comparison and report problems. This will
            permit the improvment of the overall quality of the implemented physic.

-------------------------------------  Approach 1  ----------------------------- 

With this apprach, at moment, inelastic models can be swiched-on only for neutrons
and protons. The activation of inelastic nucleus-nucleus models will be provided in 
the next release.

** Both electromagnetic and hadronic physic processes can be activated for 
   the particles of the experimental set-up.
   The different physics models can be activated by the user interactively via commands
   that can be inserted in the macro files

** Examples of activation are provided in the numerous macro files starting
   with the string "physics":

** All possible physics options are summarized in the file 
   physicsAllOptions.mac.

** Different options concerning electromagnetic interactions of protons
   and neutrons can be tested with the files: 
   physicsElectromagneticStandard.mac
   
   physicsElectromagneticICRU49.mac
   physicsElectromagneticZiegler77.mac
   physicsElectromagneticZiegler85.mac

** Different options concerning hadronic interactions of protons and
   neutrons can be tested with the files: 

   physicsHadronicBertini.mac
   physicsHadronicBinary.mac
   physicsHadronicLEP.mac
   physicsHadronicPrecompound.mac

NOTE: Apart from the different models for protons and neutrons, a user
can also select among several interaction models for particles like
electrons or photons. All possible options are listed in the file
physicsAllOptions.mac.

----------------------------------------------------------
SUGGESTED PHYSIC FOR PROTON BEAMS IN THE RANGE 0 - 400 MeV
----------------------------------------------------------

Developers of hadrontehrapy suggest to the Users want follow the Approach 1, the use of 
the following physic configuration for the
various processes (command must be inserted in a .mac file):

Electromagnetic processes:
/physics/addPhysics EM-Photon-EPDL (or) /physics/addPhysics EM-Photon-Standard
/physics/addPhysics EM-Electron-EEDL (or) /physics/addPhysics EM-Electron-Standard
/physics/addPhysics EM-HadronIon-LowE (or) /physics/addPhysics EM-HadronIon-Standard
/physics/addPhysics EM-Positron-Standard
/physics/addPhysics EM-Muon-Standard

Hadronic elastic processes:
/physics/addPhysics HadronicEl-HadronIon-UElastic

Hadronic inelastic processes:
/physics/addPhysics HadronicInel-ProtonNeutron-Prec  

-------------------------------------  Approach 2  ----------------------------- 
We developed this approach in order to semplify the choice of the physic models to 
be used in the application.
**  With this approach the user must only insert a command line in his/her .mac file
    (using the /physics/addPackage PACKAGE_NAME).
    This permits to switch-on an already build physic package.

** Various packages are already present in the Geant4 tree: they are in the directory:
   geant4/source/physics_lists/lists/include

** In this case hadronic inelastic models are directly activated for every particle.

------------------------------------------------------------------
SUGGESTED PHYSIC FOR PROTON AND ION BEAMS IN THE RANGE 0 - 400 MeV
------------------------------------------------------------------
Developers of Hadrontherapy suggest the use of the "QGSP_BIC" package for the correct simulation 
of proton and ion transposrt in the typical hadrontherapy energy range. This package 
can be inserted with one simple command in the .mac file:
/physics/addPackage QGSP_BIC

An example of macro file for the use of Approach 2 is: packageQGSP_BIC.mac 


Developers are improving the quality of the packages and validation results will be soon provided 
in a dedicated web page



------->2. EXPERIMENTAL SET-UP.      
                                      
The application simulates the proton therapy beam line
installed at Laboratori Nazionali del Sud.
The default beam line is a typical treatment line composed by several elements all
devoted to create the so-called "terapeutical beam", i.e. a beam ideal 
for a radiotherapeutic treatment.

   The main elements are:
** The COLLIMATORS: placed along the beam line to collimate the beam;

** The RANGE SHIFTERS: to decrease the energy of the primary proton beam 
   to a specific value;

** The MODULATOR WHEEL: to modulate the energy of the primary and monoenergetic
   beam in to a wide spectrum. The energy modulation is necessary to 
   homogeneusly irradiate a tumour volume that can extends in depth 
   up to 20 mm;

** The MONITOR CHAMBERS: very thin ionisation chamber that permit the 
   dose monitoring during the patient irradiation;

** The MOPI detector: microstrips, air free detector utilised for the check of the beam symmetry
   during the treatment

** The PATIENT COLLIMATOR: a brass, tumour-shaped collimator able to 
   confine the proton irradiation field in order to irradiate just the tumour mass
   in the trasverse direction;

The user has the possibility to vary, via messenger, almost all the geometrical 
characteristics of the beam line elements (i.e. their position along the beam line, 
their thickness, etc.). More details on the available user messengers can be 
found in the Hadronterapy Documentation (http://geant4infn.wikispaces.com/HadrontherapyExample).

At the end of the beam line, a typical water phantom is reproduced.
A user-defined region of the phantom is divided (via the ROGeomtry class) in 
cubic and identical voxels. The voxels size can be varied. At the end of the simulation 
the energy deposited by primary protons, and secondaries in each voxel
is collected. This information is available as an .hbk file (if the 
G4ANALYSIS_USE variable is defined).  

The default sizes of the active voxelized region are 40x40x40 mm corresponding
to a matric of 80x80x80 cubic voxels each with a lateral dimension of 0.5 mm. 

------->3. SET-UP 
                                                                        
- a standard Geant4 example GNUmakefile is provided                     

setup with:                                                             
compiler = gcc-3.4.6
G4SYSTEM = linux-g++                                                    

The following section reports the necessary environment variables 
necessary for the run of Hadrontherapy.                     

------->3.1  ENVIROMENT VARIABLES

 - G4SYSTEM = Linux-g++

 - G4INSTALL              points to the installation directory of GEANT4;

 - G4LIB                  point to the compiled libraries of GEANT4;

 - G4WORKDIR              points to the work directory;

 - CLHEP_BASE_DIR         points to the installation directory of CHLEP; 

 - G4LEVELGAMMADATA       points to the photoevaporation library;

 - NeutronHPCrossSections points to the neutron data files;

 - G4RADIOACTIVEDATA      points to the libraries for radio-active decay 
                          hadronic processes;

 - G4ABLADATA             points to the library of the INCL/ABLA hadronic model;
 
 - G4LEDATA               points to the low energy electromagnetic libraries

 - LD_LIBRARY_PATH = $CLHEP_BASE_DIR/lib

---->3.2  VISUALISATION

The user can visualise the experimental set-up with OpenGL, DAWN and vrml

---->4. HOW TO RUN THE EXAMPLE                                         

In interactive mode:
> $G4WORDIR/bin/Linux-g++/Hadrontherapy
The defaultMacro.mac is executed

The primary particle beam parameter are:
Radiation:                proton beam;
Energy distribution:      gaussian;
Mean energy:              64.0 MeV;
Energy spread:            300 keV;
Beam spot size:           1 mm;
Beam angular spread:      0.0 deg;

The modulator wheel can be rotated via the messenger:

Idle>/modulator/angle/xx deg

To produce a Spread Out Bragg Peak using the modulator a macro
(modulatorMacro.mac) is provided. With this macro the modulator is 
rotated of 360 degree at 1 deg steps. In each run 1000 protons are
generated as primary particles. Obviously a bigger resolution can be obtained 
with smaller angles or increasing the protons number in each run.

Modulator wheel can be omitted setting its material air.

run $G4WORKDIR/bin/Linux-g++/Hadrontherapy visualisationMacro.mac
to visualise the experimental set-up with OpenGL

---->6. SIMULATION OUTPUT                                    

The output is an .hbk file and a .root files. The files are  produced 
if the variable G4ANALYSIS_USE is set to 1 and the analysis tool (AIDA
interface) correctly installed.
The file contains  histograms and n-tuples.
The histograms contain the Bragg curves: energy deposited 
versus the depth in water (in mm) for the primary beam as well as all the secondaries produced. 
The n-tuple contains the total 3D energy deposit in the phantom; the information
is energy deposit in each voxel with respect to the position of the voxel.

Setup for analysis: AIDA 3.2.1  

Users can download the analysis tools from:  
http://aida.freehep.org/

Note that the same information can be stored in different format, 
like .root or .xml using the same AIDA interface.
Alternatively users that are more confident with ASCII format, can derive
their table with energy deposited in each voxel working inside the 
HadrontherapyMatrix.

Please contact cirrone@lns.infn.it for more details.

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

for comments, advices, doubts and questions please contact: 
cirrone@lns.infn.it

last modified: G.A.P. Cirrone, 20/11/2008

