Geant4 Cross Reference

Cross-Referencing   Geant4
Geant4/examples/advanced/hadrontherapy/

Version: [ ReleaseNotes ] [ 1.0 ] [ 1.1 ] [ 2.0 ] [ 3.0 ] [ 3.1 ] [ 3.2 ] [ 4.0 ] [ 4.0.p1 ] [ 4.0.p2 ] [ 4.1 ] [ 4.1.p1 ] [ 5.0 ] [ 5.0.p1 ] [ 5.1 ] [ 5.1.p1 ] [ 5.2 ] [ 5.2.p1 ] [ 5.2.p2 ] [ 6.0 ] [ 6.0.p1 ] [ 6.1 ] [ 6.2 ] [ 6.2.p1 ] [ 6.2.p2 ] [ 7.0 ] [ 7.0.p1 ] [ 7.1 ] [ 7.1.p1 ] [ 8.0 ] [ 8.0.p1 ] [ 8.1 ] [ 8.1.p1 ] [ 8.1.p2 ] [ 8.2 ] [ 8.2.p1 ] [ 8.3 ] [ 8.3.p1 ] [ 8.3.p2 ] [ 9.0 ] [ 9.0.p1 ] [ 9.0.p2 ] [ 9.1 ] [ 9.1.p1 ] [ 9.1.p2 ] [ 9.1.p3 ] [ 9.2 ] [ 9.2.p1 ] [ 9.2.p2 ] [ 9.2.p3 ] [ 9.2.p4 ] [ 9.3 ] [ 9.3.p1 ] [ 9.3.p2 ] [ 9.4 ] [ 9.4.p1 ] [ 9.4.p2 ] [ 9.4.p3 ] [ 9.4.p4 ] [ 9.5 ] [ 9.5.p1 ] [ 9.5.p2 ] [ 9.6 ] [ 9.6.p1 ] [ 9.6.p2 ] [ 9.6.p3 ] [ 9.6.p4 ] [ 10.0 ] [ 10.0.p1 ] [ 10.0.p2 ] [ 10.0.p3 ] [ 10.0.p4 ] [ 10.1 ] [ 10.1.p1 ] [ 10.1.p2 ] [ 10.1.p3 ] [ 10.2 ] [ 10.2.p1 ] [ 10.2.p2 ] [ 10.2.p3 ] [ 10.3 ] [ 10.3.p1 ] [ 10.3.p2 ] [ 10.3.p3 ] [ 10.4 ] [ 10.4.p1 ] [ 10.4.p2 ] [ 10.4.p3 ] [ 10.5 ] [ 10.5.p1 ] [ 10.6 ] [ 10.6.p1 ] [ 10.6.p2 ] [ 10.6.p3 ] [ 10.7 ] [ 10.7.p1 ] [ 10.7.p2 ] [ 10.7.p3 ] [ 10.7.p4 ] [ 11.0 ] [ 11.0.p1 ] [ 11.0.p2 ] [ 11.0.p3, ] [ 11.0.p4 ] [ 11.1 ] [ 11.1.1 ] [ 11.1.2 ] [ 11.1.3 ] [ 11.2 ] [ 11.2.1 ] [ 11.2.2 ] [ 11.3.0 ]

