Geant4 Cross Reference |
1 ------------------------------------------------------------------- 2 3 ========================================================= 4 Geant4 - an Object-Oriented Toolkit for Simulation in HEP 5 ========================================================= 6 7 moleculardna 8 ------------ 9 10 A Geant4-DNA application for simulating DNA damage. 11 12 AUTHORS (alphabetical order) 13 14 J.M.C. Brown, K. Chatzipapas, P. Dondero, M. Dordevic, S. Incerti, M. Karamitros, 15 N. Lampe, D. Sakata, W.G. Shin, R. Stanzani, H. Tran (*), S. Zein 16 17 (*) contact: tran@lp2ib.in2p3.fr 18 19 Dedicated website: 20 http://moleculardna.org 21 or 22 https://geant4-dna.github.io/molecular-docs/ 23 24 This example is provided by the Geant4-DNA collaboration. 25 (http://geant4-dna.org) 26 27 These two PhD theses describe the chain: 28 W.-G. Shin (2020): https://tel.archives-ouvertes.fr/tel-03161030 29 N. Lampe (2017): http://www.theses.fr/2017CLFAC011 30 31 Any report or published results obtained using the Geant4-DNA software 32 shall cite the following Geant4-DNA collaboration publications: 33 Med. Phys. (2024) in press (https://doi.org/10.1002/mp.17256) 34 Med. Phys. 45 (2018) e722-e739 35 Phys. Med. 31 (2015) 861-874 36 Med. Phys. 37 (2010) 4692-4708 37 Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178 38 39 Related publications can be found at: 40 http://geant4-dna.org 41 42 0 - INTRODUCTION 43 44 This example shows how to simulate physics, physico-chemistry and 45 chemistry processes in DNA geometries to predict early damage. 46 47 A more detailed description is available at http://moleculardna.org 48 49 To build the example: 50 mkdir build 51 cd build 52 cmake ../pathToExamples/moleculardna 53 make 54 55 To run the example: 56 ./molecular -m cylinders.mac -t 2 -p 2 57 # -m : macro file 58 # -t : number of threads to run 59 # -p : physics list option 60 61 Macro files can control every aspect of the simulation, see this introduction: 62 https://geant4-dna.github.io/molecular-docs/docs/overview/macro-anatomy 63 64 The macro commands of this example are listed in: 65 https://geant4-dna.github.io/molecular-docs/docs/overview/configuration 66 67 1 - GEOMETRY DEFINITION 68 69 The geometry is built from text files for cylinders (cylinders.mac), 70 ecoli (ecoli.mac) and human cell (human_cell*.mac) geometries. 71 72 - cylinders.mac: to build a 3 μm sphere filled with 200,000 individual 216 bp 73 long straight DNA segments in a 100×30×30 nm placement volume. 74 This is a geometry used for parameter (optimization) studies. 75 76 - plasmid.mac: to model a cube of liquid water (side 4.84 um) containing around 77 10 000 plasmids (pBR322, 4367 base pairs) randomly oriented in a supercoiled conformation. 78 79 - ecoli.mac: to demonstrate a simple model where the bacterial DNA follows a 80 large scale fractal ‘Hilbert curve’ geometry. 81 82 - human_cell.mac, human_cell_HTB177.mac and human_cell_MCF7.mac: to model 83 three different cell geometries, as detailed in [1]. These mac file may 84 be used to produce data that serve as input to the repair models. 85 86 - human_cell_chromosomes.mac: to model the chromosomal type of cell geometry, 87 as detailed in [4]. 88 89 More geometry information can be found in https://geant4-dna.github.io/molecular-docs/docs/examples 90 91 To construct other DNA geometries, see http://natl.github.io/fractaldna/ 92 93 To construct chromosomal or other complex DNA geometries, see https://github.com/konhat88/complexDNA 94 95 Macro commands can be used to control the geometry parameters, see for example cylinders.mac: 96 97 # Commands for world and cell dimensions 98 /world/worldSize 10200 nm 99 /cell/radiusSize 3 3 3 um 100 101 # Command to select the chemistry model (only IRT_syn for this example) 102 /process/chem/TimeStepModel IRT_syn 103 104 # End time of chemistry simulation 105 /scheduler/endTime 1 us 106 107 # Set voxel optimisation 108 /dnageom/setSmartVoxels 1 109 110 # Check overlaps in DNA geometry region 111 /dnageom/checkOverlaps false 112 113 # Distance from base pairs at which radicals are killed 114 /dnageom/radicalKillDistance 9 nm 115 116 # Deposited energy accumulation range limit to start recording SBs from direct effects 117 /dnageom/interactionDirectRange 7 angstrom 118 119 # Side length for each placement (x, y, z) 120 /dnageom/placementSize 30 30 100 nm 121 122 # Scaling of XYZ in fractal definition file 123 /dnageom/fractalScaling 1 1 1 nm 124 125 # Path to file that defines placement locations 126 /dnageom/definitionFile geometries/prisms200k_r3000.txt 127 128 # Set a placement volume [format] [name path] 129 /dnageom/placementVolume prism geometries/straight-216-0.txt 130 131 # Take the angles in the voxel placement file as multiples of pi 132 # E.g. set to true if the angle 0.5 should mean 90 degrees 133 /dnageom/setVoxelPlacementAnglesAsMultiplesOfPi false # default 134 135 # The molecule size columns are optional, as they can either 136 # fall back onto the default sizes or be set to custom sizes in the macro 137 # used default moleculeSize (as belows) 138 /dnageom/useCustomMoleculeSizes false # default 139 #/dnageom/moleculeSize 140 141 # Draw cell/chromosome volumes rather than DNA (makes DNA invisible) 142 /dnageom/drawCellVolumes false # default 143 144 # Activate Histone scavenging function with default radius 145 /dnageom/activateHistoneScavenging true # default 146 147 # DNA geometries are only ever placed in a chromosome 148 /chromosome/add cylinder sphere 3000 0 0 0 nm 149 150 # For the visualisation of DNA geometries, the following line can be used 151 /control/execute vis.mac 152 # More specifically, start moleculardna using the command ./molecular, to 153 # to open the Qt visualiser. Then use the mac file that you want, e.g. 154 # /control/execute cylinders.mac 155 # For the visualization, large amount of RAM is needed. For example 156 # using cylinders DNA geometries, to visualize 200 cylinders, ~2.5 GB 157 # are needed. For 2000 cylinders, ~11 GB are needed. 158 159 The DNA parallel world can be activated using the "useParallelPhysicsWorld" flag 160 in the PhysicsList.cc and DetectorConstruction.cc files for the physics stage. 161 Setting "useParallelPhysicsWorld = false" means that particles will only interact 162 with the water volume. Energy deposition in water caused by direct damage is 163 recorded using octree data structures associated with DNA volumes. 164 165 2 - PHYSICS LIST 166 167 The physics list can use the recommended G4EmDNAPhysics_option2, 168 G4EmDNAPhysics_option4 or 169 G4EmDNAPhysics_option6 constructors. 170 171 3 - PRIMARY GENERATOR 172 173 The source can be specified via General Particle Source in the provided 174 macro files. 175 176 4 - DNA DAMAGE MODEL 177 178 Mechanistic DNA simulations are dependent upon a 179 DNA damage model to relate energy depositions close to DNA, 180 and chemical reactions with DNA, to actual DNA damage 181 182 The following macro commands can be used to control the damage parameters: 183 184 # Direct damage threshold 185 /dnadamage/directDamageLower 17.5 eV 186 /dnadamage/directDamageUpper 17.5 eV 187 188 # Indirect damage probability to create a SSB for 189 # OH radical + DNA base 190 /dnadamage/indirectOHBaseChance 1.0 191 /dnadamage/indirectOHStrandChance 0.65 192 /dnadamage/inductionOHChance 0.0 193 194 # H radicals + DNA base 195 /dnadamage/indirectHBaseChance 1.0 196 /dnadamage/indirectHStrandChance 0.65 197 /dnadamage/inductionHChance 0.0 198 199 # e_aq radicals + base 200 /dnadamage/indirectEaqBaseChance 1.0 201 /dnadamage/indirectEaqStrandChance 0.65 202 /dnadamage/inductionEaqChance 0.0 203 204 5 - RESULTS 205 206 # Bool to set whether strands ought be saved 207 /analysisDNA/saveStrands false # default 208 209 # Directory to save DNA damage fragments 210 /analysisDNA/strandDir 211 212 # Gap between DNA fragments in base pairs 213 # Set to zero to score placement volumes independently 214 /analysisDNA/fragmentGap 0 215 216 # To save the position of hits histos only on one chain 217 /analysisDNA/diagnosticChain 218 219 Several ROOT macro files are provided in the analysis directory: 220 - cylinders.C: to plot damage from cylinders geometry 221 - ecoli.C: to plot damage from ecoli geometry 222 - human_cell.C: to plot damage and fragments distribution from human_cell* 223 geometries. The human_cell_alphas.C macro can be used as shown in [1]. 224 - plasmid.C: to plot damage and fragments distribution from plasmid geometries 225 - human_cell_chromosomes.C: to plot damage and fragments distribution 226 from human_cell_chromosomes geometries. 227 228 A python macro file is provided to modify ROOT output in SDD file format [2]: 229 - createSDD.py: to use it, insert the command "python3 createSDD.py". 230 If error with ROOT, simply 231 source /path/to/root/bin/thisroot.(c)sh, 232 do "pip install pyroot" and try again. 233 234 A python macro file is provided to analyse the output of chromosomal geometry simulation [4]: 235 - human_cell_chromosomes.py: to use it, insert the command "python3 human_cell_chromosomes.py". 236 237 238 A python macro file to calculate repair kinetics is located in the folder 239 repair_survival_models. This script can be used with the output of the mac 240 file human_cell (10^5 primaries) to reproduce data published in [3]: 241 - molecularDNArepair.py: to use it, insert the command "python3 molecularDNArepair.py". 242 The molecular-dna.root file is also needed to run it, as produced by 243 the human-cell.mac macro. 244 245 A python macro file to calculate the survival probability of cells is located 246 in the folder repair_survival_models. This script is early released and needs to be optimized 247 to fit any data. 248 - molecularDNAsurvival.py: to use it, insert the command "python3 molecularDNAsurvival.py". 249 The molecular-dna.root file is needed to run it, as produced by 250 the human-cell.mac macro. 251 252 6 - PHASE SPACE READING 253 254 The example can read a phase space file as source for the primary generation, 255 defined in the csv format used by the GRAS Two-Stage Analysis [5]. 256 An example of phase space file and the macro to read it are provided in the 257 "/phase_space" subdirectory. 258 This simple phase space file only provides 20 electrons with an energy of 259 45 keV on a randomly shaped surface based on the cylinders.mac macro file. 260 261 7 - REFERENCES 262 263 [1] https://doi.org/10.1016/j.ejmp.2023.102613 264 [2] https://doi.org/10.1667/RR15209.1 265 [3] https://doi.org/10.1002/pro6.1186 266 [4] https://doi.org/10.1016/j.ejmp.2024.104839 267 [5] https://spitfire.estec.esa.int/trac/GRAS/wiki/GRAS/GRAS-05-02/UserGuideTwoStage 268 269 An alternative example for DNA damage calculation can be found in /examples/advanced/dna/dsbandrepair