RMG Mechanism Generation Algorithm
Note: this is valid after the Accelerator Tools updates
The fundamental problem RMG seeks to solve is the approximate solution of the mass-action kinetics based ODE system containing all possible species and reactions from given conditions. However, in most if not all cases there are an infinite number of possible species and reactions making it absolutely intractable directly.
RMG simplifies this problem by coupling changes in a finite reaction network to the solution of the ODE the network represents. Starting from a given reaction network the ODE system is solved while checking specific criteria until they trigger. Once a criterion triggers either an adjustment is made to the reaction network, ODE solution is started again from t=0 (usually with new already recorded adjustments to the network) or the overall solution process is terminated. The devil of the process lies in the details of what the criteria are and what adjustments are made to the reaction system.
We consider all species and reactions in the current simulated network to be in what we refer to as the “core” of the model. Since there are an infinite number of potential species and reactions beyond the core of the model we only consider those we deem potentially important to the current core, which we refer to as belonging to the “edge” of the model. Potentially important in RMG depends on your input parameters. An edge species must be produced by a reaction between two core species, by turning on pruning and using filtering, however, additional constraints can be put on the edge to reduce its size and reduce memory usage.
There is an additional designation within the core referred to as the “surface”. Species within the core that are not part of the surface can be referred to as being part of the “bulk core”. While the species in the surface are not deemed important enough to be part of the bulk core the surface reactions they participate in are considered structurally important enough that they are needed to properly simulate the concentrations within the bulk core. Since these surface species are not considered important edge reactions brought in by surface species have additional constraints that make it tougher for them to enter the core as described below.
Flux Criterion
This criterion determines what species important because they are produced in large quantities or have high throughput.
We first calculate a characteristic reaction rate by taking the square root of the sum of the squares of the time derivatives of the core species concentrations. This characteristic rate (Rchar) should be a rough representation of how fast the reaction system is progressing toward equilibrium. We then divide all of the edge species production rates and pressure dependent network leak rates by this characteristic rate to get dimensionless rate ratios. If the rate ratio for a given edge species or network leak rate is larger than “toleranceMoveToCore” and “toleranceInterruptSimulation” the ODE solution will terminate and that edge species will be added to the core.
Dynamics Criterion
This criterion determines what reactions need added in order to get model species concentrations correct.
For the reaction A+B<=>C+D we calculate the accumulation number of the reaction:
Ac = (L_A+R)/L_A * (P_A+R)/P_A * (L_B+R)/L_B * (P_B+R)/P_B * (P_C+R)/P_C * (L_C+R)/L_C * (P_D+R)/P_D * (L_D+R)/L_D
Where R denotes the reaction rate, L_i denotes the loss rate of species i and P_i denotes the production rate of species i. The dynamics criterion specifically is Ln(Ac), if this value is greater than a set reaction tolerance (toleranceMoveEdgeReactionToSurface, toleranceMoveEdgeReactionToCore, toleranceMoveSurfaceReactionToCore) the reaction is moved. This criterion also has comparable interrupt tolerances to the flux criterion (toleranceMoveEdgeReactionToCoreInterrupt, toleranceMoveEdgeReactionToSurfaceInterrupt). Movement from surface to core doesn’t affect the simulation so it is unnecessary to interrupt the model when moving species or reactions from the surface to the core.
Surface No Layering Constraint
Any edge reaction entering the surface must have either all products or all reactants in the bulk core.
The purpose of this is to prevent the dynamics criterion from entering a feedback loop where it adds reactions to get core concentrations right and then adds more reactions to get the concentrations of the less important species brought in by those reactions right. By adding this restriction we can use lower dynamic criterion tolerances without entering a feedback loop.
Adding species/reactions
Adding a reaction is equivalent to adding all of the species participating in that reaction that are not already part of the core.
When a species is added to the core:
- All edge reactions whose species are now all in the core are added to the core
- Reactions are generated between the added species and each of the other core species and also specifically for the added species and added to the edge.
a. When two species are reacted all possible reactions are generated b. This can be sped up considerably by setting “filterReactions” to True under model in the input file. This feature causes RMG to only react species pairs once they reach concentrations at which the diffusion limiting rate would be greater than toleranceMoveToCore*Rchar. This feature is in general very robust. When using this feature additional core species may be reacted during species addition. - Any species not currently in the core or edge that participate in edge reactions are added to the edge
Exploring Pdep Networks
A pdep network is “explored” by adding to core the outside species the network has the greatest leak flux to. Then all reactions with the new species as a unimolecular reactant or product and the associated species are added to the edge (subject to filtering and pruning).
Filtering
Since reactions cannot occur faster than their diffusion limit, if filtering is on, before a given new species is reacted with another species a diffusion limiting rate of reaction is calculated and if it is less than toleranceMoveToCore*Rchar the species are not reacted together.
Pruning
Even with filtering on sometimes large RMG runs can take up too much memory. Pruning allows the user to set values for toleranceKeepInEdge, minCoreSizeForPrune, minSpeciesExistIterationsForPrune and maximumEdgeSpecies. If a species has been in the model for less than minSpeciesExistIterationsForPrune it is not eligible to be pruned. If the core size is less than minCoreSizeForPrune the entire model is not eligible for pruning. Otherwise if a given species has a peak formation rate divided by the characteristic flux smaller than toleranceKeepInEdge it will be pruned. However, if maximumEdgeSpecies is exceeded the species with the lowest fluxes (even if they are greater than toleranceKeepInEdge*Rchar) will be removed until the number of species in the edge is the maximumEdgeSpecies value.
Thermodynamic Filtering
The maxGibbsFreeEnergyPerRT property lets you set a maximum Gf/(RT) value, which if a given species is not above for any of the reactors in the run it is removed from the edge after the enlargement step.
maxNumSpecies
When the number of species in the model becomes greater than this value the current model generation stage will be terminated. If it was in the last or the only stage the entire model generation process will be terminated.
maxNumObjsPerIter
The maximum number of objects (species, reactions, PDepNetworks) that can be added to the model or explored as a result of a single simulation. During simulation these objects are accumulated every iteration until maxNumObjsPerIter is reached. If it has been reached then the next time an interrupt tolerance is violated the current simulation will end and the associated objects will be sent for enlargement.
dynamicsTimeScale
The time before which the dynamics criterion cannot be used to bring reactions into the model. This is useful because the math behind the dynamics criterion breaks down as t->0, thus restricting the use of the dynamics criterion until later times may reduce the number of junk species/reactions added to the model.
ignoreOverallFluxCriterion
This Boolean causes RMG to use the given flux criterion only for determining if a PDepNetwork should be explored and not whether species should enter the model. Lets you run pdep alongside the dynamics criterion without the flux criterion.
terminateAtMaxObjects
This Boolean causes RMG simulations to always terminate once they have collected maxNumObjsPerIter objects. If pruning is off this is automatically set to True regardless of the input file since it is always desirable.