LGMC - Lattice Gillespie Monte Carlo

A kMC implementation coupling a homogeneous (Gillespie-like) region with a lattice, enabling simulations with reactions occurring in multiple phases and capable of electrochemical reactions. Either Marcus of Butler-Volmer electron transfer theory (specified at runtime, see ‘Running LGMC’ below) can be used when calculating rates for electrochemical reactions. The lattice is periodic in the x, y direction and non-periodic in the z direction. The lattice may be static (no sites can be added or deleted) or dynamic (sites are added through adsorption and deleted through desorption reactions).

As a starting point two examples of LGMC uses are shown in Examples - LGMC with a static lattice to model CO Oxidation on Cu and LGMC with a dynamic lattice to simulate the formation and evolution of the solid electrolyte interphase in a lithium-ion battery.

Sqlite IO

Sqlite is used for input, output, and checkpointing. Before running LGMC two necessary .sqlite files must be generated - The Lattice Reaction Network Database and State Database. Examples of Python code used to generate these files are available in examples directory . Below is an outline of each .sqlite file and its necessary tables. Each .sqlite file must follow this format exactly.

The Lattice Reaction Network Database

There are two tables in the lattice reaction network database both of which must be created and filled in by the user:

metadata : this table consists of one line for the total number of species and reactions in the simulation.

CREATE TABLE metadata (
  number_of_species   INTEGER NOT NULL,
  number_of_reactions INTEGER NOT NULL
);

reactions : this table is how reactions are defined in the simulation. Only reactions of up to two reactants and products are supported. Each row in the table represents one reaction with the following attributes.

reaction_id : unique, starts at 0 and must increase in increments of one.
number_of_reactants/products : either 0, 1, or 2.
reactant_1|2 : unique, positive integer representative of a species. The integer representation of species must begin at 1 and increase in increments of one. The integer 0 is reserved to represent an empty site. If there is only one reactant/product then set the species to -1.
phase_reactant|product_1|2 : char representing if the species in the species is in the lattice(spatially resolved), L, or solution(homogeneous), S, region. If there are not two reactants|products, the phase can be set to N.
dG : gibbs free energy.
prefactor : prefactor applied during calculation of reaction rate.
rate : rate of the reaction.
electron_tunneling_coefficient : electron tunneling coefficient used for Butler-Volmer and Marcus calculations.
reorganization_energy : used for Marcus charge transfer.
charge_transfer_coefficient : charge transfer used for Butler-Volmer and Marcus calculations.
type : type of reaction:

A: adsorption
D: desorption
F: diffusion (only possible in lattice region)
L: reaction entirely in the lattice (spatially resolved region)
S: reaction entirely in the solution (homogeneous region)
O: oxidation
R: reduction

 CREATE TABLE reactions (
        reaction_id                     INTEGER NOT NULL PRIMARY KEY,
        number_of_reactants             INTEGER NOT NULL,
        number_of_products              INTEGER NOT NULL,
        reactant_1                      INTEGER NOT NULL,
        reactant_2                      INTEGER NOT NULL,
        product_1                       INTEGER NOT NULL,
        product_2                       INTEGER NOT NULL,
        phase_reactant_1                CHAR(1) NOT NULL,
        phase_reactant_2                CHAR(1) NOT NULL,
        phase_product_1                 CHAR(1) NOT NULL,
        phase_product_2                 CHAR(1) NOT NULL,
        dG                              REAL NOT NULL,
        prefactor                       REAL NOT NULL,
        rate                            REAL NOT NULL,
        electron_tunneling_coefficient  REAL NOT NULL,
        reorganization_energy           REAL NOT NULL,
        charge_transfer_coefficient     REAL NOT NULL,
        type                            CHAR(1) NOT NULL
);

The State Database

There are five tables in the initial state database all of which must be created by the user:

