Ignore:
Timestamp:
Jun 14, 2010, 3:54:58 PM (14 years ago)
Author:
garnier
Message:

geant4.9.4 beta rc0

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/examples/advanced/hadrontherapy/README

    r807 r1313  
    11
    2      =========================================================
    3                   Geant4 - Hadrontherapy example
    4      =========================================================
    5 
    6                                 README file
    7                           ----------------------
    8 
    9                                    AUTHORS
    10 
    11 G.A.P. CIRRONE(a *), G.CUTTONE(a), F. DI ROSA(a), G.RUSSO(a)
    12 a. Laboratori Nazionali del Sud - Istituto Nazionale di Fisica Nucleare
    13    95123 Catania, Italy
    14 * e-mail:cirrone@lns.infn.it
    15 
    16 M.G. PIA(b)
    17 b. Istituto Nazionale di Fisica Nucleare, Sezione di Genova Via Dodecaneso, 33
    18    16146, Genova, Italy
    19 
    20 A. LECHNER (c)
    21 c. CERN, Switzerland
    22 
    23 More informations on the Hadrontherapy example can be found in the
    24 Hadrontherapy Documentation available at http://www.ge.infn.it/geant4/examples/
    25 
    26 Alternatevely send an e-mail to cirrone@lns.infn.it.
    27 
    28 
    29 ---->0. INTRODUCTION.                                                   
    30                                                                        
    31 The hadrontherapy example simulates a hadron therapy beam line.
    32 In particular the example models the specific proton therapy beam line
    33 installed at Laboratori Nazionali del Sud (INFN) in Catania, Sicily (Italy).
    34 For more information on the proton therapy center of Catania
    35 or/and proton/hadron therapy in general, please visit the
    36 pages:
    37 http://www.lns.infn.it/catanaweb/catana/
    38 
    39 ---->1. GEOMETRY SET-UP.
     2             =========================================================
     3                     Text version of the Hadrontherapy README file
     4             =========================================================
     5
     6Last revsion: G.A.P.Cirrone, November 2009;
     7Released with the Geant4 9.3 version (December 2009)
     8
     9------------------------------------------------------------------------------------------------
     10ADVERTISEMENT: this is the text version of the README file of the hadrontherapy application,
     11as it has been released in the official Geant4 9.3 release
     12
     13A more complete and updated version of this file is published inside the web pages of Hadrontherapy:
     14http://g4advancedexamples.lngs.infn.it/Examples/hadrontherapy
     15
     16Please refer to the web-published version to know the last and future developments of hadrontherapy
     17-------------------------------------------------------------------------------------------------
     18
     19             =========================================================
     20                                HADRONTHERAPY
     21             =========================================================
     22
     23 Code developed by:
     24 G.A.P. Cirrone(a)°, G.Cuttone(a), F.Di Rosa(a), S.E.Mazzaglia(a), F.Romano(a)
    4025 
    41 The elements simulated are:
     26 Contributor authors:
     27 P.Kaitaniemi(d), A.Heikkinen(d), G.Danielsen (d)
     28
     29 Past authors:
     30 M.G.Pia(b), S.Guatelli(c), G.Russo(a), M.Russo(a), A.Lechner(e)
     31
     32 (a) Laboratori Nazionali del Sud
     33     of the INFN, Catania, Italy
     34
     35 (b) INFN Section of Genova, Italy
     36 
     37 (c) University of Wallongong, Australia
     38
     39 (d) Helsinki Institute of Physics, Helsinki, Finland
     40
     41 (e) CERN, (CH)
     42
     43  *Corresponding author, email to cirrone@lns.infn.it
     44-------------------------------------------------------------------------------------------------
     45
     46HADRONTHERAPY:
     47WHAT IT IS, WHAT IT DOES AND WHAT IT WILL PROVIDE          
     48Hadrontherapy is a Geant4-based application specifically developed to address typical needs related to the proton and ion therapy. 
     49It first release was in 2004. At that time Hadrontherapy was only capable to simulate a well specified proton therapy facility: the passive transport beam line installed at  Laboratori Nazionali del Sud (INFN) in Catania, Italy.
     50
     51Today Hadrontontherapy, except that it is in continuous development, is more flexible and show many additional capabilities as respect the past.
     52Its geometrical set-up, for example, is now completely interchangeable permitting a simple switch between different geometrical configurations.
     53In the actual version two geometrical configuration are available: the 'passive beam line'
     54and the 'IAEA Benchmark' geometry. See the paragraph Geometry set-up for more information.
     55Folder structure of Hadrontherapy
     56Hadrontherapy distribution contain different sub-folders:
     57
     58\src: where source .cc files are stored
     59\include: where header .hh files are stored
     60\macro: where a set of ready-to-use macro files are provided
     61\experimentalData: in this director a set of reference (both experimental and analithycal) data are stored. These data are then used to perform a direct comparison with simulation results that are stored in the simulationResults folder. Data stored are better described in the README file contained inside.
     62\SimulationOutputs: when one of the .mac file contained in the macro folder is used, simulation results are directly stored in this directory.
     63\RootScripts: if the ROOT program is installed the User can use the scripts contained in this directory to compare directly results from the his/her simulation with reference data provided inside the experimentalData folder.
     64
     65Currently this folders structure is in development and reference data as well as ROOT scripts will be added in the meanwhile new features and capabilities will be added. Moreover some ROOT script can be missed. Apologize for this and contact author if you need more information, clarification or useful discussion.
     66Description of the \macro folder
     67In the example directory, inside the "macro" folder two macro files are actually provided for the use of hadrontherapy with proton and carbon beams: proton_therapy.mac and ion_therapy.mac.
     68The proton_therapy.mac permits to run a simulation with the whole passive beam line installed in Catania.
     69The carbon_therapy.mac excludes all the elements (moving the origin of the ion beam close to the water phantom) and reproduce a simple passive beam line for the use with carbon beams.
     70The macro iaea.mac uses an alternative geometry that was created for the IAEA benchmark. It features a geometry with water target, aluminum beam window, and a particle detector behind the target.
     71
     72
     73DOWNLOAD AND INSTALLATION
     74Hadrontherapy source code is actually released inside the official distribution of the Geant4 toolkit in the $G4INSTALL/examples/AdvancedExamples folder.
     75
     76To run Hadrontherapy you must first install the Geant4 package. Once Geant4 is installed the example must be first compiled (with the command gmake inside the
     77../Hadrontherapy folder). When compilation is completed the program can be executed.
     78
     79A complete guide for the Geant4 installation in different operating systems can be found inside the official installation Geant4 pages.
     80
     81If you have troubles with the Geant4 installation please send an e-mail to us.
     82
     83
     84SISTEM SET-UP: enviroment variables
     85A standard Geant4 example GNUmakefile is provided                                                         
     86
     87The following section reports the environment variables that are necessary for the run of Hadrontherapy.
     88#-------------------------------------
     89#    SET UP LINUX  GCC
     90#-------------------------------------
     91
     92VERSION="geant4-09-03"
     93
     94# Path to the directory in wich you have put data files and CLHEP
     95LIBPATH=$HOME/Geant4Library
     96
     97export G4SYSTEM=Linux-g++
     98
     99# Path to the directory in wich you put your Geant4 installation
     100export G4INSTALL=$HOME/${VERSION}
     101
     102export G4LIB=$G4INSTALL/lib
     103export G4WORKDIR=$G4INSTALL/workdir
     104export G4EXE=$G4WORKDIR/bin/$G4SYSTEM
     105
     106export CLHEP_BASE_DIR=$LIBPATH/CLHEP2.0.4.5
     107export G4LEDATA=$LIBPATH/G4EMLOW6.9
     108export G4LEVELGAMMADATA=$LIBPATH/PhotonEvaporation2.0
     109export G4NEUTRONHPDATA=$LIBPATH/G4NDL3.13
     110export G4RADIOACTIVEDATA=$LIBPATH/RadioactiveDecay3.2
     111export G4ABLADATA=$LIBPATH/G4ABLA3.0
     112
     113export LD_LIBRARY_PATH=$CLHEP_BASE_DIR/lib:$LD_LIBRARY_PATH
     114
     115# For the generation .root file directly using the ROOT (if ROOT is
     116# instaled in you machine)
     117export G4ANALYSIS_USE_ROOT=1
     118export LD_LIBRARY_PATH=$ROOTSYS/lib:$LD_LIBRARY_PATH
     119
     120#-------------------------------------
     121#    SET UP    VRML VIEW
     122#-------------------------------------
     123export G4VIS_BUILD_VRML_DRIVER=1
     124export G4VIS_USE_VRML=1
     125export G4VIS_USE_VRMLFILE=1
     126export G4VRMLFILE_MAX_FILE_NUM=100
     127export G4VRMLFILE_VIEWER=vrmlview    #if installed
     128
     129# Add path to your VRML installation
     130export PATH=$PATH:~/VRML
     131
     132#-------------------------------------
     133#    SET UP    OpenGL o Mesa
     134#-------------------------------------
     135export G4VIS_BUILD_OPENGLX_DRIVER=1
     136export G4VIS_USE_OPENGLX=1
     137    
     138# Add path to your OpenGL installation
     139#export OGLHOME=/usr/lib
     140
     141
     142#-------------------------------------
     143#    SET UP    DAWN (if installed)
     144#-------------------------------------
     145export G4VIS_BUILD_DAWN_DRIVER=1
     146export G4VIS_BUILD_DOWNFILE_DRIVER=1
     147export G4VIS_USE_DAWN=1
     148export G4VIS_USE_DAWNFILE=1
     149# Add path to your DAWN installation
     150# export PATH=$PATH:~/dawn_3_86a
     151
     152# VARIOUS USER INTERFACES
     153export G4UI_USE_XM=1
     154export G4UI_USE_TCSH=1
     155export G4UI_BUILD_QT_SESSION=1
     156export G4UI_USE_QT=1
     157
     158# VARIOUS GRPHICAL USER INTERFACES
     159export G4VIS_BUILD_QT_SESSION=1
     160export G4VIS_BUILD_OPENGLQT_DRIVER=1
     161export G4VIS_USE_OPENGLQT=1
     162
     163# If the QT libraries want be used for the User interfaces than the
     164# correct path must be addressed
     165export QTHOME=/usr/lib/qt-3.3
     166export PATH=$PATH:/usr/lib/qt-3.3/include/
     167export PATH=$PATH:/usr/lib/qt-3.3/
     168
     169GEOMETRICAL SET-UP
     170The idea of Hadrontherapy is to provide a tool useful for Users interested in the field of proton and ion therapy. These can include the simple calculation of dose distribution curves in water or other materials, the derivation of important transport parameters (stopping powers, ranges, etc.) in different geometrical set-ups and for different materials, up to the complete simulation of a real transport beam line for therapy.
     171
     172The main component of the simulation is the phantom, a box that can be filled with different material and where the score of different information (at moment  the dose deposited and fluence in voxels) can be performed. A more complete description of the phantom is given in the next subsection.
     173
     174At moment the Hadrontherapy include the simulation of the proton beam line for eye-treatments installed at the INFN-LNS facility in Catania. This is a passive beam line and it is simulated in the file PassiveProtonBeamLine.cc.
     175
     176In the next future an ActiveProtonBeamLine.cc will be provided for the simulation of the active scanning treatment modality.
     177Moreover the possibility to add a very simple set-up (a beam, a phantom where collect the informations and some simple component) will be also provided.
     178
     179All these configuration will be setted by macro commands.
     180
     181There is also a facility that allows the user to make a choice between alternative geometry set-ups. This can be done by using command:
     182/geometrySetup/selectGeometry <name>
     183where <name> is either "default" for the standard hadrontherapy geometry or "IAEA" for the IAEA benchmark geometry. Both geometries are described below. By default the standard "default" geometry is used.
     184The water phantom to collect informations
     185At the end of the beam line a phantom (a box of uniform material) is reproduced. Inside it, a user-defined region is divided (via the ROGeomtry classes of Geant4) in cubic and identical voxels. The voxels size can be varied as well as the voxelized region.
     186At the end of a simulation run the dose deposited by primaries and secondaries in each voxel is collected. This information is available as an .out file or as a .root (if the G4ANALYSIS_USE variable is defined and the AIDA interface is activated).  
     187
     188The default sizes of the active voxelized region are 40x40x40 mm and actually the default voxel configuration is 200 x 1 x 1, which means 200 slices with 0.2 mm of thickness.
     189Of course this default can be modified in order to obtain, for example, a matrix of 80x80x80 cubic voxels each with a lateral dimension of 0.5 mm.
     190
     191As concern the cut and stepMax values, the default configuration implies a cut value of 0.01 mm in the whole  world (use the command /physic/setCuts <length>  in order to set the cut for all, and the command /physic/setDetectorCuts <length> to set the cut for the detector only)  and a stepMax of 0.01 mm just in the phantom (use the command /Step/waterPhantomStepMax 0.01 mm).
     192In any case it is strongly recommended to use a stepMax value not bigger than 5% of the dose slice thickness.
     193The Proton passive beam line class file
     194The following is the description of the elements of the passive proton beam line of the Laboratori Nazionali del Sud in Catania (I). This line is completely simulated inside this class.
     195
     196The main elements are:
     197* The SCATTERING SYSTEM: to transversally enlarge the original beam
     198* The COLLIMATORS: placed along the beam line to collimate the beam;
     199* The RANGE SHIFTERS: to decrease the energy of the primary proton beam to a specific value;
     200* The MODULATOR WHEEL: to modulate the energy of the primary and mono-energetic beam in to a wide spectrum. The energy modulation is necessary to homogeneously irradiate a tumour volume that can extends in depth up to 20 mm;
     201* The MONITOR CHAMBERS: very thin ionisation chamber that permit the dose monitoring during the patient irradiation;
     202* The MOPI detector: microstrips, air free detector utilised for the check of the beam symmetry during the treatment;
     203* 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 transverse direction;
     204
     205The 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.).
     206
     207The elements simulated in the PassiveBeamLine.cc file are:
    42208
    432091. A scattering system, to spread geometrically the beam;
    … …  
    452112. A system of collimators, to avoid the scattering radiation;
    46212
    47 3. A modulation system that spreads the beam in energy and
    48    produces the so-called spread out bragg peak;
    49    It is constituted by a rotating wheel of different thichnesses.
    50    The wheel rotates around is axis (parallel to the proton
    51    beam axis) and its movement can be obtained by means of a
    52    messenger between runs.
    53 
    54 4. A set of monitor chambers (special transmission ionisation
    55    chambers used to control hadron flux during the irradiation);
    56 
    57 5. A "nozzle" and a final collimator defining the final shape
    58    of the beam before reaching the patient.
    59 
    60 6. A water phantom: it is a box of water where the energy deposit is
    61    calculated.
    62    The use of  the water phantom is required by the international protocol
    63    on the measure of dose in the case of proton and ion beams (IAEA 398, 2000).
    64 
    65 ---->2. EXPERIMENTAL SET-UP.     
    66                                      
    67 The application simulates the proton therapy beam line
    68 installed at Laboratori Nazionali del Sud.
    69 The default beam line is a typical treatment line composed by several elements all
    70 devoted to create the so-called "terapeutical beam", i.e. a beam ideal
    71 for a radiotherapeutic treatment.
    72 
    73    The main elements are:
    74 ** The COLLIMATORS: placed along the beam line to collimate the beam;
    75 
    76 ** The RANGE SHIFTERS: to decrease the energy of the primary proton beam
    77    to a specific value;
    78 
    79 ** The MODULATOR WHEEL: to modulate the energy of the primary and monoenergetic
    80    beam in to a wide spectrum. The energy modulation is necessary to
    81    homogeneusly irradiate a tumour volume that can extends in depth
    82    up to 20 mm;
    83 
    84 ** The MONITOR CHAMBERS: very thin ionisation chamber that permit the
    85    dose monitoring during the patient irradiation;
    86 
    87 ** The PATIENT COLLIMATOR: a brass, tumour-shaped collimator able to
    88    confine the proton irradiation field in order to irradiate just the tumour mass
    89    in the trasverse direction;
    90 
    91 The user has the possibility to vary, via messenger, almost all the geometrical
    92 characteristics of the beam line elements (i.e. their position along the beam line,
    93 their thickness, etc.). More details on the available user messengers can be
    94 found in the Hadronterapy Documentation (http://www.ge.infn.it/geant4/examples/).
    95 
    96 At the end of the beam line, a typical water phantom is reproduced.
    97 A user-defined region of the phantom is divided (via the ROGeomtry class) in
    98 cubic and identical voxels. The voxels size can be varied. At the end of the simulation
    99 the energy deposited by primary protons, and secondaries in each voxel
    100 is collected. This information is available as an .hbk file (if the
    101 G4ANALYSIS_USE variable is defined). 
    102 
    103 The default sizes of the active voxelized region are 40x40x40 mm corresponding
    104 to a matric of 80x80x80 cubic voxels each with a lateral dimension of 0.5 mm.
    105 
    106 ---->3. SET-UP
    107                                                                        
    108 - a standard Geant4 example GNUmakefile is provided                     
    109 
    110 setup with:                                                             
    111 compiler = gcc-3.2.3
    112 G4SYSTEM = linux-g++                                                   
    113 
    114 The following section reports the necessary environment variables
    115 necessary for the run of Hadrontherapy.                     
    116 
    117 ---->3.1  ENVIROMENT VARIABLES
    118 
    119  - G4SYSTEM = Linux-g++
    120 
    121  - G4INSTALL              points to the installation directory of GEANT4;
    122 
    123  - G4LIB                  point to the compiled libraries of GEANT4;
    124 
    125  - G4WORKDIR              points to the work directory;
    126 
    127  - CLHEP_BASE_DIR         points to the installation directory of CHLEP;
    128 
    129  - G4LEVELGAMMADATA       points to the photoevaporation library;
    130 
    131  - NeutronHPCrossSections points to the neutron data files;
    132 
    133  - G4RADIOACTIVEDATA      points to the libraries for radio-active decay
    134                           hadronic processes;
    135  
    136  - G4LEDATA               points to the low energy electromagnetic libraries
    137 
    138  - LD_LIBRARY_PATH = $CLHEP_BASE_DIR/lib
    139 
    140 ---->3.2  VISUALISATION
    141 
    142 The user can visualise the experimental set-up with OpenGL, DAWN and vrml
    143 
    144 ---->4. HOW TO RUN THE EXAMPLE                                         
    145 
    146 In interactive mode:
     2133. 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 thicknesses. The wheel  rotates around its axis (parallel to the proton beam axis) and its movement can be obtained by means of a messenger between runs.
     214
     2154. A set of monitor chambers (special transmission ionisation chambers used to control the particle flux during the irradiation);
     216
     2175. A final long collimator and a patient collimator defining the final shape of the beam before reaching the patient.
     218
     2196. A water phantom: it is a box of water where the dose 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).         
     220Geometry for the IAEA benchmark
     221Simple geometry for benchmark purposes contains water phantom (thickness can be set using a macro command), an aluminum beam window and Plexi-glass. Behind the phantom we have a detector that records outcoming particles. The IAEA geometry can be activated by using the command:
     222/geometrySetup/selectGeometry IAEA
     223
     224Example IAEA benchmark run can be done as follows:
     225run:        Hadrontherapy macro/iaea.mac
     226analysis: root RootScripts/iaeaBenchmark/fragmentEnergy.C
     227
     228PHYSICS PROCESSES AND PHYSICS MODELS IMPLEMENTATION
     229A particular care is addressed to the simulation of the physic processes.
     230Three different approaches can be used for the choose of the physic models.
     231Approach 1:
     232Using the macro command:
     233/physic/addPhysics/<physics List name>.
     234
     235In this case the models (for electromagnetic, hadronic elastic and hadronic inelastic) can be activated directly calling the name of the Physics Lists that are available inside the
     236Geant4 kernel in the directory:
     237
     238$G4INSTALL/source/physics_lists/builders/include
     239
     240An example of the use of the Physics List can be found in the macro files:
     241proton_therapy.mac and ion_therapy.mac
     242Approach 2:
     243A set of built-in physic models are also contained inside the Hadrontherapy directory. These are called Local*.cc and Local*.hh and can be activated using the macro command:
     244/physic/addPhysics/<name>.
     245Approach 3:
     246We developed this approach in order to simplify the choice of the physic models to
     247be used in the application.
     248With this approach the user must only insert a command line in his/her .mac file using the: /physics/addPackage <PACKAGE_NAME>
     249    
     250This permits to switch-on an already build physic package.
     251Various packages are already present in the Geant4 tree: they are in the directory: geant4/source/physics_lists/lists/include
     252
     253In this case hadronic inelastic models are directly activated for every particle.
     254
     255NOTE: we do not recommend the use of local physics lists while we recommend the use of the Physics Lists or of the Reference Physics Lists (Approach 1 or 3)
     256
     257--------------------------------------------------------------------------------
     258SUGGESTED PHYSIC FOR ION BEAMS IN THE RANGE 0 - 400 MeV
     259--------------------------------------------------------------------------------
     260Two macro files (proton_therapy.mac and ion_therapy.mac) can be used for proton and ion
     261simulations.
     262
     263Also the QGSP_BIC_EMY package can be used if the *Approach 3* is preferred.
     264
     265INTERACTIVE COMMANDS
     266How to change Phantom and Detector geometries
     267In order to let the end user to change phantom and detector geometries and voxelization, some interactive commands have been provided. All parameters are mandatory, except those inside square brackets.
     268
     269Detector geometry
     270
     271The user can change:
     272
     273(1) The detector (box) size.
     274 
     275(2) The voxels sizes. Changing this parameters, and/or the detector sizes, user should choose values in order to be divisors of the detector correspondent sizes.
     276For both above commands, zero or negative values mean << don't change it >>
     277
     278(3) The displacement between the phantom and the detector.  Displacement parameters refer to the lower left corner of the detector respect to that of the phantom, by the point of view of the beam. In this case zero or positive values are allowed, while the negatives ones mean: << don't change it>>.
     279
     280Command synopsis: the <default values> follow "#"
     281
     282
     2831. /changeDetector/size <dimX> <dimY> <dimZ> <[unit]> # 4 4 4 cm
     2842. /changeDetector/voxelSize <dimX> <dimY> <dimZ> <[unit]> # 0.2 40 40 mm
     2853. /changeDetector/displacement <dispX> <dispY> <dispZ> <[unit]> # 0 18 18 cm
     286
     287where the X dimension is that along the beam direction
     288
     289Phantom geometry
     290
     291(1) The phantom size. As usually, zero or negatives values mean: <<don't change it>>.
     292(2) The phantom position respect to the world. In this case specified values refer to the three components of the position of the phantom's center respect to the world's.
     293
     294Command synopsis:
     295
     2961. /changePhantom/size <dimX> <dimY> <dimZ> <[unit]> # 40 40 40 cm
     2972. /changePhantom/position <posX> <posY> <posZ> <[unit]> # 20 0 0 cm
     298
     299All these commands must be followed by the command /changePhantom/update
     300in order to check and apply them to the real geometry.
     301Moreover must be issued between runs (so where you want but after the /run/initialize initialization command, or the G4State_Idle Geant4 state machine).
     302Obviously all the previous sizes must be set in order to maintain the detector inside the phantom, otherwise system complains.
     303
     304 Some examples follow:
     305
     306/changeDetector/size 40 0 0 cm
     307# Will extend detector X size to cover in full the phantom X size  
     308
     309/changeDetector/size 0 4.5 0 cm
     310# Will extend the Y size to 4.5 cm (note that voxel size Y is automatically
     311#  rounded to 4.5 cm because the default value along Y is 4 cm)
     312/changePhantom/update
     313# Remember to always update the geometry before the beamOn command!!
     314
     315/changeDetector/size 0 8 0 cm
     316# Will extend the Y size to 8 cm. In this case voxel size Y doesn't change, but
     317# the number of voxel along Y doubles.
     318/changePhantom/update
     319
     320
     321/changeDetector/voxelSize 100 0 0 um
     322# 100 um should be a divisor of detector size X
     323# Will change only slabs X size to 100 um, without affecting the other.
     324/changePhantom/update
     325
     326/changeDetector/displacement 0 0 0 # default unit mm
     327# Will place the detector in the left lower corner (from the point of view of the beam) of #the  phantom.
     328/changePhantom/update
     329Stopping powers calculation
     330It is possible for the end-user to calculate, via macro command, stopping powers only for those materials inserted into G4NistMaterialBuilder class (about 300).
     331To get stopping powers user must provide this command line on the idle interactive terminal (or into a macro file) :
     332
     333/parameter/getstopping <G4_material> <Emin> <Emax> <nPoints> <[particle]> <[output_filename]>
     334
     335All parameters are mandatory except those inside square brackets [].
     336Default values for parameters inside square brackets are respectively proton and standard output (usually the user console terminal).
     337
     338Parameters are respectively:
     339
     340* The material (NIST) name (something like G4_..., the complete list of elements and materials is available into the G4NistMaterialBuilder class and can be printed  to the terminal screen via the macro command: /parameter/nist )
     341* Kinetic energy range in MeV and the number of data points to be retrieved (in a logarithmically uniform space)
     342* The particle name (proton, e+, e-, He3, neutron,... a full list can be gotten via the macro command: /particle/list).
     343         Only for ions, user must firstly give them to the particle gun, for example issuing the  macro commands:
     344a. /gun/particle ion
     345b. /gun/ion <Z> <A> <[charge]>
     346* The output filename: if users leave this blank then the standard output is used.
     347
     348Below is an example in order to calculate the stopping power for alphas into Hydrogen between 1 keV to 150 MeV for 15 points:
     349
     350/parameter/getstopping G4_H 0.001 150 15 alpha
     351
     352# and for C12 ion:
     353
     354/gun/particle ion
     355/gun/ion 6 12 6
     356/parameter/getstopping G4_H 0.001 150 15 C12[0.0]
     357
     358# Value inside square brackets is the excitation energy of the ion (ground state).
     359
     360HOW RUN HADRONTHERAPY
     361Run the example in interactive mode                                      
    147362> $G4WORDIR/bin/Linux-g++/Hadrontherapy
    148 The defaultMacro.mac is executed
    149 
    150 The primary particle beam parameter are:
    151 Radiation:                proton beam;
    152 Energy distribution:      gaussian;
    153 Mean energy:              63.4 MeV;
    154 Energy spread:            300 keV;
    155 Beam spot size:           1 mm;
    156 Beam angular spread:      0.057 deg;
    157 
    158 The modulator wheel can be rotated via the messenger:
    159 
    160 Idle>/modulator/angle/xx deg
    161 
    162 To produce a Spread Out Bragg Peak using the modulator a macro
    163 (modulatorMacro.mac) is provided. With this macro the modulator is
    164 rotated of 360 degree at 1 deg steps. In each run 1000 protons are
    165 generated as primary particles. Obviously a bigger resolution can be obtained
    166 with smaller angles or increasing the protons number in each run.
    167 
    168 Modulator wheel can be omitted setting its material air.
    169 
    170 run $G4WORKDIR/bin/Linux-g++/Hadrontherapy visualisationMacro.mac
    171 to visualise the experimental set-up with OpenGL
    172 
    173 ---->5. PHYSICS
    174 
    175 Both electromagnetic and hadronic physic processes are activated for
    176 the particles of the experimental set-up.
    177 Different physics models can be activated by the user interactively.
    178 
    179 Examples of activation are provided in the macro files starting
    180 with the string "physics":
    181 
    182 All possible physics options are summarized in the file
    183 physicsAllOptions.mac.
    184 
    185 Different options concerning electromagnetic interactions of protons
    186 and neutrons can be tested with the files:
    187 physicsElectromagneticICRU49.mac
    188 physicsElectromagneticZiegler77.mac
    189 physicsElectromagneticZiegler85.mac
    190 
    191 Different options concerning hadronic interactions of protons and
    192 neutrons can be tested with the files:
    193 physicsHadronicBertini.mac
    194 physicsHadronicBinary.mac
    195 physicsHadronicLEP.mac
    196 physicsHadronicPrecompound.mac
    197 
    198 NOTE: Apart from the different models for protons and neutrons, a user
    199 can also select among several interaction models for particles like
    200 electrons or photons. All possible options are listed in the file
    201 physicsAllOptions.mac.
    202 
    203 ---->6. SIMULATION OUTPUT                                   
    204 
    205 The output is an .hbk file (hadrontherapy.hbk) produced
    206 if the variable G4ANALYSIS_USE is set to 1 and the analysis tool (AIDA
    207 interface) correctly installed.
    208 The file contains an histogram and an n-tuple.
    209 The histogram contains the Bragg curve: energy deposited
    210 by the proton beam (in MeV) versus the depth in water (in mm).
    211 The n-tuple contains the total 3D energy deposit in the phantom; the information
    212 is energy deposit in each voxel with respect to the position of the voxel.
    213 
    214 Setup for analysis: AIDA 3.2.1 
    215 
    216 Users can download the analysis tools from: 
    217 http://aida.freehep.org/
    218 
    219 Note that the same information can be stored in any different format.
    220 Please contact cirrone@lns.infn.it if you want store the information in
    221 a different format.
    222 
    223 ---------------------------------------------------------------------------
    224 
    225 for comments, advices, doubts and questions please contact:
    226 cirrone@lns.infn.it, giorgiorusso@lns.infn.it
    227 
    228 last modified: A. Lechner, 16/11/2007
    229 
     363
     364In this case the main file (Hadrontherapy.cc) performs different operations depending on which environment variable is activated;
     365For example, if the environment variable G4UI_USE_TCSH is activated, Hadrontherapy will start with the TCSH User Interface that has many useful functionalities. On the other hand, if this first variables is not defined, the program will continue searching for the G4UI_USE_QT variable and, finally, will open the standard G4UITerminal.
     366Run the example using macro files          
     367Hadrontherapy can be launched using a macro file:
     368
     369> $G4WORDIR/bin/Linux-g++/Hadrontherapy macroFile.mac
     370
     371The defaultMacro.mac file is contained in the main directory of Hadrontherapy and is automatically readed in case the user launch the executable without a parameter. A big number of other macro are inside the /macro folder.
     372
     373Example use of command based scoring
     374In the IAEA geometry it is possible to collect the energy deposition data using the Geant4 command based scoring feature. This allows the users to define scorers interactively in the user interface without writing a single line of C++. Below is listed an example usage of command based scoring:
     375 
     376/score/create/boxMesh boxMesh_1
     377#Box size is the radius of the box ie 20x20x20 gives 40x40x40 outer dimensions
     378/score/mesh/boxSize 13.95 16. 16. cm
     379/score/mesh/translate/xyz 69 0.0 0.0 cm
     380/score/mesh/nBin 400 1 1      # 400 bins in x-direction, 1 in y and z directions
     381
     382SIMULATION OUTPUT
     383ASCII file
     384A .out file is generated at the end of each run, Dose.out is its default name that can be changed in the HadrontherapyMatrix.cc file.
     385The file can contain four columns; the first three columns represent the voxel indexes (that univocally identify the voxel volume), while the last column represent the dose deposited in the given voxel.
     386Alternatively, if the macro command /analysis/secondaries true is given, ordinated dose and fluence, for every secondary produced, is added to the file.
     387Setting the name of the ROOT output file
     388By default the name of the ROOT output file is DoseDistribution.root. The name of the file can be set by using command:
     389/analysis/setAnalysisFile <filename>
     390
     391It is also possible to create multiple new output files in the same simulation session. For example:
     392/beam/energy/meanEnergy 4800 MeV
     393/analysis/setAnalysisFile firstRun.root
     394/run/beamOn 1000
     395/beam/energy/meanEnergy 3000 MeV
     396/analysis/setAnalysisFile secondRun.root
     397/run/beamOn 1000
     398Use of the ROOT analysis
     399It is possible to use ROOT data analysis package directly for the production of output files.
     400In the last version, anyway, this functionality must be implemented by User. This can be accomplished by setting an ad-hoc environment variable (i.e. G4ANALYSIS_USE_ROOT) to 1, adding in the code lines to create outputs with the ROOT libraries and recompiling the application.
     401In this case you must have the ROOT framework installed in your machine.
     402
     403
     404FUTURE CHALLENGES AND USERS' REQUESTS
     405This is a list of future components that will be added in Hadrontherapy and of main Users requests that we hope to fulfill in the next future.
     406What is in progress
     4071. A module for the simulation of an active beam line will be provided.
     408The Korean Group of the Proton therapy center, National Cancer Center is developing this.
     4092. Modules for LET and RBE (Relative Biological Effectiveness) calculation. The Catania Group in Collaboration with the Turin one is working on this.
     4103. Hadrontherapy will permit the simulation of a 'basic' experiment usefull in hadrontherapy applications. User will be able to simulate thin/thick target configuration to calculate quantities like double differential cross sections of secondaries produces, or fluence and yelds of primary and secondaries in a thick block. This work is maily discussed with P. Kaitaniemi and the Group from the Helsinki Institute of Physics.
     411What is requested from Users
     4121. Dicom interface
     413
     414Please contact cirrone@lns.infn.it for more details or suggestions and feedbacks on this document
     415
     416
Note: See TracChangeset for help on using the changeset viewer.