
///\file "medical/dna/moleculardna/.README.txt"
///\brief Example molecularDNA README page

/*! \page Examplesmoleculardna Example moleculardna

\author N. Lampe, M. Karamitros, D. Sakata, W. G. Shin, M. Dordevic, K.
Chatzipapas, H. N. Tran (*) et
al.\n
(*) contact: tran@cenbg.in2p3.fr

This example is provided by the Geant4-DNA collaboration.
(http://geant4-dna.org)

Any report or published results obtained using the Geant4-DNA software shall
cite the following Geant4-DNA collaboration publications:
- Med. Phys. 45 (2018) e722-e739
- Phys. Med. 31 (2015) 861-874
- Med. Phys. 37 (2010) 4692-4708
- Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178

These two PhD theses describe the chain:
- W.-G. Shin (2020): https://tel.archives-ouvertes.fr/tel-03161030
- N. Lampe (2017): http://www.theses.fr/2017CLFAC011

Related publications can be found at:http://geant4-dna.org

\section MOLECULARDNA_s0 INTRODUCTION

This example shows how to simulate physics, physico-chemistry and chemistry
processes in DNA geometries.
Please find its documentation in https://natl.github.io/molecular-docs/

To build the example:
\verbatim
mkdir build
cd build
cmake ../pathToExamples/moleculardna
make
\endverbatim

To run the example:
\verbatim
./molecular -m cylinders.mac -t 2 -p 2
# -m : macro file
# -t : number of threads to run
# -p : physics list option
\endverbatim

Macro files can control every aspect of the simulation.

\section MOLECULARDNA_s1 GEOMETRY DEFINITION

The geometry is built from text files for cylinders (cylinders.mac),
ecoli (ecoli.mac) and human cell (human_cell.mac) geometries.

- cylinders.mac : to build a 3 μm sphere filled with 200,000 individual 216 bp
  long straight DNA segments in a 100×30×30 nm placement volume
- human_cell.mac : to model a fibroblast cell geometry. This mac file, may be used
to produce data that may be used with the repair model, to produce results published
in https://doi.org/10.1002/pro6.1186
- ecoli.mac : to demonstrate a simple model where the bacterial DNA follows a
  large scale fractal ‘Hilbert curve’ geometry
- more geometry information can be found in https://natl.github.io/molecular-docs/

For the details, please see documentation to construct DNA geometry models:
  http://natl.github.io/fractaldna/

Macro commands can be used to control the geometry parameters

\verbatim
# Commands for world geometry params
/world/worldSize 10200 nm
/cell/radiusSize 3 3 3 um

# Commands for the time of chemistry simulation
/scheduler/endTime 1 us

# Set Smartless for logicalVolume
/dnageom/setSmartVoxels 1
# Check overlaps in DNA geometry region
/dnageom/checkOverlaps false # default

# Distance from base pairs at which to kill radicals
/dnageom/radicalKillDistance 9 nm

# Critical range to start recording SSBs from direct effects
/dnageom/interactionDirectRange 7 angstrom

# Side length for each placement (x, y, z)
/dnageom/placementSize 30 30 100 nm

# Scaling of XYZ in fractal definition file
/dnageom/fractalScaling 1 1 1 nm

# Path to file that defines placement locations (cylinders.mac)
/dnageom/definitionFile geometries/prisms200k_r3000.txt

# Set a placement volume [format] [name path] (cylinders.mac)
/dnageom/placementVolume prism geometries/straight-216-0.txt

# Take the angles in the voxel placement file as multiples of pi
# E.g. set to true if the angle 0.5 should mean 90 degrees
/dnageom/setVoxelPlacementAnglesAsMultiplesOfPi false # default

# The molecule size columns are optional, as they can either
# fall back onto the default sizes or be set to custom sizes in the macro
# used default moleculeSize (as belows)
/dnageom/useCustomMoleculeSizes false # default
#/dnageom/moleculeSize

# Draw cell/chromosome volumes rather than DNA (makes DNA invisible)
/dnageom/drawCellVolumes false # default

# Activate Histone scavenging function with default radius
/dnageom/activateHistoneScavenging true # default

# DNA geometries are only ever placed in a chromosome
/chromosome/add cylinder sphere 3000 0 0 0 nm

# For the visualisation of DNA geometries, the following line can be used
/control/execute vis.mac
# More specifically, start moleculardna using the command ./molecular, to
# to open the Qt visualiser. Then use the mac file that you want, e.g.
# /control/execute cylinders.mac
# For the visualization, large amount of RAM is needed. For example
# using cylinders DNA geometries, to visualize 200 cylinders, ~2.5 GB
# are needed. For 2000 cylinders, ~11 GB are needed.

\endverbatim

The DNA parallel world can be activated using the "useParallelPhysicsWorld" flag
in the PhysicsList.cc and DetectorConstruction.cc files for the physics stage.
Setting "useParallelPhysicsWorld = false" means that particles will only interact
with the water volume. Energy deposition in water caused by direct damage is
recorded using octree data structures associated with DNA volumes.

\section MOLECULARDNA_s2 PHYSICS LIST

MolecularPhysicsList is a Geant4 modular physics which can use the recommended
G4EmDNAPhysics_option2, G4EmDNAPhysics_option4 or G4EmDNAPhysics_option6 constructors.

\section MOLECULARDNA_s3 PRIMARY GENERATOR

The source can be specified via General Particle Source in the provided macro files.

\section MOLECULARDNA_s4 DNA DAMAGE MODEL

Mechanistic DNA simulations are dependent upon a
DNA damage model to relate energy depositions close to DNA,
and chemical reactions with DNA to actual DNA damage

The fowlling macro commands is used to control the damage parameters

\verbatim
# Direct damage Threshold
/dnadamage/directDamageLower 17.5 eV
/dnadamage/directDamageUpper 17.5 eV

# Indirect damage probability to create a SSB for
# OH radical + DNA base,
/dnadamage/indirectOHBaseChance 1.0
/dnadamage/indirectOHStrandChance 0.65
/dnadamage/inductionOHChance 0.0

# H radical + DNA base
/dnadamage/indirectHBaseChance 1.0
/dnadamage/indirectHStrandChance 0.65
/dnadamage/inductionHChance 0.00

# e_aq radical + base
/dnadamage/indirectEaqBaseChance 1.0
/dnadamage/indirectEaqStrandChance 0.65
/dnadamage/inductionEaqChance 0.00
\endverbatim

\section MOLECULARDNA_s5 RESULTS

\verbatim
# Bool to set whether strands ought be saved
/analysisDNA/saveStrands false # default

# Directory to save DNA damage fragments
/analysisDNA/strandDir

# Gap between DNA fragments in base pairs
# Set to zero to score placement volumes independently
/analysisDNA/fragmentGap 0

# To save the position of hits histos only on one chain
/analysisDNA/diagnosticChain
\endverbatim

Several ROOT macro files are provided in the analysis directory:
\verbatim
root cylinders.C
# to plot damage from cylinders geometry

root ecoli.C
# to plot damage from ecoli geometry

root human_cell.C
# to plot damage and fragments distribution from human_cell geometry


# A python macro file is provided to modify ROOT output in SDD file format:
python createSDD.py
# to use it, insert the command "python3 createSDD.py".
# If error with root, simply source /path/to/root/bin/thisroot.(c)sh,
# do "pip install pyroot" and try again.

# A python macro file to calculate repair kinetics is located in the folder
# repair_survival_models. This script can be used with the output of the mac
# file human_cell (10^5 primaries) to reproduced data published in
# https://arxiv.org/abs/2210.01564
molecularDNArepair.py
# to use it, insert the command "python3 molecularDNArepair.py".
# The molecular-dna.root is also needed to run it, as produced by
# the human-cell.mac.

# A python macro file to calculate the survival probability of cells is located
# in the folder repair_survival_models. This script is early released and needs to be optimized
# to fit any data.
molecularDNAsurvival.py
# to use it, insert the command "python3 molecularDNAsurnival.py".
# The molecular-dna.root is needed to run it, as produced by
# the human-cell.mac.
\endverbatim

\section MOLECULARDNA_s6 PHASE SPACE READING

The example can read a phase space file as source for the primary generation,
defined in the csv format used by the GRAS Two-Stage Analysis [1].
An example of phase space file and the macro to read it are provided in the
"/phase_space" subdirectory. This simple phase space file only provides 20 electrons
with an energy of 45 keV on a randomly shaped surface based on the cylinders.mac macro file.

An alternative example for DNA damage calculation can be found in /examples/advanced/dsbandrepair

\section MOLECULARDNA_s7 Reference

\verbatim
[1] https://spitfire.estec.esa.int/trac/GRAS/wiki/GRAS/GRAS-05-02/UserGuideTwoStage
\endverbatim
*/