Name Size       Last modified (GMT) Description
Back Parent directory       2024-12-05 15:16:16
Folder Modulators/       2024-12-05 15:16:16
Folder data/       2024-12-05 15:16:16
Folder experimentalData/       2024-12-05 15:16:16
Folder field/       2024-12-05 15:16:16
Folder include/       2024-12-05 15:16:16
Folder macro/       2024-12-05 15:16:16
Folder src/       2024-12-05 15:16:16
File CMakeLists.txt 2845 bytes       2024-12-05 15:16:16
File GNUmakefile 612 bytes       2024-12-05 15:16:16
File History 41648 bytes       2024-12-05 15:16:16
File README 30070 bytes       2024-12-05 15:16:16
File batch.mac 1737 bytes       2024-12-05 15:16:16
File clean.sh 93 bytes       2024-12-05 15:16:16
C++ file hadrontherapy.cc 8580 bytes       2024-12-05 15:16:16
File hadrontherapy.out 34667 bytes       2024-12-05 15:16:16

  1            =========================================================
  2                       Text version of the Hadrontherapy README file
  3                  =========================================================
  4 
  5 Last revision: November 2024
  6 
  7 
  8 'hadrontherapy' example is supported by the Italian INFN
  9 Institute in the framework of the Geant4 INFN experiment
 10 
 11 ----------------------------------------------------------------------------
 12                          GEANT 4 - Hadrontherapy example
 13 ----------------------------------------------------------------------------
 14 
 15                                      MAIN AUTHORS
 16                                   ====================
 17          G.A.P. Cirrone(a)*, L. Pandola(a), G. Petringa(a), S.Fattori(a), A.Sciuto(a)
 18               *Corresponding author, email to pablo.cirrone@lns.infn.it
 19 
 20 
 21                   ==========>   PAST CONTRIBUTORS  <==========
 22 
 23                     R.Calcagno(a), G.Danielsen (b), F.Di Rosa(a),
 24                     S.Guatelli(c), A.Heikkinen(b), P.Kaitaniemi(b),
 25                     A.Lechner(d), S.E.Mazzaglia(a), Z. Mei(h), G.Milluzzo(a),
 26                     M.G.Pia(e), F.Romano(a), G.Russo(a,g),
 27                     M.Russo(a), A.Tramontana (a), A.Varisano(a)
 28 
 29               (a) Laboratori Nazionali del Sud of INFN, Catania, Italy
 30               (b) Helsinki Institute of Physics, Helsinki, Finland
 31               (c) University of Wallongong, Australia
 32               (d) CERN, Geneve, Switzwerland
 33               (e) INFN Section of Genova, Genova, Italy
 34               (f) Physics and Astronomy Department, Univ. of Catania, Catania, Italy
 35               (g) CNR-IBFM, Italy
 36               (h) Institute of Applied Electromagnetic Engineering(IAEE)
 37                  Huazhong University of Science and Technology(HUST), Wuhan, China
 38 
 39 -------------------------------------------------------------------------------------------------
 40 
 41 HADRONTHERAPY:
 42 WHAT IT IS, WHAT IT DOES AND WHAT IT WILL PROVIDE
 43 ===================================================
 44 
 45 'hadrontherapy' is a Geant4-based application specifically developed to address typical needs related to proton and ion therapy. 
 46 Its first release was in 2004. At that time 'hadrontherapy' was only capable of simulating a well-specified proton therapy facility: the passive transport beam line installed at Laboratori Nazionali del Sud (INFN) in Catania, Italy.
 47 
 48 Today Hadrontherapy, except that it is in continuous development, is more flexible and shows many additional capabilities with respect to the past.
 49 Its geometrical set-up, for example, is now completely interchangeable permitting a simple switch between different geometrical configurations, which all share the same phantom (sensitive detector) with the related features.
 50 It is possible to do a simulation of a generic proton/ion transport beam line and laser-driven beam line. In this release, a module for dose average LET and RBE computations have been also included.
 51 
 52 The configurations are:
 53 
 54 - Passive proton beam line, which is installed at the LNS-INFN facility in Catania for eye tumor treatment with protons at 62 MeV. It is simulated in PassiveProtonBeamLine.cc; (G.A.P. Cirrone et al., IEEE Nuclear Science Symposium Conference Record, 2003, 3, pp. 1756-1758, J2-5) 
 55 
 56 - Passive carbon beam line, which is the simulation of the transport beam line at LNS-INFN of Catania for experiments with ion beams (Carbon, Oxygen and Helium). It is simulated in PassiveCarbonBeamLine.cc;
 57 
 58 - Laser-driven beam line, which is the simulation of a beam line for the focusing, the handling and the transport of a laser-driven beam, a Faraday Cup is the eligible detector for this class. It is simulated in LaserDrivenBeamLine.cc; 
 59 (A.Tramontana et al., A transport beamline solution for laser-driven proton beams
 60 6th International Particle Accelerator Conference, IPAC 2015, 2015, pp. 2515-2518)
 61 
 62  - TIFPA passive proton beam line, which is installed at the Protontherapy Center of Trento (Italy), used for experiments with proton beams. Geometry is implemented in HadrontherapyTIFPAPassiveProtonBeamLine.cc  
 63 (F.Tommasino et al., A new facility for proton radiobiology at the Trento proton therapy centre: Design and implementation, Physica Medica 58 (2019) 99–106)
 64 
 65 - BEST passive proton beam line is the beamline INFN-LNS is developing for the BEST Cyclotron company for eye tumor treatment with 70 MeV protons. The geometry is implemented in BESTPassiveProtonBeamline.cc.
 66   
 67 In PassiveProtonBeamLine.cc, in PassiveCarbonBeamLine.cc, in LaserDrivenBeamLine.cc,in HadrontherapyTIFPAPassiveProtonBeamLine.cc and in  BESTPassiveProtonBeamline.cc, the user can change the geometrical characteristics of beam line elements.
 68 Alternatively, the user can use the macro file.
 69 
 70 Folder structure of 'hadrontherapy'
 71 
 72 'hadrontherapy' distribution contain different sub-folders:
 73 
 74 \src: where source .cc files are stored
 75 
 76 \include: where header .hh files are stored
 77 
 78 \macro: where a set of ready-to-use macro files are provided
 79 
 80 \field: where a set of ready-to-use.TABLE files are provided. These files are generated from OPERA & COMSOL codes for the laser-driven beam line.
 81 
 82 \experimentalData: in this directory, a set of reference (both experimental and analytical) data are stored. 
 83 
 84 \data\rbe: contains the file lem1.csv including the alpha and beta values and rbe resulted from the radiobiological Local Effect Model (LEM) for three cell lines ( AG01522, U87 and HSG)
 85 
 86 Description of the \macro folder
 87 
 88 Inside the "macro" folder, different macro files are provided. 
 89 In particular, five macro files are related to the different beam lines: 
 90 
 91 defaultMacro.mac: permits to run a simulation using the default geometry, i.e. the CATANA proton beam line in Catania. A  62 MeV gaussian proton beam with 0.25 MeV sigma and 0.028° as divergence (sigma) is launched.
 92             You can modify by macro the range shifter thickness you  
 93             want to select. The entrance of the phantom is positioned at the isocentre ( (0,0,0) 
 94             coordinates). LET and RBE computation are activated. 
 95 
 96 carbon_beamline.mac: reproduces a simple passive beam line for the use of carbon, oxygen and helium ion beams for multidisciplinary applications (selectGeometry Carbon). A parallel 62 MeV/u carbon beam with 0.740 MeV/u sigma is simulated.
 97 
 98 laserDrivenBeamline.mac: simulates a typical laser-driven proton spectrum as input for a beam line made of a quadrupole system, an energy selector and a Faraday Cup (selectGeometry LaserDriven)
 99 
