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

/*! \page Examplesmoleculardna Example moleculardna

\author J.M.C. Brown, K. Chatzipapas, P. Dondero, M. Dordevic, S. Incerti, M. Karamitros,
N. Lampe, D. Sakata, W.G. Shin, R. Stanzani, H. Tran (*), S. Zein\n

(*) contact: tran@lp2ib.in2p3.fr

Dedicated website:
http://moleculardna.org
or
https://geant4-dna.github.io/molecular-docs/

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

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

Any report or published results obtained using the Geant4-DNA software
shall cite the following Geant4-DNA collaboration publications:
Med. Phys. (2024) in press (https://doi.org/10.1002/mp.17256)
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

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 to predict early damage.

A more detailed description is available at http://moleculardna.org

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
# -v : visualization option
\endverbatim

Macro files can control every aspect of the simulation, see this introduction:
https://geant4-dna.github.io/molecular-docs/docs/overview/macro-anatomy

The macro commands of this example are listed in:
https://geant4-dna.github.io/molecular-docs/docs/overview/configuration

\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.
  This is a geometry used for parameter (optimization) studies.

- fiber.mac: to visualize a fiber of DNA

- phage.mac: to model the irradiation of a DNA phage containing 141158 bp,
  placed in a cylinder with radius 3.5 um and height 7 um.

- plasmid.mac: to model a cube of liquid water (side 4.84 um) containing around
  10 000 plasmids (pBR322, 4367 base pairs) randomly oriented in a supercoiled conformation.

- ecoli.mac: to demonstrate a simple model where the bacterial DNA follows a
  large scale fractal ‘Hilbert curve’ geometry.

- human_cell.mac, human_cell_HTB177.mac and human_cell_MCF7.mac: to model
  three different cell geometries, as detailed in [1]. These mac file may
  be used to produce data that serve as input to the repair models.

- human_cell_chromosomes.mac: to model the chromosomal type of cell geometry,
  as detailed in [4].

More geometry information can be found in https://geant4-dna.github.io/molecular-docs/docs/examples

To construct other DNA geometries, see http://natl.github.io/fractaldna/

To construct chromosomal or other complex DNA geometries, see https://github.com/konhat88/complexDNA

Macro commands can be used to control the geometry parameters

\verbatim
# Commands for world and cell dimensions
/world/worldSize 10200 nm
/cell/radiusSize 3 3 3 um

# Command to select the chemistry model (only IRT_syn for this example)
/process/chem/TimeStepModel IRT_syn

# End time of chemistry simulation
/scheduler/endTime 1 us

# Set voxel optimisation
/dnageom/setSmartVoxels 1

# Check overlaps in DNA geometry region
/dnageom/checkOverlaps false

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

# Deposited energy accumulation range to start recording SBs 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
/dnageom/definitionFile geometries/prisms200k_r3000.txt

# Set a placement volume [format] [name path]
/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 -t 1 -v 1
# 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

\section MOLECULARDNA_s2 PHYSICS LIST

The physics list 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 following macro commands can be 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 radicals + DNA base
/dnadamage/indirectHBaseChance 1.0
/dnadamage/indirectHStrandChance 0.65
/dnadamage/inductionHChance 0.0

# e_aq radicals + base
/dnadamage/indirectEaqBaseChance 1.0
/dnadamage/indirectEaqStrandChance 0.65
/dnadamage/inductionEaqChance 0.0
\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* geometries.
The human_cell_alphas.C macro can be used as shown in [1].

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

root plasmid.C
# to plot damage and fragments distribution from plasmid geometries

root human_cell_chromosomes.C
# to plot damage and fragments distribution from human_cell_chromosomes geometries.

# A python macro file is provided to modify ROOT output in SDD file format [2]:
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 is provided to analyse the output of chromosomal geometry simulation [4]:
human_cell_chromosomes.py
# to use it, insert the command "python3 human_cell_chromosomes.py".

# 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 reproduce data published in [3]:
molecularDNArepair.py
# to use it, insert the command "python3 molecularDNArepair.py".
# The molecular-dna.root file is also needed to run it, as produced by
# the human-cell.mac macro.

# 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 molecularDNAsurvival.py".
# The molecular-dna.root is needed to run it, as produced by
# the human-cell.mac macro.
\endverbatim

Note on ROOT import from python:
If python cannot import ROOT, please configure your ROOT version to include PyROOT.
For further instruction, refer to the documentation of ROOT, paragraph 19.1.4.2:
https://root.cern/root/htmldoc/guides/users-guide/ROOTUsersGuide.html#python-interface

\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 [5].
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 References

\verbatim
[1] https://doi.org/10.1016/j.ejmp.2023.102613
[2] https://doi.org/10.1667/RR15209.1
[3] https://doi.org/10.1002/pro6.1186
[4] https://doi.org/10.1016/j.ejmp.2024.104839
[5] https://spitfire.estec.esa.int/trac/GRAS/wiki/GRAS/GRAS-05-02/UserGuideTwoStage
\endverbatim

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

*/
