geant4/examples/advanced/dna/dsbandrepair/.README.txt

///\file "dsbansrepair/.README.txt"
///\brief Example dsbandrepair README page

/*! \page dsbandrepair Example %dsbandrepair

 
\section dsbandrepair_s0 AUTHORS

L. T. Anh, Y. Perrot, C. Villagrasa, S. Meylan, H. N. Tran

contact: yann.perrot@irsn.fr or le.tuan.anh@vinatom.gov.vn

\section dsbandrepair_s1 REFERENCE
Please cite:
Anh et al., Physica Medica 124 (2024) 103422, https://doi.org/10.1016/j.ejmp.2024.103422

\section dsbandrepair_s2 Introduction

  “dsbandrepair” is a Geant4-DNA simulation chain for evaluating the early radiation-induced DNA damage.
The first development of the simulation chain was carried out by Meylan et al. in 2017 (Sci. Rep. 2017 7:11923)
The "extended/medical/dna/dnadamage1" example is a simplified version of "dsbanrepair"

“dsbandrepair” supports all types of DNA geometries constructed with DNAFabric (Comput. Phys. Comm. 2016 204:159-169).
Geometries for human cell nuclei (fibroblast, endothelium) and yeast were provided along with the release of “dsbandrepair”.
Users can use a free version of DNAFabric (https://bitbucket.org/sylMeylan/opendnafabric/src/master/) to create customed geometries. Or they can contact Y. Perrot for specific geometries.
The geometric models are constructed from 10 voxels to form a continuous chromatin fiber for each chromosme including heterochromatin (VoxelStraight, VoxelRight,...) and euchromatin (VoxelStraight2, VoxelRight2,...) distribution (Med. Phys. 2019 46:1501-1511).

Physical stage and chemical stage allow the calculation of direct and indirect Strand Breaks in the whole nucleus.

Furthermore, repair models were added in the analysis part:

- The Two Lesion Kinetic model developed  by Stewart (Radiat. Res. 2001 156:365-378) provides a method to link DSBs (subdivided into simple and complex DSBs) with cell death. It suggests that DSB repair depends on the severity of the lesion. It includes non-saturable first and second order repair processes. DNA fragments associated with DSBs  can interact with each other in paors and form lethal or non-lethal chromosomal aberrations.

- The Local Effect Model IV from Tommasino et al (Radiat. Res. 2013 180:524-538) was included to calculate the fraction of un-rejoined DSBs.
It is based on the spatial distribution of DSBs by looking at the number of DSBs present in 2 Mbp chromatin loops.
DSBs in the loops are consideres as "isolated DSB" or "cluster of DSBs". the fraction of unrepaired DSBs is calculated by a two-phase exponential decay.

- The Belov's model (J. Theo. Biol. 2015 366:115-130) for double-strand breaks repair is provided but has not been compared to experimental data.

\section dsbandrepair_s3 How to build and run

   To build dsbandrepair, in the terminal, use:
\verbatim
- shell$ mkdir build
- shell$ cd build
- shell$ cmake /path-to/dsbandrepair  
(Or if users don't want to download geometry files while compiling the dsbandrepair, use: cmake -DDOWNLOAD_GEOMETRY=FALSE /path-to/dsbandrepair )
- shell$ make  (or 'make -jN' with N = 1,2,3 .... )
\endverbatim
And to run:
\verbatim
- shell$ ./dsbandrepair dsbandrepair.in
\endverbatim
where dsbandrepair.in is a macrofile. User can change it to his/her own macrofile.

Note that: dsbandrepair was designed in a modular way that offers users to run physical stage chemcal stage independently. By default, dsbandrepair runs in physical stage mode. To run chemical stage, use :
\verbatim  
- shell$ rm -rf chem_ouput
- shell$ ./dsbandrepair chem.in chem 
\endverbatim
where chem.in is a macrofile. User can change it to his/her own macrofile.


\section dsbandrepair_s4 Running with mpi library

To improve the simulation in term of computational time, user can run dsbandrepair with mpi library.

MPI interface: Thanks to the work of K. Murakami and A. Dotti (DOI: https://doi.org/10.1109/NSSMIC.2015.7581867), an MPI interface was introduced into Geant4 and it’s now used in this work (see "/examples/extended/parallel/MPI"). User has to follow this example to install g4mpi library.

To compile the "dsbandrepair" with g4mpi:
\verbatim 
- shell$ mkdir build
- shell$ cd build
- shell$ cmake -DUSE_MPI=TRUE -DG4mpi_DIR=<g4mpi-path>/lib[64]/G4mpi-V.m.n /path-to/dsbandrepair  
- shell$ make  (or 'make -jN' with N = 1,2,3 .... )
\endverbatim
And to run:
\verbatim 
- shell$ mpiexec -np $nranks ./dsbandrepair dsbandrepair.in
\endverbatim

where $nranks is the number of mpi processes you want to run.

Or ro run chemical stage:
\verbatim
- shell$ rm -rf chem_ouput
- shell$ mpiexec -np $nranks ./dsbandrepair chem.in chem 
\endverbatim

\section dsbandrepair_s5 Analyzing results
To run "analysis" module, in the "build" directory, build this module with the commands:
\verbatim
- shell$  mkdir analysis
- cd analysis
- cmake /path/to/analysis
- make 
- cd ../
\endverbatim

At this point, user can launch the analysis module:
\verbatim
- shell$  ./analysis/runAna  
\endverbatim
or
\verbatim
- shell$  ./analysis/runAna macrofile
\endverbatim
where the macro file allows user to interact with the code. 
Example: ./analysis/runAna analysis.in 

\section dsbandrepair_s6 Outputs
By default, the output of "Analysis" module will be written in 4 different text files:
- SB results: this text file contains all SB results, such as total SB, direct and indirect SBs, SSB and DSB.
- SDD format: All damages are written in SDD format (Radiat. Res. 2019 191:11). File name starts with "SDD_" 
- TLK result: File name starts with "TLK_". This file contains results from TLK model.
- LEM-IV result: File name starts with "LEMIV_". This file contains results from LEMIV model.

\section dsbandrepair_s7 Maro files
Some macro files are provided along with this code, user can change them based on their own needs.

- macro files for physical stage:
    - dsbansrepair.in : This macro is for a light geometry for testing the code
    - fibroblast.in: This macro is for fibroblast cell nucleus.
    - endophys.in: This macro is for endothelium cell nucleus.
    - yeastphys.in: This macro is for yeast cell nucleus.
- macro files for chem stage:
    - chem.in
- macro files for analysis module:
    - analysis.in: allows user to set parameter for scoring, classifying damages and setting repair models parameters.

An alternative example for DNA damage calculation can be found in examples/extended/medical/dna/moleculardna

\section dsbandrepair_s8 Acknowledgments
The transition from the initial simulation chain of Meylan et al. to a version adapted for a Geant4 example benefited from funds from the BioRad3 project financed by the ESA (grant DAR 4000132935/21/NL/CRS)