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 ]
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
