Warning, /geant4/examples/extended/medical/dna/dnadamage2/README.txt is written in an unsupported language. File is not indexed.
0001 $Id: $
0002 -------------------------------------------------------------------
0003
0004 =========================================================
0005 Geant4 - dnadamage2 example
0006 =========================================================
0007
0008 DNADAMAGE2
0009 ----------
0010
0011 CORRESPONDING AUTHORS
0012 J. Naoki D. Kondo
0013 J. Ramos-Mendez
0014 B. Faddegon
0015 (a) JorgeNaoki _ DominguezKondo _ ucsf _ edu
0016 (b) Jose _ RamosMendez _ ucsf _ edu
0017 (c) Bruce _ Faddegon _ ucsf _ edu
0018
0019 CONTACT EMAIL
0020 JorgeNaoki.DominguezKondo@ucsf.edu
0021
0022 This example is provided by the Geant4-DNA collaboration.
0023 (http://geant4-dna.org)
0024
0025 Any report or published results obtained using this example shall
0026 cite the following publications:
0027
0028 [1] J.N. D-Kondo, et al., (2021) DNA damage modeled with Geant4-DNA: effects of
0029 plasmid DNA conformation and experimental conditions.
0030 Physics in Medicine and Biology, 66 (24). https://doi.org/10.1088/1361-6560/ac3a22
0031
0032 [2] J. Ramos-Méndez, et al., (2020). Independent reaction times method in Geant4-DNA:
0033 Implementation and performance.Medical Physics, 47(11), 5919–5930.
0034 https://doi.org/10.1002/mp.14490
0035
0036 In addition, cite the main Geant4-DNA collaboration publications:
0037
0038 [3] J. Appl. Phys. 125 (2019) 104301
0039 [4] Med. Phys. 45 (2018) e722-e739
0040 [5] Phys. Med. 31 (2015) 861-874
0041 [6] Med. Phys. 37 (2010) 4692-4708
0042 [7] Int. J. Model. Simul. Sci . Comput. 1 (2010) 157-178
0043
0044 0 - INTRODUCTION
0045 This examples provides scoring of plasmid DNA strand breaks using
0046 the IRT method [2]. The DNADAMAGE2 example extends the chem6 example
0047 by adding DNA molecule information and the scoring of Strand Breaks.
0048 Experimental conditions are considered such as oxygen and DMSO molar
0049 concentrations.
0050
0051 The details are described in the following papers [1][2] for both
0052 the IRT method and this example's validation.
0053
0054 1 - GEOMETRY DEFINITION
0055
0056 The geometry is composed of three main components:
0057 - The world: A 2 um water cube which hostess the rest of the components.
0058 - The Plasmid Envelope: A water sphere of 1 um in diameter by default.
0059 This envelope can be resized using the "/det/setSize"
0060 command. So users can modify their DNA concentration
0061 without increasing the number of plasmids, but by lowering
0062 the amount of water.
0063 - The Plasmids: Plasmids must be supplied to the geometry. The plasmid file must
0064 be in ASCII format. Three columns which represent the X, Y and
0065 Z position of the plasmid vertices (bps). To control the
0066 parameters to setup the plasmid geomtery, the following commands
0067 shall be used:
0068 + /det/NbOfPlasmids :Set the number of plasmid copies. G4Box Volumes
0069 are used to enclose the plasmid.
0070 + /det/OffSetFile : The file format is ASCII. It contains three columns
0071 indicating the X, Y and Z position of the center of
0072 the plasmid envelopes (G4Box volumes enclosing the plasmid)
0073 + /det/PlasmidFile : Set the ASCII file name containing the plasmid
0074 information.
0075 + /det/UseDNAVolumes : Boolean to activate/deactivate the solid
0076 volumes defining the DNA nucleotides. If set to false,
0077 virtual molecules are created from the DNA nucleotides
0078 position for simulating indirect strand breaks. See
0079 reference [2].
0080
0081 The definition of the sensitive volumes is also made in the Geometry Definition.
0082 Inside the method ConstructSDandField() (see section 5).
0083
0084 2 - PHYSICS AND CHEMISTRY LISTS
0085
0086 By default, if no Physics list is assigned using the "/physics/SetPhysics" the simulation
0087 will run using:
0088
0089 + G4EmDNAPhysics_option4 constructor
0090
0091 The full list of physics lists available for the user are:
0092 + G4EmDNAPhysics_option1
0093 + G4EmDNAPhysics_option2
0094 + G4EmDNAPhysics_option3
0095 + G4EmDNAPhysics_option4
0096 + G4EmDNAPhysics_option5
0097 + G4EmDNAPhysics_option6
0098 + G4EmDNAPhysics_option7
0099 + G4EmDNAPhysics_option8
0100
0101 By default, if no chemistry list is assigned using the "/physics/SetChemistry"
0102 the simulation will run using:
0103
0104 + G4EmDNAChemistry_ForPlasmids
0105 - Custom chemistry constructor based on the G4EmDNAChemistry_option3
0106 constructor.
0107 - It includes DNA reactions as well as DMSO and oxygen background reactions.
0108 - The chemistry constructor is based on the pre-chemical stage of PARTRAC
0109 and chemical parameters of RITRACKS.
0110 - This chemistry constructor uses the Independent Reaction Times method.
0111
0112 By using this Chemistry List, users can set oxygen and DMSO concentration
0113 with the following commands "/chem/scavenger/DMSO" and "/chem/scavenger/Oxygen".
0114 The concentrations unit must be given as molar concentaration M (mol/dm3).
0115
0116 *Of note, while other chemistry modules are also available, only the
0117 G4EmDNAChemistry_ForPlasmids is capable of scoring DNA strand breaks.
0118
0119 3 - ACTION INITALIZATION
0120
0121 The class ActionInitialization instantiates and registers
0122 to Geant4 kernel all user action classes.
0123
0124 While in sequential mode the action classes are instantiated just once,
0125 via invoking the method:
0126 ActionInitialization::Build()
0127 In multi-threading mode the same method is invoked for each thread worker
0128 and so all user action classes are defined thread-local.
0129
0130 A run action class is instantiated both thread-local
0131 and global that's why its instance is created also in the method:
0132 ActionInitialization::BuildForMaster()
0133 which is invoked only in multi-threading mode.
0134
0135 The following actions are initialized in this example:
0136 + PrimaryGenerationAction: The primary particle gun.
0137 + RunAction: Defines the actions conducted at the start and end of each
0138 Geant4 Run. It contains the call to the output functions of
0139 the scorers.
0140 + StackingAction: Needed in order to start the chemistry (See section 7)
0141 + TimeStepAction: Defines actions conducted at each Step-By-Step (SBS)
0142 Chemistry algorithm step (see section 6).
0143
0144 4 - AN EVENT: THE PRIMARY GENERATOR
0145
0146 The primary kinematic consists of N electrons with random position and
0147 momentum in the water sphere. The kinetic energy of the electrons are
0148 sampled from an energy spectrum suplied by the user using the "/fpGun/SourceFile"
0149 command. The user can set the number of primary electrons per event in order
0150 to accumulate a certain dose before running the chemistry.
0151
0152 This example provides the specrum of the kinetic energy of secondary electrons
0153 at the time they were produced by cobalt-60/cesium-137 gamma rays (see section 11
0154 and [1] for more information).
0155
0156 The chemistry module is triggered in the StackingAction class when all
0157 physical tracks have been processed (see section 7).
0158
0159 5 - DETECTOR RESPONSE: Scorers
0160
0161 5.1 - Species scorer
0162
0163 This scorer computes the energy deposition and the number of species along
0164 time in order to extract the radiochemical yields as in chem6 or chem4 examples.
0165
0166 Run::RecordEvent(), called at end of event, collects informations
0167 event per event from the hits collections, and accumulates statistics for
0168 RunAction::EndOfRunAction().
0169
0170 In multi-threading mode the statistics accumulated per worker is merged
0171 to the master in Run::Merge().
0172
0173 The following macro commands can be used to control the scoring time:
0174
0175 /scheduler/endTime : IRT chemistry time end, must be acompanied by time units.
0176
0177 /scorer/species/addTimeToRecord : Adds a specific time point to report.
0178
0179 /scorer/species/nOfTimeBins : Sets the number of time bins separated
0180 logaritmically even from 1 ps to the endTime
0181 specified.
0182
0183 The information about all the molecular species is scored and can be saved
0184 in a ASCII, ROOT or BINARY file, as specified by the user. The specific name
0185 of the file can also be specified by the user by using the following commands:
0186 -/scorer/species/OutputFile
0187 -/scorer/species/OutputFormat
0188
0189 ASCII results are given in a 5 column file which are:
0190 - Time
0191 - GValues per 100 eV
0192 - GValues Error
0193 - GValues number of molecules
0194 - Molecule name
0195
0196 ROOT or BINARY use the Geant4 Analysis Manager with the following columns:
0197 - Species ID
0198 - Number
0199 - Number of Event
0200 - Species Name
0201 - Time
0202 - Sum of G Value
0203 - Sum of G2 Value
0204
0205 5.2. - LET scorer
0206
0207 An restricted, dose-averaged LET scorer is provided with this example,
0208 it is the same scorer from the chem6 example. For more details visit the
0209 chem6 example
0210
0211 A macro command can be used to control the energy cut of the scorer:
0212 /scorer/LET/cutoff
0213
0214 5.4. - DNA Strand Break Scorer
0215
0216 The DNA Strand Breaks are obtained by this class, both direct and indirect.
0217 This class needs access to the DetectorConstruction class in order to obtain
0218 the DNA position information.
0219
0220 Contained within this scorer is a "MoleculeGun" as a mean to insert the DNA
0221 molecules and keep track of them in order to know where a strand break occurs.
0222 This helps to calculate SSBs, DSBs and other more complex DNA Strand Breaks.
0223 The user is responsible for the Strand Break classification since this example
0224 doesn't include any analysis tool.
0225
0226 Users can change the output type and output file name in the same way of the
0227 "ScoreSpecies" scorer, with the commands:
0228 -/scorer/StrandBreak/OutputFile
0229 -/scorer/StrandBreak/OutputFormat
0230
0231 The output formats available are the same as with the ScoreSpecies scorer:
0232 ASCII, ROOT and BINARY.
0233
0234 The number of direct Strand Breaks are scored when a certain energy
0235 threshold is reached for a certain deoxyribose + phosphate geometry. Users can
0236 change the direct energy treshold by using the following command:
0237 -/scorer/StrandBreak/BreakEnergy
0238
0239 Of note, the following parameter must be set to true to score the breaks produced
0240 by direct effect
0241 -/det/UseDNAVolumes true
0242
0243 The BreakEnergy is set to 17.5 eV by default.
0244
0245 The "ScoreStrandBreak" class takes the LET value at the end of the simulation from
0246 5.2 and saves it into the file of the ASCII output, so that users may get the number
0247 of Strand Breaks as a function of LET if so they desire.
0248 The current example only allows the use of electron sources, but the user is free to
0249 use different electron energies.
0250
0251 6 - IRT specific details
0252
0253 The IRT is run after the few step-by-step (SBS) steps following the water dissociation
0254 (pre-chemical) stage have finished (between 2 to 3 SBS steps), see UserPreTimeStepAction()
0255 and UserPostTimeStepAction(). At that point,
0256 SBS is stopped and the position of molecules and DNA molecules are passed to the IRT
0257 method. No DNA radiolysis is considered, so every specie created inside the DNA
0258 nucleotide territory is exclude by using the UserPreTimeStepAction as a filters, see
0259 justification in [1]
0260
0261 In sumary:
0262 The following two method are called before and after every SBS time step to pass molecules
0263 to the IRT method:
0264 + TimeStepAction::UserPreTimeStepAction()
0265 + TimeStepAction::UserPostTimeStepAction()
0266
0267 7 - STACKING ACTION
0268
0269 StackingAction::NewStage is called when a stack of tracks has been processed
0270 (for more details, look at the Geant4 documentation).
0271 A verification on whether physical tracks remain to be processed is done.
0272 If no tracks remain to be processed, the chemical module is then triggered.
0273
0274 8 - OUTPUT
0275
0276 The same output specifications from the chem6 example applies here, with the
0277 following remarkable differences:
0278 + Both the ScoreSpecies and the ScoreStrandBreaks scorers have their own
0279 output methods. Both call OutputAndClear(), which writes the output
0280 files and cleans all the information currently stored in the scorers,
0281 in preparation for the next run.
0282 + The OutputAndClear() method is called in the RunAction::EndOfRunAction()
0283 method.
0284
0285 9 - RELEVANT MACRO FILES
0286
0287 Two user macro files can be used:
0288
0289 - RunExample.in
0290 + Single Run example.
0291 + 100 repetitions of 880 electrons (~5 Gys) in a 1 um diameter volume
0292 containing 1 plasmids.
0293 + Caesium source.
0294
0295 - RunDoseDependance.in
0296 + This macro will repproduce results from S2 [1] (SBs Dose dependance).
0297 + DMSO conentration is set to 2.28E-4 M.
0298 + Oxygen Concentration is set to 0.27E-3 M.
0299 + Absorbed dose will be between ~1 - ~100 Gy.
0300 + 5 plasmids (28.1 ug/ml DNA concentration).
0301 + To reduce simulation time, the number of repetitions was lowered to 10.
0302 + Currently, only 1 Thread is used. Users are advised to increase the number
0303 of threads.
0304 + Simulation time can take up to a couple of days depending on the specific PC.
0305
0306 - init_vis.in
0307 + Default macro file to be used if user doesn't specify any macro file at run.
0308 + It calls the vis.in macro which will draw the OpenGL visualizer.
0309
0310 - vis.in
0311 + Visualization parameters for the default macro file. 1 plasmid will be draw at the center.
0312
0313 10 - PLOT
0314
0315 - No PLOT/Analysis files are prodived due to the default ASCII output.
0316 - ASCII files can be handled by most of the plot tools.
0317
0318 11 - EXTRA FILES
0319
0320 - CaesiumSource.src
0321 + Sample electron spectrum for the simulation.
0322 + Secondary electrons generated by a Caesium Gamma Source [1].
0323
0324 - CobaltSource.src
0325 + Sample electron spectrum for the simulation.
0326 + Secondary electrons generated by a Cobalt Gamma Source [1].
0327
0328 - pUC19.xyz
0329 + A sample pUC19 (2686 base pairs) plasmid with -0.03 super helix density generated at 20 C.
0330 The plasmid file has the position of each individual base pair. Values are given in nm
0331
0332 - PlasmidOffsets.txt
0333 + A sample plasmid centroid file. Users can change this values manually as long
0334 as they do not fall outside of the water sphere. In this way is possible to move
0335 the plasmids generated in the simulation. Values are given in nm.
0336