initial_state : this table represents the initial concentration of species. Each row consists of a species_id and corresponding quantity. If there is no row for a species, LGMC will initalize its quantity to zero. This table must be filled in by the user.
```
CREATE TABLE initial_state (
      species_id             INTEGER NOT NULL PRIMARY KEY,
      count                  INTEGER NOT NULL
);
```

trajectories : this table records each reaction run during the duration of the simulation. For each reaction the seed of the simulation that executed the reaction and corresponding step and time are recorded.

site_1|2_mapping : single integer representation of the i,j,k values of the lattice site involved in the reaction calculated with the Szudzik algorithm The ordering of the sites corresponds to the ordering of the products in the reaction. If one of the products is in the homogeneous region, site_1|2_mapping is equal to -2. If there is only one site involved in the reaction site_1|2_mapping is equal to -3.

 CREATE TABLE trajectories (
        seed                INTEGER NOT NULL,
        step                INTEGER NOT NULL,
        time                REAL NOT NULL,
        reaction_id         INTEGER NOT NULL,
        site_1_mapping      INTEGER NOT NULL,
        site_2_mapping      INTEGER NOT NULL
);

factors : this table contains factors that can be used to modify rates of reactions which have zero or two reactants, or have duplicate reactants. This table must be filled in by the user.
```
CREATE TABLE factors (
      factor_zero      REAL NOT NULL,
      factor_two       REAL NOT NULL,
      factor_duplicate REAL NOT NULL
);
```

interrupt_state : during checkpointing, the simulation will fill this table with the final state of the simulation. This includes both the species in the lattice and homogeneous region.

site_mapping : szudzik representation of site's i,j,k if on lattice or -2 if in homogeneous region.
edge : 0 or 1 representative of if the site allows adsorption or desorption reactions.

 CREATE TABLE interrupt_state (
        seed                    INTEGER NOT NULL,
        species_id              INTEGER NOT NULL,
        quantity                INTEGER NOT NULL,
        site_mapping            INTEGER NOT NULL,
        edge                    INTEGER NOT NULL
        
);

interrupt_cutoff : During checkpointing, the simulation will fill in this table.

CREATE TABLE interrupt_cutoff (
      seed                    INTEGER NOT NULL,
      step                    INTEGER NOT NULL,
      time                    REAL NOT NULL,
      maxk                    INTEGER NOT NULL
);

Running LGMC

To access the makefile, enter the LGMC folder:

$ cd LGMC

Next create an executable with the makefile. The executable will be located in the build folder.

$ make LGMC

For further help on the makefile and to view other commands:

$ make help

LGMC requires seven input arguments (either step_cutoff or time_cutoff must be specified):

reaction_database : a sqlite database containing the reaction network and metadata.
initial_state_database : a sqlite database containing initial state. The simulation trajectories are also written into the database.
number_of_simulation : an integer specifying how many simulations to run.
base_seed : seeds used are base_seed, base_seed+1, ..., base_seed+number_of_simulations-1.
thread_count : how many threads to use.
step_cutoff : how many steps in each simulation.
time_cutoff : how much time in each simulation [s].
checkpoint : whether checkpointing should occur.
parameters : name of .txt file containing additional parameters
- lattice_constant
- box x upper boundary
- box y upper boundary
- box z upper boundary
- temperature
- Electron free energy
- Is add site (T|F)
- Charge transfer style (M|B)

When running LGMC ensure that your input file paths are correct considering the executable is inside the build folder. Below is an example of how LGMC can be run using the input files inside the examples directory (here step_cutoff is specified):

build/LGMC --lattice_reaction_database=examples/LGMC/CO_oxidation/rn.sqlite --initial_state_database=examples/LGMC/CO_oxidation/initial_state.sqlite --number_of_simulations=1000 --base_seed=1000 --thread_count=8 --step_cutoff=200 --checkpoint=1 --parameters=examples/LGMC/CO_oxidation/LGMC_params.txt

Running this command does not generate any new files or directories but will populate the initial_state_database with trajectory data.