utaresearch / gmicromc

gMicroMC_v2.0

We are collecting user feedbacks to further improve this package. Please don't hesitate to contact us via [email protected] if you have any comments. Much appreciated!

Correpondance: [email protected] and [email protected]

Researchers are welcomed to modify and distribute this package for non-commercial purpose. The authors claim no responsibility for the results produced by users. For credit recognition, please kindly cite

• Initial development
  Tsai, M. Y., Tian, Z., Qin, N., Yan, C., Lai, Y., Hung, S. H., ... & Jia, X. (2020). A new open‐source GPU‐based microscopic Monte Carlo simulation tool for the calculations of DNA damages caused by ionizing radiation‐‐‐Part I: Core algorithm and validation. Medical physics, 47(4), 1958-1970.
• Oxygen module
  Lai, Y., Jia, X., & Chi, Y. (2021). Modeling the effect of oxygen on the chemical stage of water radiolysis using GPU-based microscopic Monte Carlo simulations, with an application in FLASH radiotherapy. Physics in Medicine & Biology, 66(2), 025004.
• Proton, heavy ions and concurrent transport of DNA
  Lai, Y., Jia, X., & Chi, Y. (2021). Recent Developments on gMicroMC: Transport Simulations of Proton and Heavy Ions and Concurrent Transport of Radicals and DNA. International journal of molecular sciences, 22(12), 6615.

Updated features

May 3rd, 2021

1. Updated gMicroMC package with more comments and smoother control of the output by using class
2. All fuctions were divided into two types, kernel functions executed by GPU in *.cu files and typical *.cpp files

Overview about the package

To make full use of this package and get meaningful results, users are suggested to well understand the general picture of microscopic MC simulation and the function of gMicroMC.

1）General picture of microscopic MC simulation

The microscopic MC simulation describes the process from the ionizing particle entering the cellular nucleus to the DNA damage formation. The entire process was decribed in three stages:

• physical stage, which describes the physical transport of the ionizing particles through a medium filled with water molecules, typically lasting from 10^-15 s to 10^-12 s.
• physicochemical stage (sometimes referred to prechemical stage), which simulated the water radiolysis process with production of free chemical radicals.
• chemical stage, which deals with the diffusion and mutual ractions among chemical radicals, covering time scale from 10^-12 s to 10^-6 s. In our most recent development, oxygen molecules and DNA structures were also considered during this stage.
• Finally, all the physical events and radical attack produce DNA damage, which are clustered into Double Strand Break (DSB) and Single Strand Break (SSB). Interested users are encouraged to read the following papers and the references therein for more details:

1. Friedland W, Dingfelder M, Kundrát P and Jacob P 2011 Track structures , DNA targets and radiation effects in the biophysical Monte Carlo simulation code PARTRAC Mutation Research - Fundamental and Molecular Mechanisms of Mutagenesis 711 28-40
2. Nikjoo H, Emfietzoglou D, Liamsuwan T, Taleei R, Liljequist D and Uehara S 2016 Radiation track , DNA damage and response — a review Reports on Progress in Physics 79 116601
3. Tsai M, Tian Z, Qin N, Yan C, Lai Y, Hung S-H, Chi Y and Jia X 2020 A new open-source GPU-based microscopic Monte Carlo simulation tool for the calculations of DNA damages caused by ionizing radiation --- Part I: Core algorithm and validation Med. Phys. 47 1958-70
4. Lai, Y., Jia, X., & Chi, Y. (2021). Modeling the effect of oxygen on the chemical stage of water radiolysis using GPU-based microscopic Monte Carlo simulations, with an application in FLASH radiotherapy. Physics in Medicine & Biology, 66(2), 025004.
5. Lai, Y., Jia, X., & Chi, Y. (2021). Recent Developments on gMicroMC: Transport Simulations of Proton and Heavy Ions and Concurrent Transport of Radicals and DNA. International journal of molecular sciences, 22(12), 6615.

2）What the package can provide

The advantage of using gMicroMC is to make a full use of GPU to accelerate the simulation process. It is very important as improving computational efficiency could enable more realistic yet computation-requiring simulations, for example, treating oxygen explicitly as molecules in the early age of chemical stage rather than viewing them as continuum background. The package does not introduce new physical or chemical interpretation. Hence, what gMicroMC can provide is basically the same as other CPU packages:

• Deposited energy, positions, track index etc. in the physics stage. (Check Data structure)
• Initial types of radicals and their distributions. (Check output from prechemical stage)
• Yields of different radicals at different moments, DNA damage sites in chemical stage.
• DNA strand break pattern after DNA damage grouping.

---

Usage

Structure

The code is structured as
./ root folder
    ./src/ --> source code
    ./inc/ --> header files
        ./inc/rapidjson --> rapidjson library to deal with json files
    ./tables/ --> predefined data for different process
        ./tables/physics --> physics cross sections
        ./tables/prechem --> info for decay channels and recombination of hydrated electrons
        ./tables/chem --> info for species and their reactions
        ./tables/dna --> stored dna structure in multiscale
    ./output/ --> output directory

