dna/dnaphysics/README.md

0001 \page ExampleDnaphysics Example dnaphysics
0002
0003 \author S. Incerti (a, *), , H. Tran (a, *), V. Ivantchenko (b), M. Karamitros\n
0004 a. LP2i, IN2P3 / CNRS / Bordeaux 1 University, 33175 Gradignan, France \n
0005 b. G4AI Ltd., UK
0006 * e-mail: incerti@lp2ib.in2p3.fr or tran@lp2ib.in2p3.fr \n
0007
0008 ## INTRODUCTION.
0009
0010 The dnaphysics example shows how to simulate track structures in liquid water
0011 using the Geant4-DNA physics processes and models.
0012
0013 The Geant4-DNA processes and models are further described at:
0014 http://geant4-dna.org
0015
0016 Any report or published results obtained using the Geant4-DNA software shall
0017 cite the following Geant4-DNA collaboration publications: \n
0018 Med. Phys. 51 (2024) 5873–5889 \n
0019 Med. Phys. 45 (2018) e722-e739 \n
0020 Phys. Med. 31 (2015) 861-874   \n
0021 Med. Phys. 37 (2010) 4692-4708 \n
0022 Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178
0023
0024 ## GEOMETRY SET-UP
0025
0026 The geometry is a 100-micron side cube (World) made of liquid water (G4_WATER
0027 material). Particles are shot from the center of the volume. The World size
0028 can be changed directly in the dnaphysics.in macro file.
0029
0030 The variable density feature of materials is illustrated in DetectorConstruction.
0031 The material density can be changed directly in the dnaphysics.in macro file.
0032
0033 ## SET-UP
0034
0035 Make sure $G4LEDATA points to the low energy electromagnetic data files.
0036
0037 ## HOW TO RUN THE EXAMPLE
0038
0039 In interactive mode, run:
0040
0041 ```
0042 ./dnaphysics
0043 ```
0044
0045 In batch, the macro dnaphysics.in can be used. It shows how to shoot different
0046 particle types and how to use Geant4-DNA Physics constructors.
0047
0048 The deexcitation.in macro can be used to simulate the energy spectrum of
0049 deexcitation products.
0050
0051 The radioactive.in macro can be used to simulate some radioactive nuclei.
0052
0053 ## PHYSICS
0054
0055 The PhysicsList uses Geant4-DNA Physics constructors and other
0056 electromagnetic physics constructors.
0057
0058 Geant4-DNA Physics constructors can be selected using the command:
0059
0060 ```
0061 /dna/test/addPhysics DNA_OptX
0062 ```
0063
0064 where X is 0 to 8 (2, 4 or 6 are recommended).
0065
0066 In addition, to also enable radioactive decay, one can use:
0067
0068 ```
0069 /dna/test/addPhysics raddecay
0070 ```
0071
0072 Warning regarding ions: when the incident particle type is ion
0073 (/gun/particle ion), specified with Z and A numbers (/gun/ion A Z),
0074 the Rudd ionisation extended model is used. The particles are tracked
0075 by default down to 0.5 MeV/u and undergo below a capture process.
0076 This tracking cut can be bypassed using:
0077
0078 ```
0079 /dna/test/addIonsTrackingCut false
0080 ```
0081
0082 ## SIMULATION OUTPUT AND RESULT ANALYSIS
0083
0084 The output results consists in a dna.root file, containing two ntuples, named
0085 "step" and "track", respectively:
0086
0087 ### 1) for each simulation step:
0088
0089 - the type of particle for the current step
0090 - the type of process for the current step
0091 - the step PostStepPoint coordinates (in nm)
0092 - the energy deposit along the current step (in eV)
0093 - the step length (in nm)
0094 - the total energy loss along the current step (in eV)
0095 - the kinetic energy at PreStepPoint (in eV)
0096 - the cos of the scattering angle
0097 - the event ID
0098 - the track ID
0099 - the parent track ID
0100 - the step number
0101
0102 This information is extracted from the SteppingAction class.
0103
0104 The ROOT file can be easily analyzed using for example the provided ROOT macro
0105 file plot.C; to do so :
0106 * be sure to have ROOT installed on your machine
0107 * be sure to be in the directory containing the ROOT files created by dnaphysics
0108 * copy plot.C into this directory
0109 * from there, launch ROOT by typing root
0110 * under your ROOT session, type in : .X plot.C to execute the macro file
0111 * alternatively you can type directly under your session : root plot.C
0112
0113 The plotDeexcitation.C ROOT macro file can be used to plot results of
0114 deexcitation.in.
0115
0116 The plotRadioactive.C ROOT macro file can be used to plot results of
0117 radioactive.in.
0118
0119 The plotElastic.C ROOT macro file can be used to show distribution of elastic
0120 scattering angles of the elastic process obtained with elastic.in. This macro also
0121 illustrates the usage of a dedicated UI command :
0122
0123 ```
0124 /step/recordOnlyFirstStep value
0125 ```
0126
0127 where value is 0 or 1. Setting value to 1 only records the first step and then kills
0128 the track and its secondaries.
0129
0130 The naming scheme for particles and processes on the displayed ROOT plots
0131 adopts a local numbering, as follows (see SteppingAction.cc):
0132
0133 - particles: \n
0134 gamma: 0 \n
0135 e-: 1 \n
0136 proton: 2 \n
0137 hydrogen: 3 \n
0138 alpha: 4 \n
0139 alpha+: 5 \n
0140 helium: 6 \n
0141 GenericIon (above helium): 7\n
0142 \n
0143 - processes: \n
0144
0145 Capture: 1
0146
0147 RadioactiveDecay: 2
0148
0149 e-_G4DNAElectronSolvation: 10 \n
0150 e-_G4DNAElastic: 11 \n
0151 e-_G4DNAExcitation: 12 \n
0152 e-_G4DNAIonisation: 13 \n
0153 e-_G4DNAAttachment: 14 \n
0154 e-_G4DNAVibExcitation: 15 \n
0155 msc: 110 \n
0156 CoulombScat: 120 \n
0157 eIoni: 130 \n \n
0158
0159 proton_G4DNAElastic: 21 \n
0160 proton_G4DNAExcitation: 22 \n
0161 proton_G4DNAIonisation: 23 \n
0162 proton_G4DNAChargeDecrease: 24 \n
0163 msc: 210 \n
0164 CoulombScat: 220 \n
0165 hIoni: 230 \n
0166 nuclearStopping: 240 \n \n
0167
0168 hydrogen_G4DNAElastic: 31 \n
0169 hydrogen_G4DNAExcitation: 32 \n
0170 hydrogen_G4DNAIonisation: 33 \n
0171 hydrogen_G4DNAChargeIncrease: 35 \n \n
0172
0173 alpha_G4DNAElastic: 41 \n
0174 alpha_G4DNAExcitation: 42 \n
0175 alpha_G4DNAIonisation: 43 \n
0176 alpha_G4DNAChargeDecrease:      44 \n
0177 msc: 410 \n
0178 CoulombScat: 420 \n
0179 ionIoni: 430 \n
0180 nuclearStopping: 440 \n \n
0181
0182 alpha+_G4DNAElastic: 51 \n
0183 alpha+_G4DNAExcitation: 52 \n
0184 alpha+_G4DNAIonisation: 53 \n
0185 alpha+_G4DNAChargeDecrease: 54 \n
0186 alpha+_G4DNAChargeIncrease: 55 \n
0187 msc: 510 \n
0188 CoulombScat: 520 \n
0189 hIoni: 530 \n
0190 nuclearStopping: 540 \n
0191
0192 helium_G4DNAElastic: 61 \n
0193 helium_G4DNAExcitation: 62 \n
0194 helium_G4DNAIonisation: 63 \n
0195 helium_G4DNAChargeIncrease: 65 \n \n
0196
0197 GenericIon_G4DNAIonisation: 73 \n
0198 msc: 710 \n
0199 CoulombScat: 720 \n
0200 ionIoni: 730 \n
0201 nuclearStopping: 740 \n \n
0202
0203 phot: 81 \n
0204 compt: 82 \n
0205 conv: 83 \n
0206 Rayl: 84 \n
0207
0208 ### 2) for each simulation track:
0209
0210 - the type of particle for the current track (see 1))
0211 - the track position (in nm)
0212 - the track momentum direction
0213 - the track kinetic energy (in eV)
0214 - the track ID
0215 - the parent track ID