GMC - Gillespie Monte Carlo

Implementation of Gillespie’s next reaction simulator appropriate for applications in a well mixed region. GMC has been used to study solid-electrolyte interphase (SEI) formation in Li-ion batteries.

As a starting point, a simple example of using GMC for homogeneous catalysis is shown in Examples.

Sqlite IO

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

The Reaction Network Database

There are two tables in the 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 and up to two 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 0 and increase in increments of one. If there is only one reactant|product then set the species to -1.
rate : rate of the reaction.

 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,
        rate                REAL 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, GMC 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.
```
CREATE TABLE trajectories (
      seed                INTEGER NOT NULL,
      step                INTEGER NOT NULL,
      reaction_id         INTEGER NOT NULL,
      time                REAL 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.

CREATE TABLE interrupt_state (
      seed                    INTEGER NOT NULL,
      species_id              INTEGER NOT NULL,
      count                   INTEGER NOT NULL
);

interrupt_cutoff : during checkpointing, the simulation will fill in this table. This cutoff table is for simulations with a zero energy budget.

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

interrupt_cutoff : during checkpointing, the simulation will fill in this table. This cutoff table is for simulations with a non-zero energy budget.

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

Running GMC

To access the makefile, enter the GMC folder:

$ cd GMC

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

$ make GMC

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

$ make help

GMC requires six 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].
energy_budget : allowed energy to be added into the system.
checkpoint : whether checkpointing should occur.

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

build/GMC --reaction_database=examples/GMC/end-to-end-test/rn.sqlite --initial_state_database=examples/GMC/end-to-end-test/initial_state_copy.sqlite --number_of_simulations=1000 --base_seed=1000 --thread_count=8 --step_cutoff=200 --energy_budget=0 --checkpoint=1

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