100 
101 Trento_parameters.mac: reproduces the experimental  beam line installed at the Trento protontherapy centre and implements a typical source.
102 
103 BestBeamLine.mac: implements the elements of the beam line developed for the BEST company and simulates a 70 MeV proton beam as input of the simulation. Dose and LET longitudinal distributions are computed at the isocentre and a native dose scorer is also added to retrieve the lateral dose profiles.
104 
105 3 additional macro files are also included: 
106 
107 modulatorMacro.mac : allows the reconstruction of the spread out bragg peak modulating the proton beams by means of a rotating modulator wheel. The wheel is rotated of 1 degree at each run and 1000 protons are simulated in each run. 
108 stoppingPowers.mac : calculates the stopping power of protons and alpha particles in the energy range between  1 keV up to 200 MeV
109 detectorGeometry.mac : example of how to modify the detector geometry
110 
111 The main folder also includes an additional macro file, batch.mac which runs a simple simulation using the default geometry of the CATANA beamline.This macro is also used during the system testing process.
112 
113 DOWNLOAD AND INSTALLATION
114 ===================================================
115 
116 'hadrontherapy' source code is released inside the distribution of the Geant4 toolkit in the $G4INSTALL/examples/advanced folder.
117 
118 To run 'hadrontherapy' you must first install the Geant4 package. Once Geant4 is installed, the example must be first compiled. When the compilation is completed the program can be executed.
119 
120 A complete guide for the Geant4 installation in different operating systems can be found inside the official installation Geant4 pages.
121 
122 A CMakeLists.txt file (preferred) is provided together with a standard GNUmakefile for compilation.                                                         
123 
124 GEOMETRIC SET-UP
125 ===================================================
126 
127 The 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.
128 The main component of the simulation is the phantom, a box that can be filled with different materials and where the scoring of different information (at moment the dose deposited in voxels) can be performed. A more complete description of the phantom is given in the next subsection.
129 
130 All these configurations will be set using macro commands.
131 
132 There is also a feature that allows the user to make a choice between alternative geometry set-ups. This can be done by using the command:
133 /geometrySetup/selectGeometry <name>
134 where <name> is either "default" for the standard 'hadrontherapy' geometry, "Carbon" for INFN-LNS transport beam line, normally used for interdisciplinary researches at LNS-INFN in Catania with carbon and other ion beams, "LaserDriven" for the laser-driven beam line, "TrentoLine" for the TIFPA beam line and "BESTBeamLine" for the beam line designed for the BEST company.
135 
136 At the end of the beam line a phantom (a box of uniform material) is reproduced. Inside it, a user-defined region is divided into cubic and identical voxels. The voxel size can be varied as well as the voxelized region.
137 At 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. 
138 The default size of the active voxelized region is 40x40x40 mm and actually the default voxel configuration is 200 x 1 x 1, which means 200 slices with 0.2 mm of thickness.
139 Of 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.
140 
141 Concerning the cut and stepMax values, the default configuration implies a cut value of 1 mm in the whole  world (use the command /run/setCut <length>  in order to set the cut for all, and the command /run/setCutForRegion <name> <length> to set the cut for the desired volume (<name>) only)  and a stepMax of 0.01 mm just in the phantom and in other volumes of the laser-driven beam line (use the command /Step/waterPhantomStepMax 0.01 mm).
142 In any case, it is strongly recommended to use a stepMax value not bigger than 5% of the dose slice thickness.
143 
144 THE PROTON PASSIVE LINE CLASS FILE
145 ===================================================
146 
147 The following is the description of the elements of the passive proton beam line of the INFN, Laboratori Nazionali del Sud in Catania (I). This line is completely simulated inside this class.
148 
149 The main elements are:
150 
151     * The SCATTERING SYSTEM: to transversally enlarge the original beam
152     * The COLLIMATORS: placed along the beam line to collimate the beam;
153     * The RANGE SHIFTERS: to decrease the energy of the primary proton beam to a specific value;
154     * The MODULATOR WHEEL: to modulate the energy of the primary and mono-energetic beam into a wide spectrum. The energy modulation is necessary to homogeneously irradiate a tumour volume that can extend in depth up to 20 mm;
155     * The MONITOR CHAMBERS: very thin ionisation chamber that permits the dose monitoring during the patient irradiation;
156     * The MOPI detector: microstrips, air-free detector utilised for the check of the beam symmetry during the treatment;
157     * The PATIENT COLLIMATOR: a brass, tumour-shaped collimator able to  confine the proton irradiation field to irradiate just the tumour mass in the transverse direction;
158 
159 The user can vary, via messenger, almost all the geometrical characteristics of the beam line elements (i.e. their position along the beam line, their thickness, etc.).
160 
161 The elements simulated in the PassiveBeamLine.cc file are:
162 
163 1. A scattering system, to spread geometrically the beam;
164 
165 2. A system of collimators, to avoid the scattering radiation;
166 
167 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 thicknesses. The wheel rotates around its axis (parallel to the proton beam axis) and its movement can be obtained employing a messenger between runs.
168 
169 4. A set of monitor chambers (special transmission ionization chambers used to control the particle flux during the irradiation);
170 
171 5. A final long collimator and a patient collimator defining the final shape of the beam before reaching the patient.
172 
173 6. 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).         
174 
175 THE CARBON PASSIVE LINE CLASS FILE
176 ===================================================
177 
178 The PassiveCarbonBeamLine.cc class implements the  Zero Degree (ZD) beamline installed at LNS-INFN and entirely dedicated to in-air irradiation with ion beams (Z > 1, E ≤ 80AMeV ).
179 The beam line is composed of an exit 50 um Kapton window which separates the in vacuum pipe from the in air section. The beam then hits a scattering system composed by a 20 um  tantalum foil and a brass central stopper. Moreover, two different systems for the beam modulation energy are simulated reproducing the available systems at LNS-INFN: a ripple filter specifically designed for 62 AMeV carbon ion beams and a ridge filter designed for 62 AMeV helium and oxygen ion beams. A transmission monitor ionization chamber providing the on-line monitoring of the delivered dose is also simulated.
180 The final collimator system is then composed by a brass tube (50 cm long and 27 mm in diameter) and a brass collimator with a variable in diameter from a maximum of 27 mm to 1 mm.
181 RIDGE FILTER 
182 The ridge filter consists in a 2D array of pins, whose the shape and the thickness is optimized to obtain the desired SOBP.
183 The developed  and simulated ridge filter is composed of 900 pins, each having a square base of 1.7 x 1.7 mm2 and height of 4.72 mm. The material chosen for its realization was plastic (C21 O4 N24) with a density of 1.18 g/cm3. The filter was designed and produced thanks to a collaboration between the INFN-LNS group and the GSI, Darmstadt(D). The reconstruction of the ridge geometry was obtained by superimposed native structures (with a trapezoid shape) already presented in Geant4 (G4Trp).
184 
185 RIPPLE FILTERS
186 ===================================================
187 
188 Due to the native norrower bragg peak of carbon ions with respect to protons, a configuration with two ripple filters is the most suggested for realizing a SOBP. 
189 This solution was adopted at the ZD beam line and implemented in the simulation to obtain a flat longitudinal dose profile with carbon ions: the first filter is positioned at 7 cm from the exit window and the second one at 10 cm from the first. A single structure has a triangular section with a thin base of plexiglass (200 mm x 200 mm x 0.3 mm) and a basis 3 mm in thickness. The material density is 1.19 g/cm3. 
190 
191 
192 LASER DRIVEN PROTON BEAMLINE
193 ===================================================
194 
195 Nowadays a big effort is being devoted to optically accelerate charged particles. There are several ion acceleration regimes that are being discussed in literature, but up to now the most experimentally investigated is the Target Normal Sheath Acceleration (TNSA) one.
196 The beam transport and focusing as well as the energy selection of these laser produced beams represents one of the critical points in order to make such beams suitable for clinical applications. In fact, in contrast to conventional accelerators, the beams produced by high intensity laser-matter interaction are typically characterized by a wide angular divergence (for example ± 25 degrees) and a 100 % energy spread. 
197 Moreover due to the high current, conventional dosimetric systems cannot be used during the experimental sections (saturation issues) and for this reason the faraday cup detector has been proposed as the elegible absolute dosimetric device. 
198 
199 The following is the description of the elements of the laser-driven beam line. This line is completely simulated inside this class.
200 
201 The main elements are:
202 
203     * The QUADRUPOLES SYSTEM: made of four quadrupoles, to focus/defocus protons with a different energy;   
204     * The COLLIMATORS: placed along the beam line to collimate the beam;
205     * The ENERGY SELECTOR SYSTEM: made of four dipoles, that provide the spatial separation of charged particles with different energies;
206     * The FARADAY CUP: that provide the charge measurement and the distribution of the secondary electrons;
207    
208 The user can have the possibility to vary, via messenger, many characteristics of the beam line elements (i.e. their position along the beam line, their thickness, etc.).
209 
210  - /LaserDriven/EnergySelector/Disable -> to disable the Energy Selector 
211 
212  - /LaserDriven/EnergySelector/FirstCollimator/Radius <value> -> to set the Radius of the first collimator
213  - /LaserDriven/EnergySelector/FirstCollimator/thickness <value> -> to set the Thickness of the first collimator
214  - /LaserDriven/EnergySelector/FirstCollimator/zPosizion <value> -> to set the position of the first collimator hole along the radial plane
215 
216  - /LaserDriven/EnergySelector/SecondCollimator/Radius <value> -> to set the Radius of the second collimator
217  - /LaserDriven/EnergySelector/SecondCollimator/thickness <value> -> to set the Thickness of the second collimator
218  - /LaserDriven/EnergySelector/SecondCollimator/zPosizion <value> -> to set the position of the second collimator hole along the radial plane
219 
220  - /LaserDriven/EnergySelector/Slit/thickness <value> -> to set the Thickness of the slit, maximum value 10mm for geometric constraintconstrain
221  - /LaserDriven/EnergySelector/Slit/HoleDimensionY <value> -> to set the Y dimension of the Slit Hole
222  - /LaserDriven/EnergySelector/Slit/HoleDimensionZ <value> -> to set the Z dimension of the Slit Hole
223  - /LaserDriven/EnergySelector/Slit/HolePositionZ <value> -> to set the Slit hole position in the Z direction as respect the Slit body center
224 
225  - /LaserDriven/Quadrupoles/DisableQuad -> to disable the Quadrupole system
226 
227 PHYSICS PROCESSES AND PHYSICS MODELS IMPLEMENTATION
228 ===================================================
229 
230 Using the builder concepts of Geant4 we assembled (and tested) two different
231 Physics Lists that are particuilarly suited for Hadronterapy applications:
232 
233 'HADRONTHERAPY_1' is more suited for protons only
234 'HADRONTHERAPY_2' is suggested for better precision with ions
235 
236 NOTE: to activate the "_HP" physics you have to set the G4PARTICLEHPDATA environment
237 variable pointing to the external dataset named "G4TENDL".
238 
239 The Reference physics lists (already present in the Geant4 kernel) can
240 be used as well. In this case the more suitable "Reference physics lists" are:
241 "QBBC", "QGSP_BIC", "Shielding", "QGSP_BERT",
242 "QGSP_BIC_AllHP" and "QGSP_BIC_HP"
243 
244 
245 All the lists can be  activated inside any macro file using the command:
246 /Physics/addPhysics
247 
248 Examples of usage are:
249 /Physics/addPhysics HADRONTHERAPY_1 or /Physics/addPhysics QGSP_BIC_HP
250 
251 
252 INTERACTIVE COMMANDS
253 ===================================================
254 
255 How to change Phantom and Detector geometries
256 
257 In order to let the user change phantom and detector geometries and voxelization, some interactive commands have been provided. All parameters are mandatory, except those inside square brackets.
258 
259 Detector geometry 
260 
261 The user can change:
262 
263 (1) The detector (box) size.
264  
265 (2) The voxels sizes. Changing these parameters, and/or the detector sizes, users should choose values in order to be divisors of the detector correspondent sizes.
266 For both above commands, zero or negative values mean << don't change it >>
267 
268 (3) The displacement between the phantom and the detector.  Displacement parameters refer to the lower-left corner of the detector with 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>>.
269 
270 Command synopsis: 
271 
272 /changeDetector/size <dimX> <dimY> <dimZ> <[unit]> 
273 /changeDetector/voxelSize <dimX> <dimY> <dimZ> <[unit]> 
274 /changeDetector/displacement <dispX> <dispY> <dispZ> <[unit]> 
275 
276 Default size values are 4x4x4 cm for the detector, 0.2x40x40 mm for any voxel and 0x18x18 cm for the displacement.    
277 where the X dimension is that along the beam direction
278 
279 Phantom geometry
280 
281 (1) The phantom size. As usually, zero or negative values mean: <<don't change it>>.
282 (2) The phantom position respects the world. In this case, specified values refer to the three components of the position of the phantom's centre respect to the world.
283 
284 Command synopsis:
285 
286 /changePhantom/size <dimX> <dimY> <dimZ> <[unit]> # 40 40 40 cm
287 /changePhantom/position <posX> <posY> <posZ> <[unit]> # 20 0 0 cm
288 
289 All   these    commands    must be   followed   by the  command  /changePhantom/update
290 to check and eventually apply changes to the real geometry.
291 Moreover,  they must  be  issued  between   runs  (so   where you   want but   after  the /run/initialize initialization command, or the G4State_Idle Geant4 state machine).
292 Obviously, all the previous sizes must be set in order to maintain the detector fully inside the phantom, otherwise, the system will give an error message.
293 
294  Some examples follow:
295 
296 /changeDetector/size 40 0 0 cm 
297 # Will extend detector X size to cover in full the phantom X size   
298 
299 /changeDetector/size 0 4.5 0 cm
300 # Will extend the Y size to 4.5 cm (note that voxel size Y is automatically
301 #  rounded to 4.5 cm because the default value along Y is 4 cm)
302 /changePhantom/update
303 # Remember to always update the geometry before the beamOn command!!
304 
305 /changeDetector/size 0 8 0 cm
306 # Will extend the Y size to 8 cm. In this case voxel size Y doesn't change, but 
307 # the number of voxels along Y doubles.
308 /changePhantom/update
309 
310 /changeDetector/voxelSize 100 0 0 um 
311 # 100 um should be a divisor of detector size X
312 # Will change only slabs X size to 100 um, without affecting the other.
313 /changePhantom/update
314 
315 /changeDetector/displacement 0 0 0 # default unit mm
316 # Will place the detector in the left lower corner (from the point of view of the beam) of #the  phantom.
317 /changePhantom/update
318 
319 Stopping powers calculation
320 
321 The end-user can calculate, via macro command, stopping powers only for those materials inserted into G4NistMaterialBuilder class (about 300).
322 To get stopping powers user must provide this command line on the idle interactive terminal (or into a macro file) :
323 
324 /parameter/getstopping <G4_material> <Emin> <Emax> <nPoints> <[particle]> <[output_filename]>
325 
326 All parameters are mandatory except those inside square brackets [].
327 Default values for parameters inside square brackets are respectively proton and standard output (usually the user console terminal).
328 
329 Parameters are respectively:
330 
331 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 )
332 Kinetic energy range in MeV and the number of data points to be retrieved (in a logarithmically uniform space)
333 The particle name (proton, e+, e-, He3, neutron,... a full list can be produced via the macro command: /particle/list).
334 Currently, it does not work with ions.
335 The output filename: if users leave this blank then the standard output is used.
336 
337 Below is an example in order to calculate the stopping power for alphas into Hydrogen between 1 keV to 150 MeV for 15 points:
338 
339 /parameter/getstopping G4_H 0.001 150 15 alpha 
340 
341 GEANT4 GENERAL PARTICLE SOURCE
342 ===================================================
343 
344 The General Particle Source (GPS, G4 class name: G4GeneralParticleSource) is in the current version of 'hadrontherapy': it enables the user to use standard energy, angular and spatial distributions. The GPS also includes methods to bias the sampling distribution.
345 
346 The G4GeneralParticleSource can be utilized by typing commands from the /gps command directory, or include the /gps commands in a macro file.
347 
348 RADIOBIOLOGICAL QUANTITIES: DOSE, LET, RBE
349 ===================================================
350 
351 LET calculation
352 
353 'hadrontherapy' application simulates and calculates the averaged LET-dose and LET-track fully accounting for the contribution of secondary particles generated in the target fragmentation  
354 Dependencies as respect to the transport parameters adopted during the Monte Carlo simulations as the production cut of secondaries particles, voxel size and the maximum steps length are minimized in the LET calculation.  The first implementation of LET calculation adopted in hadrontherapy is reported in F. Romano et al.,(2014) Phys Med Biol 59(12): 2863–8. Now, in ‘hadrontherapy’ is implemented the approach reported in G. Petringa et al., (2020) Phys Med Bio. (DOI: 10.1088/1361-6560/abaeb9)
355 At run time, data needed to calculate LET are collected. At the end of simulation, LET mean values are calculated and stored into a file.
356 
357 The Let.out file will be produced at the end of a run, where you can
358 find the dose and track  average LET for each tracked particles (both primary and
359 secondary ones) and the total mean LET. 
360 
361 The file is structured as follows:
362   - The first three columns contain the voxel indexes (first index "i" refers to the beam direction);
363   - The fourth and fifth columns contain respectively total mean dose LET (LDT) and total mean track LET (LTT)  
364   - The rest of columns contain LET Dose and Track for each single ion (whose name is in the top row of the file).
365 
366 To activate the LET computation (HadrontherapyLet.cc), you have to execute
367 the following command:
368 
369 /analysis/secondary true
370 /analysis/computeLet
371 
372 RBE and Survival calculation
373 
374 A method was developed to assess the biological damages produced by proton and ion beams in terms of survival fraction curves, i.e of the number of cells able to survive after the irradiation at different dose. The approach is based on the combined use of Monte Carlo Geant4 simulations (to calculate the doses deposited and the energy spectra of particles interacting with cells) and of the Survival analytical code (Manganaro L, Russo G, et al. Survival: a simulation toolkit introducing a modular approach for radiobiological evaluations in ion beam therapy. Phys. Med. Biol. 2018;63(8). 08–01).
375 The Monte Carlo simulations permit the calculation of the Edep and Ekin distributions that, coupled with the radiobiological response model, allow the final and calculation of a survival curve.
376 The kinetic energy and the LET value of any primary ion and of the secondaries generated in each slice of the simulated water phantom are retrieved at each simulation step. The corresponding values of αi and βi, for each specific ion i with a kinetic energy Ei and a released dose Di, are then calculated by direct linear interpolation of the Look-up-tables provided by the Survival analytical code.
377 (G.Petringa et al., Physica Medica 58 (2019) 72–80)
378 
379 The AlphaAndBeta.out and RBE.out files are produced at the end of the run.
380 AlphaAndBeta.out contains the average alpha (first column) and beta (second column) parameters calculated for each slice (third column).
381 
382 RBE.out  contains the following quantities: 
383 Dose (Gy): the physical dose;
384 ln(S): the natural log of the Survival Fraction;
385 Survival Fraction;
386 DoseB (Gy): the biological dose;
387 RBE: relative biological effectiveness;
388 depth (slice): n. of the slice;
389 
390 To activate the RBE computation (HadrontherapyRBEcc), you have to execute
391 the following command:
392 
393 #you can choose the verbosity level 
394 /rbe/verbose 2 
395  
396 #you have to indicate the name of the LUT inside the rbe folder
397 /rbe/loadLemTable data/rbe/lem.csv
398  
399 /rbe/calculation 1
400 /rbe/accumulate 1
401  
402 #you have to indicate the name of the cell line
403 /rbe/cellLine ARPE19 
404 /rbe/doseScale 7777770
405 
406 SIMULATION OUTPUT
407 ===================================================
408 
409 Store results in an ASCII file
410 
411 A .out ASCII file is generated at the end of each run, Dose.out is its default name that can be changed in the HadrontherapyMatrix.cc file.
412 The file contains four columns; the first three columns represent the voxel indexes (that unequivocally identify the voxel volume), while the last column represents the dose deposited in that given voxel.
413 Alternatively, users can force the store of data to a given filename, after any BeamOn command and before the program ends, by the macro command /analysis/writeDoseFile <myfile.out>.
414 
415 Moreover, if the macro command /analysis/secondary <true> is given, before the BeamOn command, ordinated dose and fluence, for every secondary produced, is added to the file.
416 If the macro command /analysis/computeLet is given, and the ascii file Let.out is written, with the dose and track average LET computations.
417 
418 Users must take care that any change of the phantom geometry will clear all dose data.
419 
420 It is also possible to create multiple new output files in the same simulation session. For example:
421 
422 /beam/energy/meanEnergy 4800 MeV
423 /analysis/setAnalysisFile firstRun.root
424 /run/beamOn 1000
425 /analysis/writeDoseFile firstRun.out # this will write both the .root and the .out file!
426 
427 /beam/energy/meanEnergy 3000 MeV
428 /analysis/setAnalysisFile secondRun.root # this
429 /run/beamOn 1000
430 /analysis/writeDoseFile secondRun.out
431 
432 Please contact cirrone@lns.infn.it  for more details or suggestions and feedback on this document.
433 
434