diff --git a/documentation/source/theory/rmg/dynamics.rst b/documentation/source/theory/rmg/dynamics.rst index a2aae7fdd21..6fe52c0b045 100644 --- a/documentation/source/theory/rmg/dynamics.rst +++ b/documentation/source/theory/rmg/dynamics.rst @@ -67,31 +67,31 @@ for movement from surface to bulk core based on flux or dynamics criterion. Key Parameters for Dynamics Criterion and Surface Algorithm =========================================================== -* **toleranceMoveEdgeReactionToCore** +* ``toleranceMoveEdgeReactionToCore`` An edge reaction will be pulled directly into the bulk core if its dynamics number ever exceeds this value. -* **toleranceMoveEdgeReactionToSurface** +* ``toleranceMoveEdgeReactionToSurface`` An edge reaction will be pulled into the surface if its dynamics number ever exceeds this value. -* **toleranceMoveEdgeReactionToCoreInterrupt** +* ``toleranceMoveEdgeReactionToCoreInterrupt`` When any reaction's dynamics number exceeds this value the simulation will be interrupted. -* **toleranceMoveEdgeReactionToSurfaceInterrupt** +* ``toleranceMoveEdgeReactionToSurfaceInterrupt`` When the dynamics number of any reaction that would be valid for movement to the surface exceeds this value the simulation will be interrupted -* **toleranceMoveSurfaceReactionToCore** +* ``toleranceMoveSurfaceReactionToCore`` A surface reaction will be pulled into the bulk core if its dynamics number ever exceeds this value. Note this is done on the fly during simulation. -* **toleranceMoveSurfaceSpeciesToCore** +* ``toleranceMoveSurfaceSpeciesToCore`` A surface species will be pulled into the bulk core if it's rate ratio ever exceeds this value. Note this is done on the fly during simulation. diff --git a/documentation/source/theory/rmg/prune.rst b/documentation/source/theory/rmg/prune.rst index fdbdbc5aabf..d30ed7efb2a 100644 --- a/documentation/source/theory/rmg/prune.rst +++ b/documentation/source/theory/rmg/prune.rst @@ -12,30 +12,30 @@ in order to achieve both low memory consumption and mechanism accuracy. Pruning Key Parameters in Pruning ========================= -* toleranceKeepInEdge +* ``toleranceKeepInEdge`` - Any edge species to prune should have peak flux along the whole conversion course lower than toleranceKeepInEdge :math:`*` characteristic flux. Thus, larger values will lead to smaller edge mechanisms. + Any edge species to prune should have peak flux along the whole conversion course lower than ``toleranceKeepInEdge`` :math:`*` characteristic flux. Thus, larger values will lead to smaller edge mechanisms. -* toleranceMoveToCore +* ``toleranceMoveToCore`` - Any edge species to enter core model should have flux at some point larger than toleranceMoveToCore :math:`*` characteristic flux Thus, in general, smaller values will lead to larger core mechanisms. + Any edge species to enter core model should have flux at some point larger than ``toleranceMoveToCore`` :math:`*` characteristic flux. Thus, in general, smaller values will lead to larger core mechanisms. -* toleranceInterrupSimulation +* ``toleranceInterruptSimulation`` - Once flux of any edge species exceeds toleranceInterruptSimulation :math:`*` characteristic flux, dynamic simulation will be stopped. + Once flux of any edge species exceeds ``toleranceInterruptSimulation`` :math:`*` characteristic flux, dynamic simulation will be stopped. Usually this tolerance will be set a very high value so that any flux's exceeding that means mechanism is too incomplete to continue dynamic simulation. -* maximumEdgeSpecies +* ``maximumEdgeSpecies`` If dynamic simulation isn't interrupted in half way and total number of the edge species whose peak fluxes are higher than - toleranceKeepInEdge :math:`*` characteristic flux exceeds maximumEdgeSpecies, such excessive amount of edge species with lowest peak fluxes will be pruned. + ``toleranceKeepInEdge`` :math:`*` characteristic flux exceeds ``maximumEdgeSpecies``, such excessive amount of edge species with lowest peak fluxes will be pruned. -* minCoreSizeForPrune +* ``minCoreSizeForPrune`` Ensures that a minimum number of species are in the core before pruning occurs, in order to avoid pruning the model when it is far away from completeness. The default value is set to 50 species. -* minSpeciesExistIterationsForPrune +* ``minSpeciesExistIterationsForPrune`` Set the number of iterations an edge species must stay in the job before it can be pruned. The default value is 2 iterations. @@ -46,20 +46,20 @@ How Pruning Works The goal of pruning is to delete those "useless" edge species. So "usefulness" should be defined and it's natural to have flux as a criterion for "usefulness". Since flux changes with reactant conversion, peak flux is chosen here to make decision of pruning or not. - Every time pruning is triggered, edge species with peak flux lower than toleranceKeepInEdge :math:`*` characteristic flux will be deleted. + Every time pruning is triggered, edge species with peak flux lower than ``toleranceKeepInEdge`` :math:`*` characteristic flux will be deleted. .. figure:: fluxDiagramWithTolerance.png - However, pruning is not always triggered because of toleranceInterruptSimulation. As mentioned above, in order to prune, RMG needs to figure out + However, pruning is not always triggered because of ``toleranceInterruptSimulation``. As mentioned above, in order to prune, RMG needs to figure out the peak flux of each edge species, which requires dynamic simulation to complete. If some run of dynamic simulation is terminated in half way - by toleranceInterruptSimulation, pruning is rejected although there might be some edge species with peak fluxes lower than - toleranceKeepInEdge :math:`*` characteristic flux. Since pruning requires to complete dynamic simulation, setting toleranceInterruptSimulation to be positive infinity, - as an extreme case, means always enabling pruning. Another extreme case would be that it has same value as toleranceMoveToCore where + by ``toleranceInterruptSimulation``, pruning is rejected although there might be some edge species with peak fluxes lower than + ``toleranceKeepInEdge`` :math:`*` characteristic flux. Since pruning requires to complete dynamic simulation, setting ``toleranceInterruptSimulation`` to be positive infinity, + as an extreme case, means always enabling pruning. Another extreme case would be that it has same value as ``toleranceMoveToCore`` where no pruning occurs. - In summary, each run of dynamic simulation will proceed towards terminationConversion unless some flux exceeds - toleranceInterruptSimulation :math:`*` characteristic flux.Following complete simulation is the pruning of edge species whose flux is not high enough be kept - in the edge, which is followed by pruning of excessive amount of edge species to make sure total edge species number is no greater than maximumEdgeSpecies. + In summary, each run of dynamic simulation will proceed towards ``terminationConversion`` unless some flux exceeds + ``toleranceInterruptSimulation`` :math:`*` characteristic flux. Following complete simulation is the pruning of edge species whose flux is not high enough be kept + in the edge, which is followed by pruning of excessive amount of edge species to make sure total edge species number is no greater than ``maximumEdgeSpecies``. diff --git a/documentation/source/users/arkane/credits.rst b/documentation/source/users/arkane/credits.rst index b5b01313960..75f7a0b75e3 100644 --- a/documentation/source/users/arkane/credits.rst +++ b/documentation/source/users/arkane/credits.rst @@ -27,7 +27,7 @@ Developers: (rmg_dev@mit.edu) - Prof. Y.-P. Li - Dr. X. Dong - Dr. K.A. Spiekermann -- Mr. H. Wu +- H. Wu - Dr. E.E. Dames - Dr. Z.J. Buras, - Dr. N.M. Vandewiele diff --git a/documentation/source/users/rmg/features.rst b/documentation/source/users/rmg/features.rst index 8c73016d673..ebaa2f69103 100755 --- a/documentation/source/users/rmg/features.rst +++ b/documentation/source/users/rmg/features.rst @@ -4,30 +4,30 @@ Overview of Features ******************** -Thermodynamics estimation using group additivity. +**Thermodynamics estimation using group additivity.** Group additivity based on Benson's groups provide fast and reliable thermochemistry estimates. A standalone utility for estimating heat of formation, entropy, and heat capacity is also included. -Rate-based model enlargement +**Rate-based model enlargement.** Reactions are added to the model based on their rate, fastest first. -Rate-based termination. +**Rate-based termination.** The model enlargement stops when all excluded reactions are slower than a given threshold. This provides a controllable error bound on the kinetic model that is generated. -Extensible libraries +**Extensible libraries.** Ability to include reaction models on top of the provided reaction families. -Pressure-dependent reaction networks. +**Pressure-dependent reaction networks.** Dissociation, combination, and isomerization reactions have the potential to have rate coefficients that are dependent on both temperature and pressure, and RMG is able to estimate both for networks of arbitrary complexity with a bounded error. -Simultaneous mechanism generation for several conditions. +**Simultaneous mechanism generation for several conditions.** Concurrent generation of a reaction mechanism over multiple temperature and pressure conditions. Mechanisms generated this way are valid over a range of reaction conditions. -Dynamic simulation to a target conversion or time. +**Dynamic simulation to a target conversion or time.** Often the desired simulation time is not known *a priori*, so a target conversion is preferred. -Transport properties estimation using group additivity +**Transport properties estimation using group additivity.** The Lennard-Jones sigma and epsilon parameters are estimated using empirical correlations (based on a species' critical properties and acentric factor). The critical properties are estimated using a group-additivity approach; the acentric factor is also estimated using empirical correlations. A standalone application for estimating these parameters is provided, and the output is stored in CHEMKIN-readable format. diff --git a/documentation/source/users/rmg/input.rst b/documentation/source/users/rmg/input.rst index fbbff659405..1106f3a341f 100644 --- a/documentation/source/users/rmg/input.rst +++ b/documentation/source/users/rmg/input.rst @@ -647,9 +647,9 @@ this is more likely to kick out species RMG might otherwise have added to core. Advanced Setting: Taking Multiple Species At A Time ---------------------------------------------------- -Taking multiple objects (species, reactions or pdepNetworks) during a given simulation can often decrease your overall model generation time +Taking multiple objects (``Species``, ``Reaction`` or ``PDepNetwork``) during a given simulation can often decrease your overall model generation time over only taking one. For this purpose there is a ``maxNumObjsPerIter`` parameter that allows RMG to take -that many species, reactions or pdepNetworks from a given simulation. This is done in the order they trigger their respective criteria. +that many ``Species``, ``Reaction`` or ``PDepNetwork`` from a given simulation. This is done in the order they trigger their respective criteria. You can also set ``terminateAtMaxObjects=True`` to cause it to terminate when it has the maximum number of objects allowed rather than waiting around until it hits an interrupt tolerance. This @@ -669,6 +669,14 @@ For example :: Note that this can also result in larger models, however, sometimes these larger models (from taking more than one object at a time) pick up chemistry that would otherwise have been missed. + +Advanced Settings: Other +---------------------------------------------------- +- ``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`` approaches 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``: 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 pressure dependence alongside the dynamics criterion without the flux criterion. + + .. _ontheflyquantumcalculations: On the fly Quantum Calculations @@ -1033,7 +1041,7 @@ It is now possible to concatenate different model and simulator blocks into the There must be the same number of each of these blocks (although only having one simulator block and many model blocks is enabled as well) and RMG will enter each stage these define in the order they were put in the input file. -To enable easier manipulation of staging a new parameter in the model block was developed maxNumSpecies that is the number of core species at which that stage (or if it is the last stage the entire model generation process) will terminate. +To enable easier manipulation of staging a new parameter in the model block was developed ``maxNumSpecies`` that is the number of core species at which that stage (or if it is the last stage the entire model generation process) will terminate. For example :: diff --git a/documentation/source/users/rmg/installation/anacondaDeveloper.rst b/documentation/source/users/rmg/installation/anacondaDeveloper.rst index 7dbcfb66778..991a9cd35b3 100644 --- a/documentation/source/users/rmg/installation/anacondaDeveloper.rst +++ b/documentation/source/users/rmg/installation/anacondaDeveloper.rst @@ -127,6 +127,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux python-jl replace/with/path/to/rmg.py input.py You may now use RMG-Py, Arkane, as well as any of the :ref:`Standalone Modules ` included in the RMG-Py package. +For more information about using conda, please check out the `conda user guide `_. Debugging diff --git a/documentation/source/users/rmg/installation/anacondaUser.rst b/documentation/source/users/rmg/installation/anacondaUser.rst index 286f77db143..af480ff13ee 100644 --- a/documentation/source/users/rmg/installation/anacondaUser.rst +++ b/documentation/source/users/rmg/installation/anacondaUser.rst @@ -15,6 +15,8 @@ Binary Installation Using Anaconda for Unix-Based Systems: Linux and Mac OSX conda activate rmg_env + For more information about using conda, please check out the `conda user guide `_. + #. You may now run an RMG test job. Save the `Minimal Example Input File `_ to a local directory. Use the terminal to run your RMG job inside that folder using the following command :: diff --git a/documentation/source/users/rmg/kinetics.rst b/documentation/source/users/rmg/kinetics.rst index 9db406463e7..e7786c36f64 100644 --- a/documentation/source/users/rmg/kinetics.rst +++ b/documentation/source/users/rmg/kinetics.rst @@ -6,6 +6,8 @@ Kinetics Estimation This section gives in-depth descriptions of algorithms used for determining kinetic parameters. For general usage of the kinetic database see :ref:`kineticsDatabase`. + + Priority of Kinetic Databases ----------------------------- When multiple sources are available for kinetic parameters, the following priority @@ -49,27 +51,27 @@ parameters The rank of 0 is assigned to kinetics that are generally default values for top level nodes that we have little faith in. It is never used in generation and its value will in fact be overriden -by averages of its child nodes, which generates an averaged rate rule with rank 11. +by averages of its child nodes, which generates an averaged rate rule with rank 10. Only non-zero rules are used in generation. A rank of 1 is assigned to the most trustworthy kinetics, while a rank of 10 is considered very poor. Thus, a rate rule of rank 3 will be given priority over a rate rule of rank 5. -Short Glossary: +**Short Glossary:** -FCI (Full Configuration Interaction): Exact solution to Schrodinger equation within the chosen basis +**FCI (Full Configuration Interaction):** Exact solution to Schrodinger equation within the chosen basis set and Born-Oppenheimer approximation; possible for about 12 electrons with reasonably sized basis set (cost grows factorially with number of electrons). -Wn (Weizmann-n): Composite methods often with sub-kJ/mol accuracies; W1 is possible for about 9 heavy +**Wn (Weizmann-n):** Composite methods often with sub-kJ/mol accuracies; W1 is possible for about 9 heavy atoms; W1 aims to reproduce CCSD(T)/CBS; W4 aims to reproduce CCSDTQ5/CBS. -HEAT (High Accuracy Extrapolated ab inito thermochemistry): Sub-kJ/mol accuracies; essentially +**HEAT (High Accuracy Extrapolated ab inito thermochemistry):** Sub-kJ/mol accuracies; essentially CCSDTQ with various corrections; similar in cost to Wn. -CBS (Complete Basis Set): Typically obtained by extrapolating to the complete basis set limit, +**CBS (Complete Basis Set):** Typically obtained by extrapolating to the complete basis set limit, i.e., successive cc-pVDZ, cc-pVTZ, cc-pVQZ, etc. calculations with some extrapolation formula. -CCSD(T)-F12: Coupled cluster with explicit electron correlation; chemical accuracy (1 kcal/mol) +**CCSD(T)-F12:** Coupled cluster with explicit electron correlation; chemical accuracy (1 kcal/mol) possible with double-zeta basis sets. Kinetic Families @@ -113,3 +115,19 @@ up to more and more general nodes. In the worst case, the root nodes may be used A :ref:`Full List of the Kinetics Families ` in RMG is available. +Reverse Rates +------------- +Rates in the reverse direction are calculated from the forward rate (as defined by the family) +and the equilibrium constant (as calculated from thermodynamic parameters). + +Reaction Comments +----------------- +Reaction comments are saved by RMG to the ``chem_annotated.inp`` Chemkin input file. +These comments contain information about the source of the reaction rate and are read by RMG when +loading the Chemkin file. These comments are compiled from many different locations in the code. + +Comments attached to the kinetics attribute of the entry used are included first. +These can occur if there is a comment hard-coded in the kinetics database, or if the rate rule was +derived from a training reaction, in which case ``From Training reaction # for rate rule ##`` +is automatically added. Then, comments describing the match are added based on the details of +how the kinetics were estiamted. Finally, additional metadata about the reaction type are included. diff --git a/documentation/source/users/rmg/running.rst b/documentation/source/users/rmg/running.rst index 0bb21b80a6e..038aadb8935 100755 --- a/documentation/source/users/rmg/running.rst +++ b/documentation/source/users/rmg/running.rst @@ -91,16 +91,46 @@ Currently, multiprocessing is implemented for reaction generation and the genera Details on profiling RMG jobs ----------------------------- -Here, we explain how to profile an RMG job. For starters, use the ``saveSeedModulus`` option in the input file, as described in the Section :ref:`Miscellaneous Options `, to save the seed mechanism at regular intervals, perhaps every 50 or 100 iterations depending on the size of the mechanism. This option is particularly important for saving intermediate steps when working with large mechanisms; it may be prudent to save and examine how the chemistry changes over mechanism development rather than just obtaining the final seed mechanism. +Here, we explain how to profile an RMG job. For starters, use the ``saveSeedModulus`` option in the input file, as described +in the Section :ref:`Miscellaneous Options `, to save the seed mechanism at regular intervals, +perhaps every 50 or 100 iterations depending on the size of the mechanism. This option is particularly important for saving +intermediate steps when working with large mechanisms; it may be prudent to save and examine how the chemistry changes over +mechanism development rather than just obtaining the final seed mechanism. These seeds can then be restarted with use of the ``-r`` flag, as described in the Section :ref:`Input Flags ` above. Additionally, restarting these seeds with the ``-i`` flag allows examination of how computational effort, time spent in each module, individual processor memory consumption if using the the ``-n`` flag, and overall memory consumption change over the course of mechanism development. To time profile, one could use:: rmg.py -r /seed -p -i 15 restart_from_seed.py -such that 15 iterations was arbitrarily chosen as a representative sample size to obtain profiling information. To run memory profiling, one option is to install a `python memory profiler `_ as an additional dependency. As detailed in their linked GitHub, there are options for line-by-line memory usage of small functions and for time-based memory usage. +such that 15 iterations was arbitrarily chosen as a representative sample size to obtain profiling information. +To run memory profiling, one option is to install a `python memory profiler `_ as +an additional dependency. As detailed in their linked GitHub, there are options for line-by-line memory usage of small functions +and for time-based memory usage. An example of memory profiling is:: mprof run --multiprocess rmg.py -r /seed -i 15 -n 3 restart_from_seed.py -such that this example demonstrates how to obtain memory consumption for each of three specified processes and again use 15 iterations to obtain representative profiling information. Please see the linked GitHub to learn more about how the memory profiler tool can help characterize your process. +such that this example demonstrates how to obtain memory consumption for each of three specified processes +and again use 15 iterations to obtain representative profiling information. Please see the linked GitHub to +learn more about how the memory profiler tool can help characterize your process. + + +Logging +-------- +As RMG runs, it will continuously log information as the run progresses. By default, this will include +input file information, databases loaded, kinetic rate rules used, thermo estimation, model enlargment details, +reaction simulation (to see if termination criteria are met), and (after several iterations) final mechanism +details, execution time, and memory usage. + +The logged information can be controlled by +specifying one of the optional arguments: + +``-q`` or ``--quiet``: Only warnings and errors are printed, but not saved in ``RMG.log``. + +``-v`` or ``--verbose``: Includes much more information about which kinetic families and rules are used. +Also includes details about new species and new template reactions before estimating thermo of new created species +after model enlargment. + +``-d`` or ``--debug``: In addition to ``--verbose`` info, also provides information about how to find the specific kinetics groups +when they are loaded. + diff --git a/documentation/source/users/rmg/species.rst b/documentation/source/users/rmg/species.rst index fccd09b9c34..4410d48847b 100644 --- a/documentation/source/users/rmg/species.rst +++ b/documentation/source/users/rmg/species.rst @@ -4,9 +4,29 @@ Species Representation ********************** -Species objects in RMG contain a variety of attributes, including user given names, -thermochemistry, as well as structural isomers. See the :ref:`rmgpy.species.Species` class -documentation for more information. +The base class for chemical structures in RMG is ``Graph`` (see :ref:`rmgpy.molecule.Graph`), +which is a basic implementation of a 2D mathematical graph. +A graph is comprised of a set of vertices connected by a set of edges. +In RMG, the Graph class does not store any chemical information on its own, +but it is the parent class of Group and Molecule. + +The ``Group`` class is used to represent a molecular fragment, whereas the ``Molecule`` class +is used to represent a specific molecular structure. +A ``Group`` object can have a list of allowed specifications for each atom or bond property, +while a ``Molecule`` object can only have one. Additionally, a ``Group`` object does not +have to have a complete molecule while a Molecule object must be a full chemical structure. +See the :ref:`rmgpy.molecule.Group` and :ref:`rmgpy.molecule.Molecule` class documentation. + +Finally, there is the ``Species`` class. Although colloquially we use molecules and species +interchangeably, these terms have precise meanings in RMG. +A ``Species`` object contains a list of molecule objects which are different representations of +the same chemical compound (i.e., resonance structures). +It also contains a descriptive label for the species, its thermochemical properties, transport data, +and molecular weight, among other information. This distinction is important because many chemical +compounds have resonance structures. Therefore, a ``Molecule`` object is a graph that denotes the structure +of a specific resonance isomer, while a ``Species`` incorporates all resonance structures found into one object. +This prevents duplicate reactions from being generated for two molecule objects that are really the same chemical compound. +See the :ref:`rmgpy.species.Species` class documentation for more information. RMG considers each species to be unique, and comprised of a set of molecular structural isomers, including resonance isomers. RMG uses the list of resonance isomers to diff --git a/examples/rmg/commented/input.py b/examples/rmg/commented/input.py index 91b01b2b11b..6cc5173c9f3 100644 --- a/examples/rmg/commented/input.py +++ b/examples/rmg/commented/input.py @@ -19,7 +19,7 @@ thermoLibraries=['BurkeH2O2', 'primaryThermoLibrary', 'DFT_QCI_thermo', 'CBS_QB3_1dHR'], # overrides RMG transport calculations with these values. # if species exist in multiple libraries, the earlier libraries overwrite the previous values - transportLibraries=['PrimaryTransportLibrary.py'], + transportLibraries=['PrimaryTransportLibrary'], # overrides RMG kinetics estimation if needed in the core of RMG. # list of libraries found at http://rmg.mit.edu/database/kinetics/libraries/ # libraries can be input as either a string or tuple of form ('library_name',True/False)