RMG Models & Mechanism Generation

This section will describe from a high level the basic procedure and major functions used by the Reaction Mechanism Generator (RMG) software to create chemistry models.

With many and complex functions composing the RMG software, it is useful to group the functions by their major purpose or the task which they accomplish within the overall model generation scheme. Nick Vandewiele suggested that the tasks required for model generation are (in no particular order)...

1. ODE solving
2. Reaction generation
3. Synchronization
4. Thermodynamic and kinetic evaluation

RMG iteratively increases the size and complexity of the model, completing each of these tasks for each incremental increase in complexity. Also, it is important to understand that the nature of the model core and edge. At a high level the model core components are the species and reactions that are deemed to be important to the model and the edge components are the candidate species and reactions that have not been decided as important enough to include in the core yet.

Bearing these major tasks and iterative nature of RMG in mind, the first function to consider would be execute function found on RMG-Py/rmgpy/rmg/main.py. The execute function is called by RMG-Py/rmg.py (rmg.py is the script put in the command line to initialize mechanism generation) and contains the major loops and tasks for model generation. After initializing and the execute function enters a loop that successively simulates the system (ODE solving), decides important species to add to the core (from the edge), and then updates the model adding new species and reactions to the edge (this includes the major tasks of reaction generation, synchronization, and thermodynamic and kinetic determination). The loop then begins again with this new updated model.

Examining each of these in more detail...

The ODE solving step is accomplished by the reactionsystem.simulate function which is found RMG-Py/rmgpy/solver/base.pxd. Note that this makes use of a DASPK algorithm implemented in fortran with python wrappers.

Next consider the step of adding important species to the core. The importance of a species is determined by its flux, with the highest flux species judged to be the most important. After the simulation is complete the highest flux species (obj in the code) is outputted by the simulate function. If a pdep system is being explored then a separate function getMaximumLeakSpecies is used to determine the highest flux species.

The species determined to be most important are then passed into the enlarge function found in RMG-Py/rmgpy/rmg/model.py. This enlarge function contains all the important tasks of reaction generation, synchronization, species thermodynamic determination and reaction kinetic determination. After these tasks are completed the loop is restarted and the new model is simulated. This process repeats until no species has a flux above a specified thresh-hold and the model is determined to be complete.

Another way to learn about how RMG generates models is to see how different functions are called. Below is shown a timing profile that includes the major functions (by cpu time usage) and how they call each other.

Note that which functions are time intensive varies greatly on the nature of the job. However examining the above image starting at the top gives a sense of the flow of the code in a "typical" job. The execute function calls the simulate and enlarge functions. The different tasks of the enlarge function and their key functions can be seen branching out below it.