$\texttt{PATHMC}$ (Particle-based Approach to cHemical dynamics using Monte Carlo) is a refined chemical stage simulator for modeling diffusion and chemical reactions of species incorporating interaction potentials.

The existing step-by-step diffusion and reaction models are refined to explicitly account for Coulomb interactions:

• Diffusion model: The interaction potential is incorporated into the stochastic equations of motion;
• Reaction model: A Coulomb-corrected missed-reaction probability is derived, and unreactive partially diffusion-controlled encounters are resolved within the local force field.

Contact
Mail	info@pathmc.org
URL	pathmc.org

Building $\texttt{PATHMC}$

$\texttt{PATHMC}$ is cross-platform and requires a compiler with support for the $\texttt{C++20}$ standard; therefore, $\texttt{GCC16}$ is recommended for Linux systems, and and $\texttt{MSVC~2019}$ or later on Windows systems.

$\textsf{(i)}$ $\texttt{LINUX}$

For Linux systems, the provided $\texttt{Makefile}$ can be used with $\texttt{g++}$ to build $\texttt{PATHMC}$. The build should be performed in a separate build directory:

mkdir build
cd build
make -f ../Makefile

After the executable has been built, the required simulation input data and directory structure must be copied into the build directory. This includes simulation parameter files, such as species and reaction tables, as well as the directory structure expected by $\texttt{PATHMC}$, including folders such as $\texttt{PRECHEM}$, $\texttt{LOG}$, $\ldots$ Therefore, the following command must be executed once for a fresh build directory:

make -f ../Makefile copy_dirs

After this step, the build directory contains the $\texttt{PATHMC}$ executable and the minimal set of files and folders required to run a simulation.

$\textsf{(ii)}$ $\texttt{WINDOWS}$

For Windows systems, the build procedure is analogous. However, $\texttt{nmake}$, which is included in the $\texttt{MSVC}$ toolset, must be used instead of $\texttt{make}$, together with the supplied $\texttt{Makefile.msvc}$.

Running an example

To verify that the build was successful, run the supplied example simulation from the build directory:

pathmc -m IN_MAC/example_in.mac

Structure of $\texttt{PATHMC}$

$\texttt{PATHMC}$ can be called via the command line with a variable number of parameters according to the following syntax:

pathmc -arg1 <opt1> -arg2 <opt2> -arg3 --arg4long ...

The most relevant command-line arguments are:

Short argument	Long argument	Description
$\texttt{-i}$	$\texttt{--version}$	$\textsf{Display program information}$
$\texttt{-h}$	$\texttt{--help}$	$\textsf{Display the help and command table}$
$\texttt{-m }$	$\texttt{--mac }$	$\textsf{Path to the \texttt{*.mac} input file}$
		$\textsf{\textit{see \texttt{-h} for more.}}$

Some example calls are:

pathmc --version
pathmc -m IN/in.mac
pathmc -m IN/in.mac --pot 1
pathmc -m IN/in.mac --pc PRECHEM/prechem/_1/_MeV.txt

For typical simulations, only the input file needs to be specified on the command line, since all additional parameters are defined in that file:

pathmc -m <input_file>.mac

Generating PRECHEM files

Before a simulation with $\texttt{PATHMC}$ can be started, a phase-space file containing the initial chemical configuration is required. This file can be generated, for example, with $\texttt{Geant4-DNA}$. The coordinates and names of the chemical species, or alternatively their IDs, must be written to an output file at $1,\mathrm{ps}$, corresponding to the beginning of the chemical stage. This prechemical file, referred to as the $\texttt{prechem}$ file, follows a simple $\texttt{csv}$ structure:

MOL_NAME ;    x / nm ;    y / nm  ;    z / nm
e_aq^-1;      28.9887;    -94.2703;    3333.73
e_aq^-1;       7.5753;    -73.0198;    3370.02
...

$\textsf{Remark.}$ The species names specified in the MOL_NAME field must match the corresponding definitions in the species and reaction tables provided by the $\texttt{*.xml}$ files in the CHEM_TABLES directory. Example prechemical configuration files are available in the PRECHEM subfolder.

Defining a species and reaction table

Before defining the reactions, the chemical species must first be specified. In particular, the charge used for Coulomb interactions must be provided, together with information on whether spin-controlled reactions should be modeled explicitly. If <SPIN> is not defined, spin effects are not treated explicitly and are instead included implicitly through the specified bulk reaction rate. An example is shown below:

<?xml version ="1.0"?>
<SPECIES_DATA>
    <SPECIES>
        <NAME>e_aq^-1</NAME>
        <D>4.9E-9</D>
        <Q>-1</Q>
        <R>0.5E-9</R>
        <SPIN>1</SPIN>
    </SPECIES>
    ...
</SPECIES_DATA>

Scavengers are defined by a concentration $c$ and a vanishing diffusion constant, $D \equiv 0$:

<SPECIES>
    <NAME>O2</NAME>
    <D>0</D>
    <C>5.2E-4</C>
</SPECIES>

If no scavengers are defined, the background model is not initialized; the log file reports on all background particles. The species table must be saved as an $\texttt{*.xml}$ file. The diffusion coefficients are given in $\mathrm{m^2}$ $\mathrm{s^{-1}}$, radii in $\mathrm{m}$, and concentrations in molar units, $\mathrm{M}=\mathrm{mol}$ $\mathrm{l^{-1}}$.

