Creating a Condition File Manually
To run RMG, you must specify the initial conditions and the model generation
parameters, all of which are contained in a single file, condition.txt.
The file condition.txt can be
located in any directory, although it is advised that you create a special
directory for RMG simulations, since each condition.txt creates its own
subdirectories.
The condition.txt file should specify the following conditions, in
order:
- The main Database
- Any restrictions on the number of atoms / radicals for all generated species
- The name and location of all Primary Thermodynamic Libraries
- The name and location of all Primary Transport Libraries
- Optionally, some additional forbidden structures
- Whether Restart files should be written or read
- The initial temperature and pressure of the system
- Commands for liquid phase systems
- Whether to generate an IUPAC International Chemical Identifier (InChI) for each species
- (Optional) parameters for performing on-the-fly quantum calculations as a substitute for group additivity
- The name, concentration, and chemical structure of the reactants
- The specification and concentration of the inert gas(es)
- The method to use to estimate spectroscopic data for each species
- The Pressure dependence model
- The finish controller
- The dynamic simulator
- Sensitivity analysis settings
- The name and location of all Primary Kinetic Libraries
- The name and location of all Primary Reaction Libraries
- The name and location of all Seed Mechanisms
- The units for the Arrhenius parameters A and Ea (to be reported in the generated chem.inp file)
The name condition.txt is variable. As you’ll see in
Section Running RMG from the Command Line in Linux, you can change the name of the initialization
file, so long as it remains a .txt file.
Database
Field is Required
In the main RMG directory is a directory of databases: $RMG/databases/. By
default, there is one directory within the directory of databases:
$RMG/databases/RMG_database. It is possible, however, to create multiple
databases. For example, you can copy the entire contents of the default database
into a new database, $RMG/databases/my_database, and change some of the
values. Unless you have created your own databases, the Database setting should
be left at the default value:
Species Restrictions
Field is Optional
By default, RMG will allow no more than 30 carbon atoms in any given species (other such default restrictions are:
no more than 10 oxygen atoms, no more than 10 radicals, no more than 100 heavy-atoms, etc.). If you would like to
change the default settings, the syntax is as follows
MaxCarbonNumberPerSpecies: 30
MaxOxygenNumberPerSpecies: 10
MaxRadicalNumberPerSpecies: 10
MaxSulfurNumberPerSpecies: 10
MaxSiliconNumberPerSpecies: 10
MaxHeavyAtomNumberPerSpecies: 100
MaxCycleNumberPerSpecies: 10
Each of these fields is optional, but if present must be in this order;
the default values for all fields are listed above.
A “Heavy Atom” is defined in RMG as a non-hydrogen atom.
If you expect species with fused rings you may want to raise MaxCycleNumberPerSpecies.
Changing the default values of these fields, in particular, lowering the maximum value per species, may help you
if your simulations are running out of memory. Also, changing the default settings of these fields could be
beneficial if you are only concerned with the decomposition of the initial species.
Primary Thermo Library
Field is Required
By default, RMG will calculate the thermodynamic properties of the species from
Benson additivity formulas. In general, the group-additivity results are
suitably accurate. However, if you would like to override the default settings,
you may specify the thermodynamic properties of species in the
primaryThermoLibrary. When a species is specified in the primaryThermoLibrary,
RMG will automatically use those thermodynamic properties instead of generating
them from Benson’s formulas. Multiple libraries may be created, if so desired.
The order in which the primary thermo libraries are specified is important:
If a species appears in multiple primary thermo libraries, the first instance will
be used.
Please see Section Editing the Thermodynamic Database for details on editing the
primary thermo library. In general, it is best to leave the PrimaryThermoLibrary
set to its default value. In particular, the thermodynamic properties for H and H2
must be specified in one of the primary thermo libraries as they cannot be estimated
by Benson’s method.
In addition to the default library, RMG comes with the thermodynamic properties
of the species in the GRI-Mech 3.0 mechanism [GRIMech3.0].
| [GRIMech3.0] | (1, 2) Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel W. Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald K. Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, and Zhiwei Qin http://www.me.berkeley.edu/gri_mech/ |
This library is located in the
$RMG/databases/RMG_database/thermo_libraries directory. All “Locations” for the
PrimaryThermoLibrary field must be with respect to the $RMG/databases/RMG_database/thermo_libraries
directory.:
PrimaryThermoLibrary:
Name: Default
Location: primaryThermoLibrary
Name: GRI-Mech 3.0
Location: GRI-Mech3.0
END
Primary Transport Library
Field is Required
By default, RMG will estiamte the transport properties (Lennard-Jones sigma and epsilon parameters) of a species from
empirical correlations described by Tee et al. [Tee]; these correlations are functions of the acentric factor, the critical
temperature, and the critical pressure. The acentric factor is estimated using the empirical correlation described by Lee
et al. [Lee], which itself is a function of the critical pressure, the critical temperature, and the boiling temperature.
The critical properties and boiling point are estimated using the Joback group-additivity scheme [Joback], [Reid].
| [Tee] | L.S. Tee, S. Gotoh, and W.E. Stewart; “Molecular Parameters for Normal Fluids: The Lennard-Jones 12-6 Potential”; Ind. Eng. Chem., Fundamentals (1966), 5(3), 346-63 Table III: Correlation iii |
| [Lee] | B.I. Lee and M.G. Kesler; “A Generalized Thermodynamic Correlation Based on Three-Parameter Corresponding States”; AIChE J., (1975), 21(3), 510-527 |
| [Reid] | R.C. Reid, J.M. Prausnitz and B.E. Poling; “The Properties of Gases and Liquids” 4th ed. McGraw-Hill, New York, NY, 1987 |
| [Joback] | K.G. Joback; Master’s thesis, Chemical Engineering Department, Massachusetts Institute of Technology, Cambridge, MA, 1984 |
If you would like to override the default settings, you may specify the transport properties of species in the
PrimaryTransportLibrary. Similar to the PrimaryThermoLibrary, RMG will automatically use those transport properties
instead of estimating them using the methods described above. Multiple libraries may be created, if so desired.
The order in which the primary transport libraries are specified is important: If a species appears in multiple primary
transport libraries, the first instance will be used.
RMG comes with the transport properties of the species in the GRI-Mech 3.0 mechanism [GRIMech3.0]. This library is located in the
$RMG/databases/RMG_database/transport_libraries directory. All “Locations” for the
PrimaryTransportLibrary field must be with respect to the $RMG/databases/RMG_database/transport_libraries directory.
PrimaryTransportLibrary:
Name: GRI-Mech 3.0
Location: GRI-Mech3.0
END
Forbidden Structures
Field is Optional
It is possible, though not necessary, to specify additional forbidden structures
in the condition file. This section should appear after the PrimaryTransportLibrary section.
Each adjacency list can be a species, as described in the Reactants section, but can
contain wildcards as described in the Thermo Database and Adjacency List Notation section.
For example:
ForbiddenStructures:
AdjacentBiradicalCs
1 C 1 {2,S}
2 C 1 {1,S}
AdjacentBiradicalCd
1 C 1 {2,D}
2 C 1 {1,D}
END
Note that each adjacency list must be followed by an empty line, and that the section
must end (after an empty line) with the word END.
Restart Files
Field is Required
The next two items pertain to the reading and writing of “Restart” files.
For the baseball fans out there: Imagine a baseball game is in the top of the 5th inning, but the game is
suspended (and later cancelled) due to bad weather. In baseball, the game would need to be
re-played, starting from the first inning (unless it’s the World Series, and then play will
resume where it left off on the following day). RMG’s Restart files fall under the latter
condition: Imagine you have a terminated RMG simulation, and would like to pick up where you
left off. Instead of having to re-run every aspect of the previous mechanism, you can supply RMG
with the Restart files and RMG can more quickly restore the desired mechanism conditions.
The Restart files contain
information regarding all species and reaction in the mechanism and are written after every
successful ODE time step. These files are written in the Restart folder within the working
directory. The files are:
coreSpecies.txt: The name and connectivity of every species present in the model's core
coreReaction.txt: The structure, kinetics, and comments for every high-P limit reaction present in the model's core
edgeSpecies.txt: The name and connectivity of every species present in the model's edge
edgeReaction.txt: The structure, kinetics, and comments for every high-P limit reaction present in the model's edge
pdepreactions.txt: The structure, high-P limit kinetics, fall-off parameters, and comments for every pressure-dependent reaction in the model that was specified by the user in a Reaction Library or Seed Mechanism
pdepnetworks.txt: The structure, high-P limit kinetics, pressure-dependent kinetics, and comments for every pressure-dependent reaction in the model that was generated by RMG
These files may be used for a variety of reasons, including:
Having more detailed information on the model's edge species and reactions
As a Seed Mechanism, in constructing reaction mechanisms valid at multiple equivalence ratios
As "Restart" files, in hopes of restoring the conditions of a terminated simulation
To write the files
ReadRestart: no
WriteRestart: yes
To read the files (Note: the Restart folder must be present in the working directory):
ReadRestart: yes
WriteRestart: no
Initial Conditions
Field is Required
The next item in the initialization file is the initial temperature and
pressure. Currently, RMG can only model constant temperature and pressure systems.
Future versions will allow for variable temperature and pressure. Please note
that the temperature and pressure must be accompanied by a unit (in
parentheses). Suitable temperature units are: K, F, and C. Suitable pressure
units are: atm, torr, pa, and bar. The following example assumes that the system
begins at 600 Kelvin and 200 atmospheres:
TemperatureModel: Constant (K) 600
PressureModel: Constant (atm) 200
You may also list multiple temperature and pressure conditions, as the example below shows:
TemperatureModel: Constant (K) 600 700 800 900
PressureModel: Constant (atm) 1 200
The intervals between the supplied values do not have to be equal, i.e. the following is an equally valid
TemperatureModel field:
TemperatureModel: Constant (K) 600 700 900 1500
For cases in which multiple temperatures and pressures are listed, the model generator will simulate the system (still using an isothermal, isobaric model) at all possible combinations of the specified temperatures and pressures. Thus, the resulting reaction mechanism will be valid (within the given error tolerances, estimates, and various other assumptions) at all the conditions specified. (Note, however, that reported concentrations in the Final_Model.txt output file will only correspond to the first T/P combination.)
InChI Generation
Field is Optional
The next item in the initialization file is the InChI generation command.
To use it you will need to install the InChI software.
An InChI, or IUPAC International Chemical Identifier, is an unique
species identifier, with the exception of differing electronic or spin states,
developed by IUPAC and NIST. An example of an InChI string (which represents the species
caffeine) is:
InChI=1/C8H10N4O2/c1-10-4-9-6-5(10)7(13)12(3)8(14)11(6)2/h4H,1-3H3
The InChI is composed of layers, separated by a forward-slash (/):
- Chemical formula layer
- Connectivity layer
- Hydrogen layer
- ...
For the current release, the InChIs are used as another way to represent a
molecule. In future releases, the InChIs will link RMG with an online thermochemical
database: PrIMe, or Process Informatics Model. The union will
allow RMG to search for a community-recommended thermochemical data entry (e.g.
Arrhenius parameters, NASA polynomials) before using estimation techniques.
If this field is turned on, the InChI for each species in the model is located in the RMG_Dictionary.txt file.
More information on the InChI project may be found at http://www.iupac.org/inchi/. More information on the PrIMe project may be found at http://primekinetics.org/
To enable the InChI generation, the item should read:
To disable the InChI generation, the item should read:
On-the-fly Quantum Calculations
Field is Optional
The next section is optional and specifies parameters for on-the-fly quantum mechanics (QM) calculations for estimating thermodynamic parameters.
If the user does not have the needed dependencies or wishes to use the
group additivity approach for estimation of all unknown thermodynamic parameters, this section should be omitted.
The first line in this block should be something like
ThermoMethod: QM gaussian03
The second field in the first line is optional and specifies the QM program to use. Options
include “mopac”, “gaussian03”, or “both” (the default if this field is omitted).
The “both” option requests that RMG first try to use MOPAC and if all MOPAC attempts
for a particular species are unsuccessful, then it will try Gaussian03. In all three cases, these will use PM3 calculations. Two experimental options
are “mm4” and “mm4hr”, and require the MM4 force field program; the former uses mm4 with the rigid-rotor, harmonic oscillator
(RRHO) approximation, while the latter does rotor scans to treat rotor modes. It has been found that this approach generally works reasonably well, but
currently fails to give accurate results for cyclic C3 species and may be less robust than the PM3 options.
The next line determines whether RMG will use QM calculations for all species or just cyclic ones:
It is often desireable to run with this option on, as the QM calculations can be time-consuming
and may be less accurate than group-additivity for acyclic species, whereas they are more likely to improve accuracy for cyclic species.
The user must next specify the maximum radical number for species that will be fed to the QM program:
For molecules with more radicals than the value specified here, QM calculations
will be performed on the saturated molecule (with added hydrogens) and hydrogen bond increment (HBI)
corrections will be applied, similar to the approach used with group additivity. It is recommended that
this value be left at 0 (zero), as it has been found that radicals tend to be difficult for the PM3
implementations to handle robustly, and errors or significant inaccuracies (particularly for biradicals)
are more likely.
Next, the user must specify whether (and how) connectivity-checking functionality should be use:
ConnectivityChecking: confirm
Options include “off”, “check”, and “confirm”. The “off” option disables this functionality.
The “check” option will perform a check on the final optimized geometry to try to assess whether it corresponds
to a molecular structure with the desired connectivity; if not, a warning is printed, alerting the user. The “confirm”
option will perform the same checks, except in cases where there is an apparent mismatch, the job will be treated
as a failure and calculation with different geometry/keywords will be attempted.
Finally, you can choose whether or not to save the QM calculation input and output files.
The benefits of saving them are that if another job encounters the same species it can re-use the result,
if you have set them up to share the same RMG_QM_CALCS directory, and you can check the outputs if debugging.
However, they can just take a lot of disk space, so if you’d rather not save them, then set it to ‘no’:
Reactants
Field is Required
The name, concentration, and structure of each reactant must be specified. For
each reactant, the first line should include the reactant’s
name (e.g. C2O2) and it’s concentration(s) preceded by units (e.g. (mol/cm3) 4.09e-3).
Acceptable units for concentration are “mol/cm3”, “mol/m3”, and “mol/l”. Please note,
RMG will not accept a species name that begins with a number.
Be warned that names longer than about 6 characters will be replaced with “SPC(#)”
in the Chemkin file due to the maximum length of a reaction string in Chemkin,
so keep your names short!
Like with the initial conditions, it is possible to set multiple starting
concentrations, separated by spaces. RMG will create reaction systems for each
combination of temperature, pressure, and starting concentration. You must
enter the same number of starting concentrations for each species, including
the Inert Gases described in the next section.
The next line defines the reactant structure, described by an adjacency list.
The RMG Viewer and Editor is a useful tool for
generating adjacency lists. Please note that you may choose the simplified
adjacency list in which the hydrogen atoms are omitted (shown below):
InitialStatus:
CH3OH (mol/cm3) 4.09e-3
1 C 0 {2,S}
2 O 0 {1,S}
O2 (mol/cm3) 1.1E-7
1 O 1 {2,S}
2 O 1 {1,S}
END
Please note that the keyword END must be placed at the end of the
InitialStatus section.
If one of the reactants is a resonance isomer, you only need to define one of
the resonance structures, and RMG will automatically detect the others.
Represent molecular oxygen, O2, as shown above. This is a deviation
from versions of the RMG database prior to RMG 3.2. For more detail, please see this discussion on
representing oxygen.
Maintaining a species at constant concentration
Adding the text ConstantConcentration after a species’s initial
concentration(s) in the condition file ensures that the concentration of the
species remains unchanged during the simulation. This can be used for
generating kinetic models in liquid phase experiments where gases (e.g.
oxygen) are bubbled through the substrate at constant pressure, so that any
consumption due to reactions is replenished externally:
O2 (mol/cm3) 4.09e-3 ConstantConcentration
1 O 1 {2,S}
2 O 1 {1,S}
Inert Gases
Field is Required
Following InitialStatus, the initialization file specifies which inert gases, if
any, are used. Currently RMG can handle four inert gases: N2, Ne, He, and Ar. If
one of the gases is not used, set the concentration to (mol/cm3) 0.0. If no bath
gas is used, set all concentrations to zero. In the example below, there is no
nitrogen, the neon and helium are omitted, and the argon concentration is 2.21E-6 (mol/cm3):
InertGas:
N2 (mol/cm3) 0.0
Ar (mol/cm3) 2.21E-6
END
In this case, the only difference between N2 and Ne (or He) is that N2 will be
written to the SPECIES section of the chem.inp file, whereas Ne (or He)
will be excluded.
To create valid CHEMKIN files, ensure that any 3rd-body collider molecules used in
your Seed Mechanisms or Reaction Libraries are either declared in their
species.txt files (if they are reactive) or in this section.
(i.e. it’s a good idea to list all of N2, Ne, He and Ar, even if their concentrations are 0)
The number of concentrations must correspond to the number of concentrations
specified in the preceding Reactants section.
Please note that the keyword END must be placed at the end of the InertGas
section.
Spectroscopic Data
Field is Required
The next item in the initialization file is the method to use to estimate the
spectroscopic data (i.e. rovibrational modes) of each species. At present
there is only one method available, which utilizes approximate frequencies
based on functional groups in the molecule when possible, then fits remaining
degrees of freedom to heat capacity data. This can also be set to off if
spectroscopic data is not needed (i.e. when pressure dependence is off).
When pressure dependent calculations are not desired, this item should read:
SpectroscopicDataEstimator: off
When pressure dependent calculations are desired, this item should read:
SpectroscopicDataEstimator: FrequencyGroups
Pressure Dependence
Field is Required
This flag is used to specify whether the model should account for pressure
dependent rate coefficients. If pressure dependence is not desired, this item
should read:
If pressure dependence is desired, this item can take one of two values, based
on the method used to approximate the pressure-dependent kinetics: ModifiedStrongCollision and ReservoirState. The former utilizes
the modified strong collision approach of Chang, Bozzelli, and Dean [Chang2000],
and works reasonably well while running more rapidly. The latter
utilizes the steady-state/reservoir-state approach of Green and Bhatti [Green2007],
and is more theoretically sound but more expensive.
To specify the modified strong collision approach, this item should read:
PressureDependence: ModifiedStrongCollision
To specify the reservoir state approach, this item should read:
PressureDependence: ReservoirState
For more information on the two methods, consult the following resources:
| [Chang2000] | A.Y. Chang, J.W. Bozzelli, and A. M. Dean. “Kinetic Analysis of Complex Chemical Activation and Unimolecular Dissociation Reactions using QRRK Theory and the Modified Strong Collision Approximation.” Z. Phys. Chem. 214 (11), p. 1533-1568 (2000). |
| [Green2007] | N.J.B. Green and Z.A. Bhatti. “Steady-State Master Equation Methods.” Phys. Chem. Chem. Phys. 9, p. 4275-4290 (2007). |
When pressure dependence is on, you must also specify a linear interpolation model to use to evaluate k(T, P) and output to the Chemkin file. (This line is not required if pressure dependence is set to
off.) This line must immediately follow the previous one.
By default pressure dependence is run for every system that might show pressure
dependence, i.e. every isomerization, dissociation, and association reaction.
In reality, larger molecules are less likely to exhibit pressure-dependent
behavior than smaller molecules due to the presence of more modes for
randomization of the internal energy. In certain cases involving very large
molecules, it makes sense to only consider pressure dependence for molecules
smaller than some user-defined number of atoms. This is specified e.g. using
the line
MaxAtomsForPressureDependence: 20
to turn off pressure dependence for all molecules larger than the given number
of atoms (20 in the above example). If this option is present, it must be
given directly before the PDepKineticsModel option discussed below.
To disregard all temperature and pressure dependence and simply output the rate at the provided
temperature and pressure, use the line
To use logarithmic interpolation of pressure and Arrhenius interpolation for temperature, use the
line
PDepKineticsModel: PDepArrhenius
The auxillary information printed to the Chemkin chem.inp file will have the “PLOG”
format. Refer to Section 3.5.3 of the CHEMKIN_Input.pdf document and/or
Section 3.6.3 of the CHEMKIN_Theory.pdf document. These files are part of
the CHEMKIN manual.
To fit a set of Chebyshev polynomials on inverse temperature and logarithmic pressure axes mapped
to [-1,1], use the line
PDepKineticsModel: Chebyshev
You should also specify the number of temperature and pressure basis functions by adding the appropriate integers. For example, the following specifies that five basis functions in temperature and four in pressure should be used
PDepKineticsModel: Chebyshev 5 4
The auxillary information printed to the Chemkin chem.inp file will have the “CHEB”
format. Refer to Section 3.5.3 of the CHEMKIN_Input.pdf document and/or
Section 3.6.4 of the CHEMKIN_Theory.pdf document.
To generate the k(T,P) interpolation model, a set of temperatures and pressures must be used. RMG can do this automatically, but it must be told a few parameters. Following the previous line, you should provide a line to specify the minimum and maximum temperature and number of temperatures to use in the grid, e.g.
TRange: (K) 300.0 2000.0 8
A similar line should follow for pressures:
PRange: (bar) 0.01 100.0 5
If you prefer, you can also specify the grid of temperatures and pressures manually using lines similar to the following:
Temperatures: 8 (K) 300.0 400.0 500.0 600.0 800.0 1000.0 1500.0 2000.0
Pressures: 5 (bar) 0.01 0.1 1.0 10.0 100.0
You should specify either a TRange or Temperatures line and either a PRange or Pressures line.
Note
If requesting “Chebyshev” polynomials in the “PDepKineticsModel” field, please consider the temperature(s) and
pressure(s) that will be simulated in CHEMKIN (or similar). For example, if one were modeling a shock tube
experiment, the largest temperature specified in the “Temperatures” or “TRange” field should probably be
greater than 2000 K, as the simulated temperature will likely exceed this value. In the developers’ experience,
CHEMKIN will terminate a simulation when the simulated temperature exceeds the largest allowed temperature for
the Chebyshev polynomials (the values of all system variables will be returned as “NaN”).
Lastly, you also need to specify information regarding the number of energy grains to use
when solving the Master Equation. The default value is 250; this was selected to balance the speed
and accuracy of the Master Equation solver method. However, for some pressure-dependent networks,
this number of energy grains will result in the pressure-dependent k(T, P) being greater than
the high-P limit. The default option in RMG is to print a warning message in the output file, stating
this phenomenom, and then to continue the simulation. If you would prefer RMG to increase the
number of energy grains and resolve the Master Equation, add the following line
If this field is turned on, RMG will increase the number of energy grains for the given pressure-dependent
network until the computed k(T, P) is less than the high-P limit or until the number
of energy grains exceeds 1000. Please note, the runtime of a RMG simulation with this field turned
on will be longer than one with this field turned off. Furthermore, not specifying this field in the
input file is the same as
Finish Controller
Field is Required
The Finish Controller defines the termination rules for model growth.
Additionally, it includes the precision parameters such as reaction time,
conversion, and error tolerance. The finish controller item should begin
with a line that contains only FinishController:.
Below the Finish Controller line, you must specify the goal. The goal tells the
program when to terminate the reaction model expansion. There are two goal
options: ReactionTime and Conversion. ReactionTime must be followed
by a number and a time unit. Acceptable units of time are “sec”, “min”, “hr”,
and “day”. Conversion must be followed by a reactant
species name and a number between 0 and 1.
Beneath the goal, you must specify the error tolerance. Typical values for the
error tolerance are between 0.0001 and 0.5. A smaller error tolerance generally
corresponds to a larger model and longer model generation times. In the first example, the simulation will run for 0.001 seconds:
FinishController:
(1) Goal ReactionTime: 0.001 (sec)
(2) Error Tolerance: 0.1
In the second example, the simulation will run until 90% of the C2H6 reactant is
consumed and has a much tighter error tolerance:
FinishController:
(1) Goal Conversion: C2H6 0.90
(2) Error Tolerance: 0.0001
For the initial model run, it is often preferable to use Goal Conversion
instead of Goal ReactionTime, since it is difficult to judge a priori
what the reaction time should be.
For a more detailed description on rate-based model enlargement, please consult
[Susnow1997].
Dynamic Simulator
Field is Required
RMG uses the DASSL or DASPK dynamic solver. DASSL is recommended, as RMG uses
DASPK in a way that requires the use of the proprietary DAEPACK library, which
is not distributed with RMG (see installation instructions for details).
The first line beneath the solver should be either TimeStep or Conversions, depending on whether you chose Goal Conversion or Goal ReactionTime as your finish controller criterion.
The TimeStep indicates at what time steps RMG should check to see if the model needs to be enlarged. By default the units of time steps is always seconds. For example in the example shown below RMG will stop at 0.0001 sec, 0.0002 sec ... and so on to see whether the error tolerance is satisfied:
DynamicSimulator: DASSL
TimeStep: 0.0001 0.0002 0.0004 0.0006 0.0008 0.0009
The other option is to specify the Conversions. In this option the conversion of the FinishController species (in this case, C2H6) is monitored and RMG will stop at conversions of 0.1, 0.2, ... and so on to see whether the error tolerance is satisfied:
DynamicSimulator: DASSL
Conversions: 0.1 0.2 0.4 0.6 0.8 0.9
For both TimeStep or Conversions, in addition to determining when RMG will stop to check whether error tolerances are satisfied, the concentrations and flux at the points specified will be reported in the Final_Model.txt file.
Note that if conversion or time steps are specified this way, RMG only checks
for model validity at those points and not in between. It is therefore
advisable to use the automatic stepping option described next.
If you would not like to specify time steps or conversions, you may have them determined using the “automated time stepping” feature by specifying AUTO as follows:
DynamicSimulator: DASSL
TimeStep: AUTO
or:
DynamicSimulator: DASSL
Conversions: AUTO
The automated time stepping feature is described in greater detail in the Theory and Implementation Details appendix.
Pruning
When using automated time stepping, it is also possible to perform mechanism generation with pruning of “unimportant” edge species to reduce memory usage. This option is requested by specifying AUTOPRUNE in place of AUTO. When using AUTOPRUNE, this must be followed by four lines specifying pruning parameters, as the example below shows:
DynamicSimulator: DASSL
TimeStep: AUTOPRUNE
TerminationTolerance: 1.0E4
PruningTolerance: 1.0E-15
MinSpeciesForPruning: 1000
MaxEdgeSpeciesAfterPruning: 1000
TerminationTolerance and PruningTolerance are compared with the same quantity as Error Tolerance in the FinishController section (i.e. they are all compared with ratios of edge species flux to characteristic reaction model flux).
TerminationTolerance indicates how high the edge flux ratio must get to interrupt the simulation (before reaching the Goal Conversion or Goal ReactionTime described earlier). Pruning won’t occur if the simulation is interrupted before reaching the goal criteria, so set this high to increase pruning opportunities. The value should be greater than or equal to Error Tolerance.
PruningTolerance indicates how low the edge flux ratio for a species must get before the species is pruned (removed) from the edge (regardless of edge size relative to MaxEdgeSpeciesAfterPruning). The value should be (significantly) lower than Error Tolerance.
MinSpeciesForPruning indicates the minimum total number of species (edge and core) that must be present for pruning (due to low edge flux ratio relative to PruningTolerance or due to MaxEdgeSpeciesAfterPruning) to occur.
MaxEdgeSpeciesAfterPruning indicates the upper limit for the size of the edge. Pruning will continue until the edge is at least this small, regardless of PruningTolerance (though lowest fluxes are pruned first).
When using pruning, RMG will not prune unless all reaction systems reach the goal reaction time or conversion without first exceeding the termination tolerance. Therefore, you may find that RMG is not pruning even though the model edge size exceeds MaxEdgeSpeciesAfterPruning. In order to increase the likelihood of pruning in such cases, you can try increasing TerminationTolerance to an arbitrarily high value. Alternatively, if you are using a conversion goal, because reaction systems may reach equilibrium below the goal conversion, it may be helpful to reduce the goal conversion or switch to a goal reaction time.
Simulator Tolerances
Fields are Required
The next two lines specify the absolute and relative tolerance for the ODE solver, respectively. Common values for the absolute tolerance are 1e-15 to 1e-25. Relative tolerance
is usually 1e-4 to 1e-8:
Note: You have the option of using sensitivity analysis only if you have the
DASPK solver and the DAEPACK library. If you are using DASSL solver then skip the Sensitivity Analysis section.
One option when dealing with NegativeConcentrationException issues is to use the “non-negative” option with DASSL. This option is requested with the line DynamicSimulator: DASSL: non-negative. See the FAQ for further details.
Sensitivity Analysis
Field is Optional
If DASPK is chosen for the dynamic solver, RMG can perform sensitivity
analysis and generate error bars on the concentration profiles. As mentioned above,
however, RMG uses DASPK in a way that requires the use of the proprietary library
DAEPACK which provides automatic differentiation capabilities for the sensitivity analysis (see installation instructions for details).
If you do not have access to this library, an alternative is to perform sensitivity analysis
in CHEMKIN, using the ‘’chem.inp’’ file produced by RMG.
The sensitivity analysis is based upon first-order sensitivity coefficients and uncertainties in
the rate constants. To use the sensitivity analysis, either the first or
second line must be set to on. If both Error bars and Display
sensitivity coefficients are set to off, then RMG will not perform a
sensitivity analysis.
When the option to generate error bars is turned on, RMG calculates the upper
and lower bounds on the concentration profiles for all core species. These upper
and lower bounds are generated by the first-order sensitivity equation:
\ln C_i \left( t,\overrightarrow{k} + \Delta \overrightarrow{k} \right) \approx \ln C_i \left( t,\overrightarrow{k} \right) + \sum_j \frac{\partial \ln C_i}{\partial \ln k_j} \Delta \ln k_j
where C_i is the concentration of the i^{th} species, and \overrightarrow{k} is
the vector of rate constants.
If the option to display sensitivity coefficients is turned on, you must specify
a list of species for which the sensitivities should be displayed. The output
file will then include the sensitivities of those species with respect to all
the rate constants, all the heats of formations, and the initial concentrations
of all the reactants. Additionally, if you choose to display the sensitivity
coefficients, RMG will print a list of the five reactions that contribute the
most to the uncertainty in the concentration (for each species selected by the
user).
Sensitivities to rate constants are normalized sensitivities (\partial \ln C_i/ \partial \ln k_j), and
sensitivities to heats of formation are semi-normalized (\partial \ln C_i/ \partial \Delta H_f). The
contribution of a reaction to the uncertainty is estimated as the product of the
normalized sensitivity and the uncertainty in the rate constant (\Delta \ln k). In the
following example, RMG will perform a sensitivity analysis. Error bars will be
generated for all the species, and the sensitivity coefficients will be
generated for carbon monoxide, carbon dioxide, methane, and water:
Error bars: On
Display sensitivity coefficients: On
Display sensitivity information for:
CO
CO2
CH4
H2O
END
Please note that the keyword END must be placed at the end of the Error
bars section.
Primary Kinetic Library
Field is Required but can be empty.
The next section of the condition.txt file specifies which, if any, primary
kinetic libraries should be used. When a reaction is specified in a primary kinetic
library, RMG will use these kinetics instead of the kinetics located in the
RMG_database/kinetics_groups/<RxnFamily>/rateLibrary.txt directory.
For details of the kinetics libraries included with RMG that can be used as a primary kinetic library,
see Kinetics Libraries.
You can specify your own
primary kinetic library in the location section. In the following example, the
user has created her own primary kinetic library with a few additional reactions
specific to n-butane, and these reactions are to be used in addition to the
Leeds’ oxidation library:
PrimaryKineticLibrary:
Name: nbutane
Location: nbutane
Name: Leeds
Location: combustion_core/version5
END
If a user wished to use the GRI-Mech 3.0 mechanism as a primary kinetic library,
the syntax is:
Name: GRI-Mech 3.0
Location: GRI-Mech3.0
The libraries are stored in $RMG/databases/RMG_database/kinetics_libraries/
and the Location: should be specified relative to this path.
Please note that the keyword END must be placed at the end of the Primary
Kinetic Library section. Because the units for the Arrhenius parameters are
given in each library, the different libraries can have different units.
If the same reaction occurs more than once in a single Primary Kinetics Library,
all instances will be recognized by RMG and will be reported as DUPLICATES in the
chem.inp file.
If the same reaction occurs more than once in the combined
library, the instance of it from the first library in which it appears is
the one that gets used.
Changed in version 3.2: In previous versions this feature was called “PrimaryReactionLibrary” it has been
renamed to “PrimaryKineticLibrary” to better represent its functionality.
Primary Reaction Library
Field is Required but can be empty.
The next section of the condition.txt file specifies which, if any,
Reaction Libraries should be used. When a reaction library is specified, RMG will first
use the reaction library to generate all the relevant reactions for the species
in the core before going through the reaction templates. This feature can be used as a
Primary Kinetic Library, in addition to specifying reactions that the user
wants to consider while building the mechanism but that do not otherwise match any of RMG reaction family templates.
Unlike the Seed Mechanism, reactions present in a Reaction Library will not be included
in the core automatically from the start.
For details of the kinetics libraries included with RMG that can be used as a reaction library,
see Kinetics Libraries.
You can specify your own
reaction library in the location section. In the following example, the user has created
a reaction library with a few additional reactions specific to n-butane, and these reactions
are to be used in addition to the Glarborg C3 library:
ReactionLibrary:
Name: nbutane
Location: nbutane
Name: Glarborg
Location: Glarborg/C3
END
The reaction libraries are stored in $RMG/databases/RMG_database/kinetics_libraries/
and the Location: should be specified relative to this path.
Please note that the keyword END must be placed at the end of the Reaction Library
section. Because the units for the Arrhenius parameters are
given in each mechanism, the different mechanisms can have different units.
Note
While using a Reaction Library the user must be careful enough to provide
all instances of a particular reaction in the library file, as RMG will
ignore all reactions generated by its templates. For example, suppose you supply the
Reaction Library with butyl_1 –> butyl_2. Although RMG would find two unique
instances of this reaction (via a three- and four-member cyclic Transition State),
RMG would only use the rate coefficient supplied by you in generating the mechanism.
RMG will not handle irreversible reactions correctly, if supplied in a Reaction
Library, see RMG “Primary Kinetic Libraries” and “Reaction Libraries” do not handle irreversible reactions properly.
Seed Mechanisms
Field is: Required but can be empty.
The next section of the condition.txt file specifies which, if any,
Seed Mechanisms should be used. If a seed mechanism is passed to RMG, every
species and reaction present in the mechanism will be placed into the core, in
addition to the species that are listed in the Reactants section.
For details of the kinetics libraries included with RMG that can be used as a seed mechanism,
see Kinetics Libraries.
You can specify your own
seed mechanism in the location section. Please note that the oxidation
library should not be used for pyrolysis models. The syntax for the seed mechanisms
is similar to that of the primary reaction libraries, except for the GenerateReactions
line, explained below.:
SeedMechanism:
Name: GRI-Mech 3.0
Location: GRI-Mech3.0
GenerateReactions: yes
Name: Leeds
Location: combustion_core/version5
GenerateReactions: yes
END
The seed mechanisms are stored in $RMG/databases/RMG_database/kinetics_libraries/
and the Location: should be specified relative to this path.
There is a new required GenerateReactions line in seed mechanisms that controls how RMG adds the
seed species and reactions to the model core. If set to yes, RMG will use its
reaction families to react all seed species with one another; the generated
reactions will supplement the seed reactions. If set to no, RMG will not
generate reactions of the seed species. In either case, RMG will react the
species in the condition file with one another and with all species in the
seed mechanism.
Please note that the keyword END must be placed at the end of the Seed
Mechanism section. Because the units for the Arrhenius parameters are
given in each mechanism, the different mechanisms can have different units.
Additionally, if the same reaction occurs more than once in the combined
mechanism, the instance of it from the first mechanism in which it appears is
the one that gets used.
Chemkin Units
Field is Required
The last section of the condition.txt file specifies the units for the
Arrhenius A and Ea parameters reported in the chem.inp file. The acceptable
units for A are “moles” and “molecules”; the acceptable units for Ea are “kcal/mol”,
“cal/mol”, “kJ/mol”, “J/mol”, and “Kelvins”:
ChemkinUnits:
A: moles
Ea: kcal/mol
Another option available to the user is to specify whether the comments following
each set of Arrhenius parameters in the chem.inp file are concise or verbose.
The verbose comments describe how the reported A, n, and Ea Arrhenius parameters were
calculated in the event RMG could not find an exact match for the functional groups.:
ChemkinUnits:
Verbose: on
A: moles
Ea: kcal/mol
If the Verbose field is not present, RMG will default to “off”.
Note
The chem.inp file generated with the Verbose field turned “on” may have
a comment that spans hundreds of characters. These verbose comments may cause
the CHEMKIN interpreter to throw an error when running the Pre-Processor.