Compile

nvcc main.cpp ./src/* -o gMicroMC -I ./inc -rdc=true
or
make

Run the program

After compilation, the users needs to provide correct config.txt file, where illustration of parameters have been listed.
Then running ./gMicroMC command will give you output files as defined in the config.txt.

The work flow is
prepare arrays like random seeds
--> generating initial particles physicsList::h_particles
--> simulate physics stage physicsList::run()
--> store initial positions and types of water molecules physicsList::saveResults()
--> reading prechemical stage PrechemList::readWaterStates()
--> simulate prechemical stage and save results PrechemList::run()
--> reading chemical stage ChemList::d_posx, ChemList::d_posy, ChemList::d_posz, ChemList::d_ttime, ChemList::d_ptype, ChemList::d_index
--> run chemical stage ChemList::run()
--> save results ChemList::saveResults()
--> read in for DNA damage analysis DNAList::posx
--> simulated DNA damage analysis DNAList::run()
--> DNA damage summary DNAList::saveResults();

All information is given in config.txt file, which is in json format.

Note

1. the saveResults() and readIn functions are not required mandatorily. Users can directly set the values in corresponding host arrays. For example, instead of physicsList::saveResults() and then prechemicalList::ReadIn(), users can directly set values of prechemicalList::posx, prechemicalList::posy, prechemicalList::posz, prechemicalList::ptype, prechemicalList::ttime, prechemicalList::index. This can be done in main.cpp fuction.
2. The reason why saveResults() fuction exists is due to the concern of memory. It is safer to save into files and then either read in by batchs or apply constraints to reduce the number of events (radicals).
3. The users have full freedom to change the data in ./tables folder, which could alter the defined physics interaction or decay channel. So be careful.

gmicromc's Issues

G-value

Hi, I have read the two articles linked to this project and tried to run the code myself. I have not clear if the G-values of the different free radicals (plotted as a function of time in the articles) are obtained directly somewhere in the outputs or it is calculated later from the outputs.
In the first scenario, in which output file is that saved?

Thanks

gMicroMC/phy_stage/compile_cuMC, the compile command needs a change

From:
/usr/local/cuda-10.1/bin/nvcc microMC.cu readtbl.cu -G -g -arch=sm_35 -rdc=true -lcudadevrt -lcuda -lcudart -o microMC

To:
nvcc microMC.cu readtbl.cu -G -g -arch=sm_35 -rdc=true -lcudadevrt -lcuda -lcudart -o microMC

since most users will have nvcc in there PATH already just nvcc is better, a lot of users will end up having to edit this if they don’t have this exact path and encounter errors on their system whilst compiling.

Thank you

prechem_stage/main.cu (Line 40)

prechem_stage/main.cu (Line 40):

parData_pc.readInitialParticles_GEANT4("../phy_stage/output/result.txt");

This directory doesn’t exist in the file structure of the code, so an empty directory: ./phy_stage/output is needed to be made.

Without it present, segfaults are received when running the code due to it not existing.

Cannot startup an example - CUDA Error at src/initialize.cpp:20

Linux version:
Debian GNU/Linux 11 \n \l

./gMicroMC
Output:

rm: cannot remove './output/*': No such file or directory
{
//global setting
"Device": 0, // device to be used
"startStage": 0, // 0 for physics stage, 1 for prechemical stage, 2 for chemical stage, 3 for DNA searching
"outputDir": "./output/",
"NPART": 262144,
"NRAND": 262144,
"NTHREAD_PER_BLOCK": 256,
"verbose":3,
"targetEneDep": 2.5e6, //eV,
//physics stage
"GPUBaseMemory":300, // in MB
"nSecondPer100keV":5000,
"nRadicalsPer100keV":8000, // increase them if encounter memory issues

    "pCSData":"./tables/physics/totalProtonCS3.dat",
    "eDACSData":"./tables/physics/DACS.txt",
    "eIonCSData":"./tables/physics/ionizationCS.txt",
    "eExcCSData":"./tables/physics/excitationCS.txt",
    "eElaCSData":"./tables/physics/elasticCS.txt",
    "eElaDCSData":"./tables/physics/elasticDCS.txt",

    "eECutoff": 7.5, //eV
    "pECutoff": 100,

    "physicsWorldShape":1, // 0 for sphere with radius= physicsWorldSizeX, 1 for box with ROISizeX=the side length along x axis
    "physicsWorldSizeX":0.01, // in cm
    "physicsWorldSizeY":0.01,
    "physicsWorldSizeZ":0.01,
    "physicsWorldCenterX":0, // in cm
    "physicsWorldCenterY":0,
    "physicsWorldCenterZ":0,

//define ROI
"ROIShape":1, // 0 for sphere with radius=ROISizeX, 1 for box with ROISizeX=the side length along x axis
"ROISizeX":5.5,// in um
"ROISizeY":5.5,
"ROISizeZ":5.5,
"ROICenterX":0, // in um
"ROICenterY":0,
"ROICenterZ":0,

    "nPar": 1, // particle number per run

"maxRun": 1, // maximal runs. Maximal particle simulated=nPar*nRun
"sourceModel": 1, // 0 for PSF file, 1 for random in sphere.
"sourceEnergyModel": 0, // only works if sourceModel!=0. 0 for not using histogram files and uniform inside emin and emax
// 1 for using histogram files
"sourceFile":"./input/source.txt", // PSF filename if sourceModel=0, histogram file name if (sourceModel!=0 && sourceEnergyModel==1)
// The following five parameters only work when sourceModel!=0, i.e., not using PSF files.
"sourceSampleDim": 0.0001, // unit cm, radius for sourceModel=1,
// for other distributions, please reload physicsList::iniParticle()
"sourcePType": 1,
"sourceA": 1, // 1 for proton and 0.0054 for electron
"sourceEmin":20e7, //eV
"sourceEmax":20e7,

    "fileForIntOutput":"./output/phyint.dat",
    "fileForFloatOutput":"./output/phyfloat.dat",
    "fileForTotalEvent":"./output/totalphy.dat",
    "fileForEnergy":"./output/phyEne.txt",

//physicochemcial stage
"fileForBranchInfo": "./tables/prechem/branchInfo_prechem_org.txt",
"fileForRecombineInfo": "./tables/prechem/thermRecombInfo_prechem.txt",
"fileForIntInput": "./output/phyint.dat",
"fileForFloatInput": "./output/phyfloat.dat", //default by physics stage
"fileForOutput":"./output/prechemRes.dat",

//chemical stage
"fileForSpecInfo":"./tables/chem/RadiolyticSpecies.txt",
"fileForReactionInfo":"./tables/chem/Type1_ReactionInfo.txt",
"useConstantRadius":0, // reaction radius changes with time step? 1 for no 0 for yes
"fileForRadicalInfo":"./output/prechemRes.dat", // if followingprechemical stage, the name should be the same as "fileForOutput" for prechemical stage
"chemicalTime":2500, //2500, //unit ps, t_c in the paper
"DNAReactTime":10000, //unit ps, t_i in the paper

    "timeFileForNvsTime":"./output/Time.dat",
    "numberFileForNvsTime":"./output/nRadical.dat",
    "saveInterval":5, //ps
    "chemROI": 5500, //nm

    "fileForChemOutput":"./output/chemRes.dat",

//DNA related
"bentChromatin":"./tables/dna/BentChromatinFiberUnitTable.txt", // files for reading DNA structure
"bentHistone":"./tables/dna/BentHistonesTable.txt",
"straightChromatin":"./tables/dna/StraightChromatinFiberUnitTable.txt",
"straightHistone":"./tables/dna/StraightHistonesTable.txt",
"wholeDNA":"./tables/dna/WholeNucleoChromosomesTable.bin",

    "fileForChemPos":"./output/chemRes.dat",
    "fileForOutputDamage":"./output/finalstat.txt",
    "compareEnergy":8711450, // in eV
    "repTimes":1,

    "probChem":0.4

}

verbose is 3
NPART is 262144
NRAND is 262144
NTHREAD_PER_BLOCK is 256
trying to use device 0
Number of device: 32766
Using device #: 0
Major revision number: 0
Minor revision number: 0
Name:
Total global memory: 0.00 MB
Total shared memory per block: 0.00 kB
Total registers per block: 0
Warp size: 0
Maximum memory pitch: 0
Maximum threads per block: 0
Maximum dimension of block: 000
Maximum dimension of grid: 000
Clock rate: 0.00 GHz
Total constant memory: 0.00 kB
Texture alignment: 0
Concurrent copy and execution: No
Number of multiprocessors: 0
Kernel execution timeout: No

Start initialize random numbers
CUDA Error at src/initialize.cpp:20

Binary output.dat reading

Hi again,
I was wondering if you might share how do you read the binary files and combine their information after the simulation.
Since they are binary file.dat I am not able to read and process them.

Moreover, I am trying to use this code along with Geant4, what lower energy cut is used for the produced electrons in gMicro?

Many thanks!

gMicroMC binary removal

gMicroMC is a binary and can be compiled from main.c or just be a bash script (if possible), it will save users having to compile an auto run script....Compiling a code that compiles code and runs it is a is a bit confusing.

How to Run section updating

Doing the steps to run the code manually doesn’t work/are a bit confusing (following the instructions in the readme in the how to run section):

./phy_stage/microMC config.txt
./prechem_stage/prechem 0
….

Since the code is hard wired to read paths relative to the current directory from where the executable is run, these need to be executed in the directory they are located in ( just like gMicroMC-master/main.c does ), not using the paths above.

It would be good if the How to Run section could be changed a little bit to reflect this. Also in part III the instructions “cp ./phy_stage/output/outputtotalphy.dat ./chem_stage/Results” doesn’t work since outputtotalphy.dat doesn’t exist and isn’t produced by running “./prechem 0”, it should be “cp ./phy_stage/output/totalphy.dat ./chem_stage/Results”