Warning, /geant4/examples/advanced/dna/moleculardna/README is written in an unsupported language. File is not indexed.
0001 -------------------------------------------------------------------
0002
0003 =========================================================
0004 Geant4 - an Object-Oriented Toolkit for Simulation in HEP
0005 =========================================================
0006
0007 moleculardna
0008 ------------
0009
0010 A Geant4-DNA application for simulating DNA damage.
0011
0012 AUTHORS (alphabetical order)
0013
0014 J.M.C. Brown, K. Chatzipapas, P. Dondero, M. Dordevic, S. Incerti, M. Karamitros,
0015 N. Lampe, D. Sakata, W.G. Shin, R. Stanzani, H. Tran (*), S. Zein
0016
0017 (*) contact: tran@lp2ib.in2p3.fr
0018
0019 Dedicated website:
0020 http://moleculardna.org
0021 or
0022 https://geant4-dna.github.io/molecular-docs/
0023
0024 This example is provided by the Geant4-DNA collaboration.
0025 (http://geant4-dna.org)
0026
0027 These two PhD theses describe the chain:
0028 W.-G. Shin (2020): https://tel.archives-ouvertes.fr/tel-03161030
0029 N. Lampe (2017): http://www.theses.fr/2017CLFAC011
0030
0031 Any report or published results obtained using the Geant4-DNA software
0032 shall cite the following Geant4-DNA collaboration publications:
0033 Med. Phys. (2024) in press (https://doi.org/10.1002/mp.17256)
0034 Med. Phys. 45 (2018) e722-e739
0035 Phys. Med. 31 (2015) 861-874
0036 Med. Phys. 37 (2010) 4692-4708
0037 Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178
0038
0039 Related publications can be found at:
0040 http://geant4-dna.org
0041
0042 0 - INTRODUCTION
0043
0044 This example shows how to simulate physics, physico-chemistry and
0045 chemistry processes in DNA geometries to predict early damage.
0046
0047 A more detailed description is available at http://moleculardna.org
0048
0049 To build the example:
0050 mkdir build
0051 cd build
0052 cmake ../pathToExamples/moleculardna
0053 make
0054
0055 To run the example:
0056 ./molecular -m cylinders.mac -t 2 -p 2
0057 # -m : macro file
0058 # -t : number of threads to run
0059 # -p : physics list option
0060 # -v : visualization option
0061
0062 Macro files can control every aspect of the simulation, see this introduction:
0063 https://geant4-dna.github.io/molecular-docs/docs/overview/macro-anatomy
0064
0065 The macro commands of this example are listed in:
0066 https://geant4-dna.github.io/molecular-docs/docs/overview/configuration
0067
0068 1 - GEOMETRY DEFINITION
0069
0070 The geometry is built from text files for cylinders (cylinders.mac),
0071 ecoli (ecoli.mac) and human cell (human_cell*.mac) geometries.
0072
0073 - cylinders.mac: to build a 3 μm sphere filled with 200,000 individual 216 bp
0074 long straight DNA segments in a 100×30×30 nm placement volume.
0075 This is a geometry used for parameter (optimization) studies.
0076
0077 - fiber.mac: to visualize a fiber of DNA
0078
0079 - phage.mac: to model the irradiation of a DNA phage containing 141158 bp,
0080 placed in a cylinder with radius 3.5 um and height 7 um.
0081
0082 - plasmid.mac: to model a cube of liquid water (side 4.84 um) containing around
0083 10 000 plasmids (pBR322, 4367 base pairs) randomly oriented in a supercoiled conformation.
0084
0085 - ecoli.mac: to demonstrate a simple model where the bacterial DNA follows a
0086 large scale fractal ‘Hilbert curve’ geometry.
0087
0088 - human_cell.mac, human_cell_HTB177.mac and human_cell_MCF7.mac: to model
0089 three different cell geometries, as detailed in [1]. These mac file may
0090 be used to produce data that serve as input to the repair models.
0091
0092 - human_cell_chromosomes.mac: to model the chromosomal type of cell geometry,
0093 as detailed in [4].
0094
0095 More geometry information can be found in https://geant4-dna.github.io/molecular-docs/docs/examples
0096
0097 To construct other DNA geometries, see http://natl.github.io/fractaldna/
0098
0099 To construct chromosomal or other complex DNA geometries, see https://github.com/konhat88/complexDNA
0100
0101 Macro commands can be used to control the geometry parameters, see for example cylinders.mac:
0102
0103 # Commands for world and cell dimensions
0104 /world/worldSize 10200 nm
0105 /cell/radiusSize 3 3 3 um
0106
0107 # Command to select the chemistry model (only IRT_syn for this example)
0108 /process/chem/TimeStepModel IRT_syn
0109
0110 # End time of chemistry simulation
0111 /scheduler/endTime 1 us
0112
0113 # Set voxel optimisation
0114 /dnageom/setSmartVoxels 1
0115
0116 # Check overlaps in DNA geometry region
0117 /dnageom/checkOverlaps false
0118
0119 # Distance from base pairs at which radicals are killed
0120 /dnageom/radicalKillDistance 9 nm
0121
0122 # Deposited energy accumulation range limit to start recording SBs from direct effects
0123 /dnageom/interactionDirectRange 7 angstrom
0124
0125 # Side length for each placement (x, y, z)
0126 /dnageom/placementSize 30 30 100 nm
0127
0128 # Scaling of XYZ in fractal definition file
0129 /dnageom/fractalScaling 1 1 1 nm
0130
0131 # Path to file that defines placement locations
0132 /dnageom/definitionFile geometries/prisms200k_r3000.txt
0133
0134 # Set a placement volume [format] [name path]
0135 /dnageom/placementVolume prism geometries/straight-216-0.txt
0136
0137 # Take the angles in the voxel placement file as multiples of pi
0138 # E.g. set to true if the angle 0.5 should mean 90 degrees
0139 /dnageom/setVoxelPlacementAnglesAsMultiplesOfPi false # default
0140
0141 # The molecule size columns are optional, as they can either
0142 # fall back onto the default sizes or be set to custom sizes in the macro
0143 # used default moleculeSize (as belows)
0144 /dnageom/useCustomMoleculeSizes false # default
0145 #/dnageom/moleculeSize
0146
0147 # Draw cell/chromosome volumes rather than DNA (makes DNA invisible)
0148 /dnageom/drawCellVolumes false # default
0149
0150 # Activate Histone scavenging function with default radius
0151 /dnageom/activateHistoneScavenging true # default
0152
0153 # DNA geometries are only ever placed in a chromosome
0154 /chromosome/add cylinder sphere 3000 0 0 0 nm
0155
0156 # For the visualisation of DNA geometries, the following line can be used
0157 /control/execute vis.mac
0158 # More specifically, start moleculardna using the command ./molecular -t 1 -v 1
0159 # to open the Qt visualiser. Then use the mac file that you want, e.g.
0160 # /control/execute cylinders.mac
0161 # For the visualization, large amount of RAM is needed. For example
0162 # using cylinders DNA geometries, to visualize 200 cylinders, ~2.5 GB
0163 # are needed. For 2000 cylinders, ~11 GB are needed.
0164
0165 2 - PHYSICS LIST
0166
0167 The physics list can use the recommended G4EmDNAPhysics_option2,
0168 G4EmDNAPhysics_option4 or
0169 G4EmDNAPhysics_option6 constructors.
0170
0171 3 - PRIMARY GENERATOR
0172
0173 The source can be specified via General Particle Source in the provided
0174 macro files.
0175
0176 4 - DNA DAMAGE MODEL
0177
0178 Mechanistic DNA simulations are dependent upon a
0179 DNA damage model to relate energy depositions close to DNA,
0180 and chemical reactions with DNA, to actual DNA damage
0181
0182 The following macro commands can be used to control the damage parameters:
0183
0184 # Direct damage threshold
0185 /dnadamage/directDamageLower 17.5 eV
0186 /dnadamage/directDamageUpper 17.5 eV
0187
0188 # Indirect damage probability to create a SSB for
0189 # OH radical + DNA base
0190 /dnadamage/indirectOHBaseChance 1.0
0191 /dnadamage/indirectOHStrandChance 0.65
0192 /dnadamage/inductionOHChance 0.0
0193
0194 # H radicals + DNA base
0195 /dnadamage/indirectHBaseChance 1.0
0196 /dnadamage/indirectHStrandChance 0.65
0197 /dnadamage/inductionHChance 0.0
0198
0199 # e_aq radicals + base
0200 /dnadamage/indirectEaqBaseChance 1.0
0201 /dnadamage/indirectEaqStrandChance 0.65
0202 /dnadamage/inductionEaqChance 0.0
0203
0204 5 - RESULTS
0205
0206 # Bool to set whether strands ought be saved
0207 /analysisDNA/saveStrands false # default
0208
0209 # Directory to save DNA damage fragments
0210 /analysisDNA/strandDir
0211
0212 # Gap between DNA fragments in base pairs
0213 # Set to zero to score placement volumes independently
0214 /analysisDNA/fragmentGap 0
0215
0216 # To save the position of hits histos only on one chain
0217 /analysisDNA/diagnosticChain
0218
0219 Several ROOT macro files are provided in the analysis directory:
0220 - cylinders.C: to plot damage from cylinders geometry
0221 - ecoli.C: to plot damage from ecoli geometry
0222 - human_cell.C: to plot damage and fragments distribution from human_cell*
0223 geometries. The human_cell_alphas.C macro can be used as shown in [1].
0224 - phage.C: to plot damage and fragments distribution from phage geometry
0225 - plasmid.C: to plot damage and fragments distribution from plasmid geometries
0226 - human_cell_chromosomes.C: to plot damage and fragments distribution
0227 from human_cell_chromosomes geometries.
0228
0229 A python macro file is provided to modify ROOT output in SDD file format [2]:
0230 - createSDD.py: to use it, insert the command "python3 createSDD.py".
0231 If error with ROOT, simply
0232 source /path/to/root/bin/thisroot.(c)sh,
0233 do "pip install pyroot" and try again.
0234
0235 A python macro file is provided to analyse the output of chromosomal geometry simulation [4]:
0236 - human_cell_chromosomes.py: to use it, insert the command "python3 human_cell_chromosomes.py".
0237
0238
0239 A python macro file to calculate repair kinetics is located in the folder
0240 repair_survival_models. This script can be used with the output of the mac
0241 file human_cell (10^5 primaries) to reproduce data published in [3]:
0242 - molecularDNArepair.py: to use it, insert the command "python3 molecularDNArepair.py".
0243 The molecular-dna.root file is also needed to run it, as produced by
0244 the human-cell.mac macro.
0245
0246 A python macro file to calculate the survival probability of cells is located
0247 in the folder repair_survival_models. This script is early released and needs to be optimized
0248 to fit any data.
0249 - molecularDNAsurvival.py: to use it, insert the command "python3 molecularDNAsurvival.py".
0250 The molecular-dna.root file is needed to run it, as produced by
0251 the human-cell.mac macro.
0252
0253 *** Note on ROOT import from python:
0254 If python cannot import ROOT, please configure your ROOT version to include PyROOT.
0255 For further instruction, refer to the documentation of ROOT, paragraph 19.1.4.2:
0256 https://root.cern/root/htmldoc/guides/users-guide/ROOTUsersGuide.html#python-interface
0257
0258 6 - PHASE SPACE READING
0259
0260 The example can read a phase space file as source for the primary generation,
0261 defined in the csv format used by the GRAS Two-Stage Analysis [5].
0262 An example of phase space file and the macro to read it are provided in the
0263 "/phase_space" subdirectory.
0264 This simple phase space file only provides 20 electrons with an energy of
0265 45 keV on a randomly shaped surface based on the cylinders.mac macro file.
0266
0267 7 - REFERENCES
0268
0269 [1] https://doi.org/10.1016/j.ejmp.2023.102613
0270 [2] https://doi.org/10.1667/RR15209.1
0271 [3] https://doi.org/10.1002/pro6.1186
0272 [4] https://doi.org/10.1016/j.ejmp.2024.104839
0273 [5] https://spitfire.estec.esa.int/trac/GRAS/wiki/GRAS/GRAS-05-02/UserGuideTwoStage
0274
0275 An alternative example for DNA damage calculation can be found in /examples/advanced/dna/dsbandrepair
