.. _conditionfile: ********************************** 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, :file:`condition.txt`. The file :file:`condition.txt` can be located in any directory, although it is advised that you create a special directory for RMG simulations, since each :file:`condition.txt` creates its own subdirectories. The :file:`condition.txt` file should specify the following conditions, in order: #. The main :ref:`database` #. Any :ref:`restrictions ` on the number of atoms / radicals for all generated species #. The name and location of all :ref:`Primary Thermodynamic Libraries ` #. The name and location of all :ref:`Primary Transport Libraries ` #. Optionally, some additional :ref:`forbidden structures ` #. Whether :ref:`Restart ` files should be written or read #. The :ref:`initial temperature and pressure ` of the system #. Commands for :ref:`liquid phase ` systems #. Whether to generate an :ref:`IUPAC International Chemical Identifier (InChI) ` for each species #. (Optional) parameters for performing on-the-fly :ref:`quantum calculations ` as a substitute for group additivity #. The name, concentration, and chemical structure of the :ref:`reactants ` #. The specification and concentration of the :ref:`inert gas(es) ` #. The method to use to estimate :ref:`spectroscopic data ` for each species #. The :ref:`Pressure dependence ` model #. The :ref:`finish controller ` #. The :ref:`dynamic simulator ` #. :ref:`Sensitivity analysis ` settings #. The name and location of all :ref:`Primary Kinetic Libraries ` #. The name and location of all :ref:`Primary Reaction Libraries ` #. The name and location of all :ref:`Seed Mechanisms ` #. The :ref:`units ` for the Arrhenius parameters A and Ea (to be reported in the generated chem.inp file) The name :file:`condition.txt` is variable. As you'll see in Section :ref:`runninginlinux`, you can change the name of the initialization file, so long as it remains a :file:`.txt` file. .. _database: Database -------- Field is **Required** In the main RMG directory is a directory of databases: :file:`$RMG/databases/`. By default, there is one directory within the directory of databases: :file:`$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, :file:`$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:: Database: RMG_database .. _speciesRestrictions: 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. .. _primarythermolibrary: 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 :ref:`editingthermodatabase` 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] 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 :file:`$RMG/databases/RMG_database/thermo_libraries` directory. All "Locations" for the PrimaryThermoLibrary field must be with respect to the :file:`$RMG/databases/RMG_database/thermo_libraries` directory.:: PrimaryThermoLibrary: Name: Default Location: primaryThermoLibrary Name: GRI-Mech 3.0 Location: GRI-Mech3.0 END .. _primarytransportlibrary: 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 :file:`$RMG/databases/RMG_database/transport_libraries` directory. All "Locations" for the PrimaryTransportLibrary field must be with respect to the :file:`$RMG/databases/RMG_database/transport_libraries` directory. :: PrimaryTransportLibrary: Name: GRI-Mech 3.0 Location: GRI-Mech3.0 END .. _forbiddenstructures: 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 :ref:`reactants` section, but can contain :ref:`wildcards ` as described in the :ref:`adjacencylistnotation` 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: 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 :file:`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 :file:`Restart` folder must be present in the working directory):: ReadRestart: yes WriteRestart: no .. _initialconditions: 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 :file:`Final_Model.txt` output file will only correspond to the first T/P combination.) .. _InChIgeneration: InChI Generation ---------------- Field is **Optional** The next item in the initialization file is the InChI generation command. To use it you will need to :ref:`install the InChI software `. An InChI, or IUPAC **In**\ ternational **Ch**\ emical **I**\ dentifier, 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 **Pr**\ ocess **I**\ nformatics **M**\od\ **e**\ l. 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 :file:`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:: InChIGeneration: on To disable the InChI generation, the item should read:: InChIGeneration: off .. _qm: 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 :ref:`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:: QMForCyclicsOnly: on 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:: MaxRadNumForQM: 0 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':: KeepQMFiles: no .. _reactants: 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 :ref:`inertgas` described in the next section. The next line defines the reactant structure, described by an adjacency list. The :ref:`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 :ref:`representing oxygen `. .. |O2| replace:: O\ :sub:`2`\ 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} .. we should also document the 'unreactive' flag, but I'm not sure what it does. .. this is commented out because it breaks the latex +------------------+----------+---------------------+ | | Notation | Explanation | +==================+==========+=====================+ | Chemical Element | C | Carbon atom | | +----------+---------------------+ | | O | Oxygen atom | | +----------+---------------------+ | | H | Hydrogen atom | +------------------+----------+---------------------+ | Free Electrons | 0 | Non-radical | | +----------+---------------------+ | | 1 | Mono-radical | | +----------+---------------------+ | | 2 | Bi-radical | | +----------+---------------------+ | | 2T | Triplet | | +----------+---------------------+ | | 2S | Singlet | | +----------+---------------------+ | | 3 | Tri-radical | +------------------+----------+---------------------+ | Chemical Bond | S | Single Bond | | +----------+---------------------+ | | D | Double Bond | | +----------+---------------------+ | | Dcis | Cis-double bond | | +----------+---------------------+ | | Dtrans | Trans-double bond | | +----------+---------------------+ | | T | Triple bond | | +----------+---------------------+ | | B | Benzene bond | +------------------+----------+---------------------+ .. _inertgas: 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 .. |N2| replace:: N\ :sub:`2`\ In this case, the only difference between N2 and Ne (or He) is that N2 will be written to the SPECIES section of the :file:`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 :ref:`reactants` section. Please note that the keyword ``END`` must be placed at the end of the InertGas section. .. _spectroscopicdata: 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 .. _pressuredependence: 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:: PressureDependence: off 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 :math:`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 :: PDepKineticsModel: Rate 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 :file:`CHEMKIN_Input.pdf` document and/or Section 3.6.3 of the :file:`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 :file:`CHEMKIN_Input.pdf` document and/or Section 3.6.4 of the :file:`CHEMKIN_Theory.pdf` document. To generate the :math:`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"). .. _numberofgrains: 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 :math:`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 :: DecreaseGrainSize: yes If this field is turned on, RMG will increase the number of energy grains for the given pressure-dependent network until the computed :math:`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 :: DecreaseGrainSize: no .. _finishcontroller: 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 C\ :sub:`2`\ H\ :sub:`6` 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]_. .. _dynamicsimulator: 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 :ref:`installation instructions ` for details). .. Future versions of RMG might include the CHEMKIN dynamic solver. 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, C\ :sub:`2`\ H\ :sub:`6`) 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 :file:`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 :ref:`appendix `. .. _pruning: 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. .. _atol-rtol: 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:: Atol: 1e-20 Rtol: 1e-4 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: 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 :ref:`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: .. math:: \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 :math:`C_i` is the concentration of the :math:`i^{th}` species, and :math:`\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 (:math:`\partial \ln C_i/ \partial \ln k_j`), and sensitivities to heats of formation are semi-normalized (:math:`\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 (:math:`\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. .. _primarykineticlibrary: Primary Kinetic Library ------------------------ Field is **Required** but can be empty. The next section of the :file:`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 :file:`RMG_database/kinetics_groups//rateLibrary.txt` directory. For details of the kinetics libraries included with RMG that can be used as a primary kinetic library, see :ref:`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 :file:`$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 :file:`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. .. note:: RMG will not handle irreversible reactions correctly, if supplied in a Primary Kinetic Library, see :ref:`irreversiblekinetics`. .. versionchanged:: 3.2 In previous versions this feature was called "PrimaryReactionLibrary" it has been renamed to "PrimaryKineticLibrary" to better represent its functionality. .. _primaryreactionlibrary: Primary Reaction Library ------------------------ Field is **Required** but can be empty. The next section of the :file:`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 :ref:`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 :file:`$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 :ref:`irreversiblekinetics`. .. _seedmechanism: Seed Mechanisms --------------- Field is: **Required** but can be empty. The next section of the :file:`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 :ref:`reactants` section. For details of the kinetics libraries included with RMG that can be used as a seed mechanism, see :ref:`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 :file:`$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. .. note:: For more information on what files to include in a Primary Kinetic / Reaction Library or Seed Mechanism, visit :ref:`Building a Primary Kinetic Library / Reaction Library / Seed Mechanism ` .. _chemkinunits: Chemkin Units ------------- Field is **Required** The last section of the :file:`condition.txt` file specifies the units for the Arrhenius A and Ea parameters reported in the :file:`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 :file:`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 :file:`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.