The reactions to be considered and their observed reaction rates $k_\mathrm{obs}$ must then be defined. The reaction rates are given in units of $10^{10},\mathrm{M^{-1}}$ $\mathrm{s^{-1}}$ and are automatically read from a $\texttt{*.xml}$ file. The reaction type <TYPE> must also be specified explicitly if partially diffusion-controlled reactions are to be resolved in the force field. If no type is given, the reaction is assumed to be of type 1, i.e. totally diffusion-controlled. The reactions are defined as follows:

<?xml version ="1.0"?>
<REACTION_DATA>
    <REACTION>
        <REACTANT>H^0</REACTANT>
        <REACTANT>e_aq^-1</REACTANT>
        <PRODUCT>H_2^0</PRODUCT>
        <PRODUCT>OH^-1</PRODUCT>
        <K>2.5</K>
        <TYPE>1</TYPE>
    </REACTION>
    <REACTION>
        <REACTANT>e_aq^-1</REACTANT>
        <REACTANT>H3O^1</REACTANT>
        <PRODUCT>H^0</PRODUCT>
        <K>2.11</K>
        <TYPE>4</TYPE>
    </REACTION>
    ...
</REACTION_DATA>

The species names specified in the reaction table must already be defined in the species table; Type 6 reactions are identified automatically if one of the reactants has been defined as a scavenger. For clarity, the reaction tables should be stored in the CHEM_TABLES/... subdirectory, although this is not required.

Input file

Before execution, the simulation parameters must be defined in an input file with the following simple structure:

# Example PATHMC input file
# This is a comment...
PRECHEMF PRECHEM/<folder_of_configurations> # "PRECHEM" FOR FILE, "PRECHEMF" FOR FOLDER
REACTION_TABLE CHEM_TABLES/rt_g4.xml        # PATH TO REACTION TABLE
SPECIES_TABLE CHEM_TABLES/st_g4_spin.xml    # PATH TO SPECIES TABLE
DT_MIN 1E-12                                # MINIMUM TIME STEP
T_FINAL 1.1E-8                              # END SIMULATION TIME
TIMESTEP_MODE 1		                        # 0 = STATIC (DT_MIN), 	1 = DYNAMIC
POTENTIAL_MODE 1	                        # 0 = FORCE_FREE, 	    1 = PAIR_POTENTIAL
VERBOSE 0                                   # DETAIL OF OUTPUT AND LOGGING
BINS 20                                     # TEMPORAL BINS FOR SCORING
SEED 3141592                                # RANDOM SEED
END                                         # END OF INPUT FILE

Particular attention should be paid to the terminating END statement. The input file has a simple structure: each command, for example PRECHEMF, is followed by its corresponding value. In this case, the value specifies the path to the prechemical configuration directory. Similarly, SPECIES_TABLE and REACTION_TABLE define the file paths to the species and reaction tables, respectively. The parameters DT_MIN and T_FINAL set the lower time-step limit and the termination time, respectively. The option TIMESTEP_MODE controls dynamic time-step scaling. This scaling consists of a drift-controlled and a reaction-controlled contribution, allowing propagation in the force field while preventing reactions from being missed with a certain confidence. POTENTIAL_MODE enables or disables the interaction potentials in the diffusion model.

If PRECHEM is used, $\texttt{PATHMC}$ is initialized in single-file mode. In this case, only one event is executed and the corresponding output is generated. If the PRECHEMF command is used instead, the specified value is interpreted as a directory containing multiple prechemical configuration files. These files are processed sequentially in multi-file mode. At the end of this procedure, a summary file containing the mean $G$ value is generated automatically and written to a file with the suffix *.gval_sum. If the name of a prechemical configuration file contains the deposited energy in $\mathrm{eV}$, the $G$ value is calculated. Otherwise, the number of species is written instead.

At this point, all requirements for running a simulation are met. Once the input file with extension $\texttt{*.mac}$ has been placed in the IN_MAC directory, the simulation can be started. During execution, the simulation reports its progress and the $G$-value save points through the console output; the following output is printed continuously:

---------- BEGIN : G - VAL SAVE POINT =>
t           e_aq    OH-     OH*     H2      H3O+    H*      H2O2    ...
2.51189e-07 36      4       34      5       40      6       9       ...
---------- END : G - VAL SAVE POIN

This output contains the current simulation time and the species-resolved counts used to calculate the $G$ value at the corresponding time point.

Output of a run

$G$ values, species and reaction counts

All output files, including $\texttt{G}$-value files with the suffix $\texttt{.gval}$ and reaction-frequency files with the suffix $\texttt{.rstat}$, are stored in the $\texttt{AUSGAB}$ directory. Depending on the execution mode, the files are either written directly to this directory in single-file mode or to a subdirectory named after the RUN_ID in multi-file mode.

HTML log file

After completion of the simulation, an $\texttt{HTML}$ log file LOG_<INPUT_FILE>_<RUNID>.HTML log file is automatically generated in the LOG directory, which reports on the success of the run, possible errors, the species and reaction table, and all simulation parameters and outputs: an example log file can be found here.

License and third-party notices

Unless otherwise noted, the original code authored for $\texttt{PATHMC}$ is licensed under the MIT License; see LICENSE. This repository includes third-party components under their respective licenses; see LICENSE_THIRD_PARTY.md for details.