diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..83f07e7ee3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +## How to contribute to RMG-Py + +Thank you for contributing to RMG-Py! Please take a moment to review our guidelines: + +### **Did you find a bug? Do you want to see a new feature?** + +* Please open an Issue to the corresponding repository: + * [RMG-Py](https://github.com/ReactionMechanismGenerator/RMG-Py/issues): For functionality of the RMG and Arkane software packages + * [RMG-database](https://github.com/ReactionMechanismGenerator/RMG-database/issues): For issues related to the data available to RMG + * [RMG-website](https://github.com/ReactionMechanismGenerator/RMG-website/issues): For issues related to the [RMG website](https://rmg.mit.edu) + + +### **Did you write code that fixes a bug or adds a new feature?** + +* Open a new GitHub PR to merge into the main branch. Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. + +* Your PR must pass unit tests, regression tests, and code coverage, and receive approval from at least one reviewer before it can be merged in. + +* If you wrote a new feature, please [add unit tests](https://github.com/ReactionMechanismGenerator/RMG-Py/tree/main/test/rmgpy). We currently use [pytest](https://docs.pytest.org/en/stable/) for our unit testing. + +* If you wrote a significant new feature, please add a regression test: + * First, please create an input file that includes your new feature. Ensure `saveEdgeSpecies` is set to `True` so that the edge model will also be saved to a file. If applicable, include diverse sets of input conditions to test compatibility with other features. + * Generate the reaction mechanism corresponding to the input file. Ensure that the simulation does not take more than 15 minutes maximum. You can reduce simulation times in multiple ways, e.g. by increasing the `toleranceMoveToCore` flag. + * In the `test/regression` folder, create a new folder with a relevant name, and copy the RMG-Py simulation input file in this folder. Include this new folder in your PR. + * In `.github/workflows/CI.yml`, edit the two lists of regression tests in the `Regression Tests - Execution` and `Regression Tests - Compare to Baseline` steps to add the name of your folder. Be sure to follow BASH syntax. + + * > Warning: This will __fail__ CI because of directory not found errors. This is because the baseline files used for comparison in the regression tests do not exist yet. Your PR will need to be merged by bypassing branch protection restrictions. + + +### **Do you want to contribute to the documentation?** + +* Documentation is [hosted here](http://reactionmechanismgenerator.github.io/RMG-Py/) using [Sphinx](https://www.sphinx-doc.org/en/master/). + +* The live version of the documentation is hosted on the `gh-pages` branch which is updated upon pushes to the `main` branch of RMG-Py. + +* To add new documentation, create or modify `.rst` (reStructuredText) files under the `documentation` directory and create a PR to push to `main`. For a primer on how to write `.rst` markup, please [check out the Sphinx documentation.](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) + +* Please test the documentation on a local build (e.g., via `make html` in the `documentation` directory) before pushing changes. + +### **Do you have questions?** + +* Email us at rmg_dev@mit.edu. + +### **Best practices for PRs** + +* Rebase to the main branch before working, to avoid merge conflicts. + +* Keep PRs small and aim to merge quickly. + +* Commits should be specific and as small as required; commit messages should be descriptive and as long as required. Commit messages should explain *why* the change is needed. We recommend following [these guidelines.](https://wiki.openstack.org/wiki/GitCommitMessages) + +* Submit a PR only when the code is polished and ready for review. Consider opening a draft PR for work in progress that requires collaborator input. + +* Please follow the [PEP8 Python style guide.](https://peps.python.org/pep-0008/) + +Thank you! + +RMG Developers \ No newline at end of file diff --git a/documentation/source/theory/rmg/dynamics.rst b/documentation/source/theory/rmg/dynamics.rst index a2aae7fdd2..6fe52c0b04 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 fdbdbc5aab..d30ed7efb2 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 4e9d9cc981..ded1cd6aad 100644 --- a/documentation/source/users/arkane/credits.rst +++ b/documentation/source/users/arkane/credits.rst @@ -9,7 +9,7 @@ Project Supervisors: - Prof. William H. Green (whgreen@mit.edu) - Prof. Richard H. West (r.west@northeastern.edu) - Prof. C. Franklin Goldsmith (franklin_Goldsmith@brown.edu) -- Asst. Prof. Alon Grinberg Dana (alon@technion.ac.il) +- Prof. Alon Grinberg Dana (alon@technion.ac.il) Developers: (rmg_dev@mit.edu) @@ -24,10 +24,10 @@ Developers: (rmg_dev@mit.edu) - Dr. D.S. Ranasinghe - Dr. R.J. Gillis - Dr. A.M. Payne -- Asst. Prof. Y.-P. Li -- X. Dong -- K.A. Spiekermann -- H. Wu +- Prof. Y.-P. Li +- Dr. X. Dong +- Dr. K.A. Spiekermann +- Mr. H. Wu - Dr. E.E. Dames - Dr. Z.J. Buras, - Dr. N.M. Vandewiele @@ -41,11 +41,4 @@ Developers: (rmg_dev@mit.edu) How to Cite *********** -A. Grinberg Dana, M.S. Johnson, J.W. Allen, S. Sharma, S. Raman, M. Liu, C.W. Gao, C.A. Grambow, M.J. Goldman, -D.S. Ranasinghe, R.J. Gillis, A.M. Payne, Y.-P. Li, X. Dong, K.A. Spiekermann, H. Wu, E.E. Dames, Z.J. Buras, -N.M. Vandewiele, N.W. Yee, S.S. Merchant, B. Buesser, C.A. Class, C.F. Goldsmith, R.H. West, W.H. Green, -"Automated reaction kinetics and network exploration (Arkane): -A statistical mechanics, thermodynamics, transition state theory, and master equation software", -*International Journal of Chemical Kinetics* 2023, 55(6), 300-323. - -DOI: `10.1002/kin.21637 `_ +Please refer to the ``Arkane`` reference in the `CITATIONS.bib file `_. diff --git a/documentation/source/users/rmg/credits.rst b/documentation/source/users/rmg/credits.rst index faa4284055..6618c6499f 100755 --- a/documentation/source/users/rmg/credits.rst +++ b/documentation/source/users/rmg/credits.rst @@ -16,26 +16,29 @@ Project Supervisors: Current Developers: (rmg_dev@mit.edu) -- Dr. Alon Grinberg Dana +- Prof. Alon Grinberg Dana - Dr. Matt Johnson -- Yen-Ting Wang -- Xiaorui Dong -- Hao-Wei Pang +- Dr. Anna Doner - Oscar Wu -- Kevin Spiekermann - Jonathan Zheng - Jackson Burns - Nathan Morgan +- Prof. Richard H. West - Prof. C. Franklin Goldsmith -- Dr. Katrin Blondal - Dr. Bjarne Kreitz +- Chao Xu - Chris Blais - Sevy Harris - Nora Khalil Previous Developers: +- Dr. Xiaorui Dong +- Dr. Hao-Wei Pang +- Dr. Kevin Spiekermann +- Yen-Ting Wang - Dr. Joshua W. Allen +- Dr. Katrin Blondal - Dr. Yunsie Chung - Dr. David Farina - Dr. Mark Goldman @@ -66,25 +69,4 @@ Previous Developers: How to Cite *********** -C.W. Gao, J.W. Allen, W.H. Green, R.H. West, -"Reaction Mechanism Generator: Automatic construction of chemical kinetic mechanisms", -*Computer Physics Communications* 2016, 203, 212-225. - -DOI: `10.1016/j.cpc.2016.02.013 `_ - - -M. Liu, A. Grinberg Dana, M.S. Johnson, M.J. Goldman, A. Jocher, A.M. Payne, C.A. Grambow, K. Han, N.W. Yee, -E.J. Mazeau, K. Blondal, R.H. West, C.F. Goldsmith, W.H. Green, -"Reaction Mechanism Generator v3.0: Advances in Automatic Mechanism Generation", -*Journal of Chemical Information and Modeling* 2021, 61(6), 2686–2696. - -DOI: `10.1021/acs.jcim.0c01480 `_ - - - -M.S. Johnson, X. Dong, A. Grinberg Dana, Y. Chung, D. Farina, R.J. Gillis, M. Liu, N.W. Yee, K. Blondal, -E. Mazeau, C.A. Grambow, A.M. Payne, K.A. Spiekermann, H.-W. Pang, C.F. Goldsmith, R.H. West, W.H. Green, -"The RMG Database for Chemical Property Prediction", -*Chemical Information* 2022, 62(20), 4906–4915. - -DOI: `10.1021/acs.jcim.2c00965 `_ +Please refer to the ``RMG``, ``RMG3``, and ``RMG_Database`` citations in the `CITATIONS.bib file `_. diff --git a/documentation/source/users/rmg/database/kinetics.rst b/documentation/source/users/rmg/database/kinetics.rst index 7c1a1a6195..3ec2953d5f 100644 --- a/documentation/source/users/rmg/database/kinetics.rst +++ b/documentation/source/users/rmg/database/kinetics.rst @@ -52,150 +52,7 @@ Kinetic libraries should also be used in the cases where: * No family exists for the class of reaction * You are not confident about the accuracy of kinetic parameters -Below is a list of pre-packaged kinetics library reactions in RMG: - - -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Library |Description | -+=============================================================+==========================================================================================+ -|1989_Stewart_2CH3_to_C2H5_H |Chemically Activated Methyl Recombination to Ethyl (2CH3 -> C2H5 + H) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|2001_Tokmakov_H_Toluene_to_CH3_Benzene |H + Toluene = CH3 + Benzene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|2005_Senosiain_OH_C2H2 |pathways on the OH + acetylene surface | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|2006_Joshi_OH_CO |pathways on OH + CO = HOCO = H + CO2 surface | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|2009_Sharma_C5H5_CH3_highP |Cyclopentadienyl + CH3 in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|2015_Buras_C2H3_C4H6_highP |Vinyl + 1,3-Butadiene and other C6H9 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|biCPD_H_shift |Sigmatropic 1,5-H shifts on biCPD PES | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|BurkeH2O2inArHe |Comprehensive H2/O2 kinetic model in Ar or He atmosphere | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|BurkeH2O2inN2 |Comprehensive H2/O2 kinetic model in N2 atmosphere | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|C2H4+O_Klipp2017 |C2H4 + O intersystem crossing reactions, probably important for all C/H/O combustion | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|C10H11 |Cyclopentadiene pyrolysis in the presence of ethene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|C3 |Cyclopentadiene pyrolysis in the presence of ethene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|C6H5_C4H4_Mebel |Formation Mechanism of Naphthalene and Indene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Chernov |Soot Formation with C1 and C2 Fuels (aromatic reactions only) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|CurranPentane |Ignition of pentane isomers | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Dooley |Methyl formate (contains several mechanisms) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|ERC-FoundationFuelv0.9 |Small molecule combustio (natural gas) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Ethylamine |Ethylamine pyrolysis and oxidation | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|FFCM1(-) |Foundational Fuel Chemistry Model Version 1.0 (excited species removed) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2005_Ismail_C6H5_C4H6_highP |Phenyl + 1,3-Butadiene and other C10H11 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2012_Matsugi_C3H3_C7H7_highP |Propargyl + Benzyl and other C10H10 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2016_Mebel_C9H9_highP |C9H9 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2016_Mebel_C10H9_highP |C10H9 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2016_Mebel_Indene_CH3_highP |CH3 + Indene in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2017_Buras_C6H5_C3H6_highP |Phenyl + Propene and other C9H11 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2017_Mebel_C6H4C2H_C2H2_highP |C10H7 HACA reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2017_Mebel_C6H5_C2H2_highP |C8H7 HACA reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2017_Mebel_C6H5_C4H4_highP |Phenyl + Vinylacetylene and other C10H9 reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/2017_Mebel_C6H5C2H2_C2H2_highP |C10H9 HACA reactions in high-P limit | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|First_to_Second_Aromatic_Ring/phenyl_diacetylene_effective |Effective Phenyl + Diacetylene rates to Benzofulvenyl and 2-Napthyl | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Fulvene_H |Cyclopentadiene pyrolysis in the presence of ethene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|GRI-HCO |The `HCO <=> H + CO` reaction | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|GRI-Mech3.0 |Gas Research Institute natural gas mechanism optimized for 1 atm (discontinued Feb. 2000) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|GRI-Mech3.0-N |GRI-Mech3.0 including nitrogen chemistry (NOx from N2) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Glarborg |Mechanisms by P. Glarborg, assorted by carbon number | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|JetSurF2.0 |Jet Surrogate Fuel model up tp C12 (excited species removed) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Klippenstein_Glarborg2016 |Methane oxidation at high pressures and intermediate temperatures | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Lai_Hexylbenzene |Alkylaromatic reactions for hexylbenzene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Mebel_C6H5_C2H2 |Pathways from benzene to naphthalene | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Mebel_Naphthyl |Reactions of naphthyl-1 and naphthyl-2 | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Methylformate |Methyl formate | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Narayanaswamy |Oxidation of substituted aromatic species (aromatic reactions only) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Nitrogen_Dean_and_Bozzelli |Combustion Chemistry of Nitrogen | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Nitrogen_Glarborg_Gimenez_et_al |High pressure C2H4 oxidation with nitrogen chemistry | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Nitrogen_Glarborg_Lucassen_et_al |Fuel-nitrogen conversion in the combustion of small amines | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Nitrogen_Glarborg_Zhang_et_al |Premixed nitroethane flames at low pressure | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|NOx |important NOx related reactions, e.g., thermal & prompt NO, N2O | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|NOx/LowT |Low temperature kinetics (~<1000K) for selected reactions from the NOx library | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|OxygenSingTrip |Reactions of singlet and triplet oxygen | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|SOx |important SOx related reactions, e.g., H-S, C-S, SOx | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/DMDS |Dimethyl disulfide (CH3SSCH3) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/DMS |Dimethyl disulfide (CH3SSCH3) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/DTBS |Di-tert-butyl Sulfide (C4H9SSC4H9) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/GlarborgBozzelli |SO2 effect on moist CO oxidation with and without NO | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/GlarborgH2S |H2S oxidation at high pressures | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/GlarborgMarshall |OCS chemistry | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/GlarborgNS |Interactions between nitrogen and sulfur species in combustion | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/Hexanethial_nr |Hexyl sulfide (C6H13SC6H13) + hexadecane (C16H34) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/Sendt |Small sulfur molecule | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/TP_Song |Thiophene (C4H4S, aromatic) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|Sulfur/Thial_Hydrolysis |Thioformaldehyde (CH2S) and thioacetaldehyde (C2H4S) to COS and CO2 | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|TEOS |Organic oxidized silicone | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|c-C5H5_CH3_Sharma |Cyclopentadienyl + CH3 | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|combustion_core |Leeds University natural gas mechanism (contains versions 2-5) | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|fascella |Cyclopentadienyl + acetyl | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|kislovB |Formation of indene in combustion | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|naphthalene_H |Cyclopentadiene pyrolysis in the presence of ethene Part 1 | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|vinylCPD_H |Cyclopentadiene pyrolysis in the presence of ethene Part 2 | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ -|PrimaryH2O2 |Updated rate parameters for the H2O2 system that include ter-molecular reactions | -+-------------------------------------------------------------+------------------------------------------------------------------------------------------+ +`A full list of the libraries can be found on the RMG website `_ (please allow 1-2 minutes for the website to load). .. _kinetics_families_db: @@ -212,237 +69,7 @@ Each reaction family contains the files: * training.py containing a training set for the family * rules.py containing kinetic parameters for rules -There are currently 74 reaction families in RMG: - -.. |f00| image:: images/kinetics_families/1+2_Cycloaddition.png - :scale: 40% -.. |f01| image:: images/kinetics_families/1,2-Birad_to_alkene.png - :scale: 40% -.. |f02| image:: images/kinetics_families/1,2_Insertion_CO.png - :scale: 40% -.. |f03| image:: images/kinetics_families/1,2_Insertion_carbene.png - :scale: 40% -.. |f04| image:: images/kinetics_families/1,2_NH3_elimination.png - :scale: 40% -.. |f05| image:: images/kinetics_families/1,2_shiftC.png - :scale: 40% -.. |f06| image:: images/kinetics_families/1,2_shiftS.png - :scale: 40% -.. |f07| image:: images/kinetics_families/1,3_Insertion_CO2.png - :scale: 40% -.. |f08| image:: images/kinetics_families/1,3_Insertion_ROR.png - :scale: 40% -.. |f09| image:: images/kinetics_families/1,3_Insertion_RSR.png - :scale: 40% -.. |f10| image:: images/kinetics_families/1,3_NH3_elimination.png - :scale: 40% -.. |f75| image:: images/kinetics_families/1,3_sigmatropic_rearrangement.png - :scale: 40% -.. |f11| image:: images/kinetics_families/1,4_Cyclic_birad_scission.png - :scale: 40% -.. |f12| image:: images/kinetics_families/1,4_Linear_birad_scission.png - :scale: 40% -.. |f13| image:: images/kinetics_families/2+2_cycloaddition.png - :scale: 40% -.. |f17| image:: images/kinetics_families/6_membered_central_C-C_shift.png - :scale: 40% -.. |f18| image:: images/kinetics_families/Baeyer-Villiger_step1_cat.png - :scale: 40% -.. |f19| image:: images/kinetics_families/Baeyer-Villiger_step2.png - :scale: 40% -.. |f20| image:: images/kinetics_families/Baeyer-Villiger_step2_cat.png - :scale: 40% -.. |f21| image:: images/kinetics_families/Bimolec_Hydroperoxide_Decomposition.png - :scale: 40% -.. |f22| image:: images/kinetics_families/Birad_R_Recombination.png - :scale: 40% -.. |f23| image:: images/kinetics_families/Birad_recombination.png - :scale: 40% -.. |f24| image:: images/kinetics_families/CO_Disproportionation.png - :scale: 40% -.. |f25| image:: images/kinetics_families/Concerted_Intra_Diels_alder_monocyclic_1,2_shiftH.png - :scale: 40% -.. |f26| image:: images/kinetics_families/Cyclic_Ether_Formation.png - :scale: 40% -.. |f27| image:: images/kinetics_families/Cyclic_Thioether_Formation.png - :scale: 40% -.. |f28| image:: images/kinetics_families/Cyclopentadiene_scission.png - :scale: 40% -.. |f29| image:: images/kinetics_families/Diels_alder_addition.png - :scale: 40% -.. |f30| image:: images/kinetics_families/Disproportionation.png - :scale: 40% -.. |f31| image:: images/kinetics_families/HO2_Elimination_from_PeroxyRadical.png - :scale: 40% -.. |f32| image:: images/kinetics_families/H_Abstraction.png - :scale: 40% -.. |f33| image:: images/kinetics_families/Intra_2+2_cycloaddition_Cd.png - :scale: 40% -.. |f34| image:: images/kinetics_families/Intra_5_membered_conjugated_C=C_C=C_addition.png - :scale: 40% -.. |f35| image:: images/kinetics_families/Intra_Diels_alder_monocyclic.png - :scale: 40% -.. |f36| image:: images/kinetics_families/Intra_Disproportionation.png - :scale: 40% -.. |f37| image:: images/kinetics_families/Intra_RH_Add_Endocyclic.png - :scale: 40% -.. |f38| image:: images/kinetics_families/Intra_RH_Add_Exocyclic.png - :scale: 40% -.. |f39| image:: images/kinetics_families/Intra_R_Add_Endocyclic.png - :scale: 40% -.. |f40| image:: images/kinetics_families/Intra_R_Add_ExoTetCyclic.png - :scale: 40% -.. |f41| image:: images/kinetics_families/Intra_R_Add_Exo_scission.png - :scale: 40% -.. |f42| image:: images/kinetics_families/Intra_R_Add_Exocyclic.png - :scale: 40% -.. |f43| image:: images/kinetics_families/Intra_Retro_Diels_alder_bicyclic.png - :scale: 40% -.. |f44| image:: images/kinetics_families/Intra_ene_reaction.png - :scale: 40% -.. |f45| image:: images/kinetics_families/Korcek_step1.png - :scale: 40% -.. |f46| image:: images/kinetics_families/Korcek_step1_cat.png - :scale: 40% -.. |f47| image:: images/kinetics_families/Korcek_step2.png - :scale: 40% -.. |f48| image:: images/kinetics_families/Peroxyl_Disproportionation.png - :scale: 40% -.. |f49| image:: images/kinetics_families/Peroxyl_Termination.png - :scale: 40% -.. |f50| image:: images/kinetics_families/R_Addition_COm.png - :scale: 40% -.. |f51| image:: images/kinetics_families/R_Addition_CSm.png - :scale: 40% -.. |f52| image:: images/kinetics_families/R_Addition_MultipleBond.png - :scale: 40% -.. |f53| image:: images/kinetics_families/R_Recombination.png - :scale: 40% -.. |f54| image:: images/kinetics_families/Singlet_Carbene_Intra_Disproportionation.png - :scale: 40% -.. |f55| image:: images/kinetics_families/Singlet_Val6_to_triplet.png - :scale: 40% -.. |f56| image:: images/kinetics_families/SubstitutionS.png - :scale: 40% -.. |f57| image:: images/kinetics_families/Substitution_O.png - :scale: 40% -.. |f58| image:: images/kinetics_families/Surface_Abstraction.png - :scale: 40% -.. |f59| image:: images/kinetics_families/Surface_Adsorption_Bidentate.png - :scale: 40% -.. |f60| image:: images/kinetics_families/Surface_Adsorption_Dissociative.png - :scale: 40% -.. |f61| image:: images/kinetics_families/Surface_Adsorption_Double.png - :scale: 40% -.. |f62| image:: images/kinetics_families/Surface_Adsorption_Single.png - :scale: 40% -.. |f63| image:: images/kinetics_families/Surface_Adsorption_vdW.png - :scale: 40% -.. |f64| image:: images/kinetics_families/Surface_Bidentate_Dissociation.png - :scale: 40% -.. |f65| image:: images/kinetics_families/Surface_Dissociation.png - :scale: 40% -.. |f66| image:: images/kinetics_families/Surface_Dissociation_vdW.png - :scale: 40% -.. |f67| image:: images/kinetics_families/Surface_Recombination.png - :scale: 40% -.. |f68| image:: images/kinetics_families/intra_H_migration.png - :scale: 40% -.. |f69| image:: images/kinetics_families/intra_NO2_ONO_conversion.png - :scale: 40% -.. |f70| image:: images/kinetics_families/intra_OH_migration.png - :scale: 40% -.. |f71| image:: images/kinetics_families/intra_substitutionCS_cyclization.png - :scale: 40% -.. |f72| image:: images/kinetics_families/intra_substitutionCS_isomerization.png - :scale: 40% -.. |f73| image:: images/kinetics_families/intra_substitutionS_cyclization.png - :scale: 40% -.. |f74| image:: images/kinetics_families/intra_substitutionS_isomerization.png - :scale: 40% -.. |f76| image:: images/kinetics_families/lone_electron_pair_bond.png - :scale: 40% - -.. table:: - :widths: 40 60 - - ===================================================== ===== - **1+2_Cycloaddition** |f00| - **1,2-Birad_to_alkene** |f01| - **1,2_Insertion_CO** |f02| - **1,2_Insertion_carbene** |f03| - **1,2_NH3_elimination** |f04| - **1,2_shiftC** |f05| - **1,2_shiftS** |f06| - **1,3_Insertion_CO2** |f07| - **1,3_Insertion_ROR** |f08| - **1,3_Insertion_RSR** |f09| - **1,3_NH3_elimination** |f10| - **1,3_sigmatropic_rearrangement** |f75| - **1,4_Cyclic_birad_scission** |f11| - **1,4_Linear_birad_scission** |f12| - **2+2_cycloaddition** |f13| - **6_membered_central_C-C_shift** |f17| - **Baeyer-Villiger_step1_cat** |f18| - **Baeyer-Villiger_step2** |f19| - **Baeyer-Villiger_step2_cat** |f20| - **Bimolec_Hydroperoxide_Decomposition** |f21| - **Birad_R_Recombination** |f22| - **Birad_recombination** |f23| - **CO_Disproportionation** |f24| - **Concerted_Intra_Diels_alder_monocyclic_1,2_shiftH** |f25| - **Cyclic_Ether_Formation** |f26| - **Cyclic_Thioether_Formation** |f27| - **Cyclopentadiene_scission** |f28| - **Diels_alder_addition** |f29| - **Disproportionation** |f30| - **HO2_Elimination_from_PeroxyRadical** |f31| - **H_Abstraction** |f32| - **Intra_2+2_cycloaddition_Cd** |f33| - **Intra_5_membered_conjugated_C=C_C=C_addition** |f34| - **Intra_Diels_alder_monocyclic** |f35| - **Intra_Disproportionation** |f36| - **Intra_RH_Add_Endocyclic** |f37| - **Intra_RH_Add_Exocyclic** |f38| - **Intra_R_Add_Endocyclic** |f39| - **Intra_R_Add_ExoTetCyclic** |f40| - **Intra_R_Add_Exo_scission** |f41| - **Intra_R_Add_Exocyclic** |f42| - **Intra_Retro_Diels_alder_bicyclic** |f43| - **Intra_ene_reaction** |f44| - **Korcek_step1** |f45| - **Korcek_step1_cat** |f46| - **Korcek_step2** |f47| - **Peroxyl_Disproportionation** |f48| - **Peroxyl_Termination** |f49| - **R_Addition_COm** |f50| - **R_Addition_CSm** |f51| - **R_Addition_MultipleBond** |f52| - **R_Recombination** |f53| - **Singlet_Carbene_Intra_Disproportionation** |f54| - **Singlet_Val6_to_triplet** |f55| - **SubstitutionS** |f56| - **Substitution_O** |f57| - **Surface_Abstraction** |f58| - **Surface_Adsorption_Bidentate** |f59| - **Surface_Adsorption_Dissociative** |f60| - **Surface_Adsorption_Double** |f61| - **Surface_Adsorption_Single** |f62| - **Surface_Adsorption_vdW** |f63| - **Surface_Bidentate_Dissociation** |f64| - **Surface_Dissociation** |f65| - **Surface_Dissociation_vdW** |f66| - **Surface_Recombination** |f67| - **intra_H_migration** |f68| - **intra_NO2_ONO_conversion** |f69| - **intra_OH_migration** |f70| - **intra_substitutionCS_cyclization** |f71| - **intra_substitutionCS_isomerization** |f72| - **intra_substitutionS_cyclization** |f73| - **intra_substitutionS_isomerization** |f74| - **lone_electron_pair_bond** |f76| - ===================================================== ===== - +`A full list of the kinetic families can be found on the RMG website `_ (please allow 1-2 minutes for the website to load). Recipe ------ diff --git a/documentation/source/users/rmg/faq.rst b/documentation/source/users/rmg/faq.rst index 2d2b3acc1e..aa950a8d70 100644 --- a/documentation/source/users/rmg/faq.rst +++ b/documentation/source/users/rmg/faq.rst @@ -9,52 +9,19 @@ We have compiled some common questions about installing and using RMG below. For any other questions related to RMG and its usage and installation, please post an issue on our `GitHub issues page `_, where you can also search for any previous reports of your issue. -Alternatively, you can also ask questions via the `RMG-Py chat room `_ -or by contacting us directly at rmg_dev@mit.edu. +Alternatively, you can contact us directly at rmg_dev@mit.edu. Installing RMG ============== -#. **How can I install RMG-Py without Anaconda?** - - Usually we don't recommend installing RMG-Py without Anaconda because it takes longer and is easier to get trouble - with package management. But one still can try direct installation on Linux or MacOS by following - :ref:`Linux instruction` or :ref:`MacOS instruction`. The RMG team does not use this install approach - internally any more, so these instructions are not actively maintained. - -#. **Why does RMG-Py not work natively on Windows?** +#. **Why does RMG-Py not work natively from source on Windows?** One major challenge with supporting Windows is ensuring that all of our dependencies support Windows. This becomes non-trivial as we add more dependencies to support increasing RMG functionality. Ensuring that code within RMG is platform-agnostic is also challenging, since it is rarely the first priority for new development because our main focus is on research. -#. **What is the recommended way to run RMG-Py on Windows?** - - The currently recommended way to run RMG on Windows is to set up a Linux environment. There are multiple ways you - can approach this. Windows 10 supports a Linux subsystem which allows one to set up a Linux environment within - Windows without using virtualization. You can find instructions on setting up RMG within the Linux subsystem - :ref:`here`. - - Another option would be to set up a full Linux virtual machine using something like VirtualBox or VMWare Workstation. - The benefit of this option is being able to run in a full Linux environment. However, running two operating systems - simultaneously does result in excess resource overhead, so it may not be suitable for running extended RMG jobs. - Instructions for setting up a virtual machine can be found :ref:`here`. - - A third option that we are currently beginning to explore using `Docker `_, which is a - container-based infrastructure which shares the same benefits as a virtual machine but with less overhead. There - are some test images of RMG-Py which can be found on `Docker Hub `_ if you would like to - give this a try. More detailed instructions will be made available once we officially support this approach. - -#. **Windows binary installation gives ``WindowsError: [Error 5]``?** - - Error 5 is access is denied, so this is either a permissions error, or an issue with the Windows file lock. - `These posts `_ suggest rebooting the computer (in case it's a file lock), - and running the anaconda prompt, from which you run ``conda create -c rmg --name rmg_env rmg rmgdatabase``, - as an administrator (in case it's a permissions error). Please checkout one example from a user having - `Windows binary installation issue `_. - Running RMG =========== @@ -98,24 +65,6 @@ Running RMG factors, such as poor thermochemistry or rate constants. Unfortunately, there is currently no good way to debug and fix these types of errors. -#. **Why did I get** ``Segmentation fault:11`` **after installing RMG on my machine?** - - **Segmentation fault** is a typical error in C code, caused by a program trying to read or write an illegal memory - location, i.e. one it is not allowed to access. The most common cause in RMG is a conflict between two different - versions of a shared library. RMG has some dependencies which are written in C++, e.g. rdkit, openbabel. If you - compile one of these with a different version of some compiler library, or you compile RMG using one version and - run it with another, you will often get a Segmentation fault. Chances are those packages are not up to date, or - maybe your environmental variable ``PATH`` is messed up so that the wrong version of something is being found. - Please see one example from a user having same - `Segmentation fault issue `_. - -#. **Why did I get** ``IOError: [Errno 13] Permission denied: 'C:\\RMG.log'`` - - You do not have permission to write to the log file. Try running the RMG from a different folder that you do have - write permission to, such as within your user's documents directory, or else try running the command prompt as an - Administrator (so that you have write permission everywhere). See for example - `issue #817 `_. - Miscellaneous ============= diff --git a/documentation/source/users/rmg/features.rst b/documentation/source/users/rmg/features.rst index 8c73016d67..ebaa2f6910 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 fbbff65940..1106f3a341 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 e1aed5f7db..3459111559 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 286f77db14..af480ff13e 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/installation/dependencies.rst b/documentation/source/users/rmg/installation/dependencies.rst index ba8a3ad66c..6cfbf0dc49 100644 --- a/documentation/source/users/rmg/installation/dependencies.rst +++ b/documentation/source/users/rmg/installation/dependencies.rst @@ -8,49 +8,9 @@ Dependencies List of Dependencies ==================== -Briefly, RMG depends on the following packages, almost all of which can be found in the `RMG anaconda channel `_ as binary packages. +A list of RMG's dependencies can be found in the ``environment.yml`` file on the `RMG GitHub page `_. -* **boost:** portable C++ source libraries -* **cairo:** a 2D vector graphics library with support for multiple backends including image buffers, PNG, PostScript, PDF, and SVG file output. Used for molecular diagram generation -* **cairocffi:** a set of Python bindings and object-oriented API for cairo -* **coverage:** code coverage measurement for Python -* **cython:** compiling Python modules to C for speed up -* **dde:** Data Driven Estimator for neural network thermochemistry prediction -* **ffmpeg:** (optional) used to encode videos, necessary for generating video flux diagrams -* **gaussian:** (optional) commerical software program for quantum mechanical calculations. Must be installed separately. -* **gcc:** GNU compiler collection for C,C++, and Fortran. (MinGW is used in windows) -* **gprof2dot:** converts Python profiling output to a dot graph -* **graphviz:** generating flux diagrams -* **jinja2:** Python templating language for html rendering -* **jupyter:** (optional) for using IPython notebooks -* **lpsolve:** mixed integer linear programming solver, used for resonance structure generation. Must also install Python extension. -* **markupsafe:** implements XML/HTML/XHTML markup safe strings for Python -* **matplotlib:** library for making plots -* **mock:** for unit-testing -* **mopac:** semi-empirical software package for QM calculations -* **mpmath:** for arbitrary-precision arithmetic used in Arkane -* **muq:** (optional) MIT Uncertainty Quantification library, used for global uncertainty analysis -* **networkx:** (optional) network analysis for reaction-path analysis IPython notebook -* **pytest:** advanced unit test controls -* **numpy:** fast matrix operations -* **openbabel:** chemical toolbox for speaking the many languages of chemical data -* **psutil:** system utilization diagnostic tool -* **pydas:** differential algebraic system solver -* **pydot:** interface to Dot graph language -* **pydqed:** constrained nonlinear optimization -* **pyparsing:** a general parsing module for python -* **pyrdl:** RingDecomposerLib for graph ring perception -* **pyyaml:** Python framework for YAML -* **pyzmq:** Python bindings for zeroMQ -* **quantities:** unit conversion -* **rdkit:** open-source cheminformatics toolkit -* **scipy:** fast mathematical toolkit -* **setuptools:** for packaging Python projects -* **sphinx:** documentation generation -* **symmetry:** calculating symmetry numbers of chemical point groups -* **xlwt:** generating Excel output files - .. _dependenciesRestrictions: License Restrictions on Dependencies @@ -60,7 +20,7 @@ All of RMG's dependencies except the ones listed below are freely available and * **pydas**: The DAE solvers used in the simulations come from `Linda Petzold's research group `_ at UCSB. For running sensitivity analysis in RMG, the DASPK 3.1 solver is required, which "is subject to copyright restrictions” for non-academic use. Please visit their website for more details. To run RMG without this restriction, one may switch to compiling with the DASSL solver instead in RMG, which is "available in the public domain.” -If you wish to do on-the-fly quantum chemistry calculations of thermochemistry (advisable for fused cyclic species in particular, where the ring corrections to group additive estimates are lacking), -the then you will need the third-party software for the QM calculations: +If you wish to do on-the-fly quantum chemistry calculations of thermochemistry (such as to improve estimates for fused cyclic species), +then you will need the third-party software for the QM calculations: -* **gaussian**: Gaussian03 and Gaussian09 are currently supported and commercially available. See `https://gaussian.com `_ for more details. +* **gaussian**: Gaussian16, Gaussian09 and Gaussian03 are currently supported and commercially available. See `https://gaussian.com `_ for more details. diff --git a/documentation/source/users/rmg/kinetics.rst b/documentation/source/users/rmg/kinetics.rst index 9db406463e..f13125cea9 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 @@ -111,5 +113,28 @@ average for :math:`A` is a geometric mean, while the average for :math:`n`, If there are still no "sibling" kinetics, then the groups will continue to fall up to more and more general nodes. In the worst case, the root nodes may be used. +Kinetic averaging takes into account the nodal distances (the distance between a child node and its parent). +By default, the nodal distance is 1, but custom values can be specified within a ``group.py`` file, in order of +ascending precedence: either in a list of values for each tree e.g. ``treeDistances = [1,2,5]``, +or directly assigned to an entry in the group definition e.g. ``Entry(... nodalDistance=5, )``. +This may be desired in special cases where one or more child nodes matches the family but has very different +kinetics, leading to poor overall tree estimates. + 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 0bb21b80a6..038aadb893 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 fccd09b9c3..4410d48847 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/documentation/source/users/rmg/thermo.rst b/documentation/source/users/rmg/thermo.rst index b566ed48a4..53826b8c15 100644 --- a/documentation/source/users/rmg/thermo.rst +++ b/documentation/source/users/rmg/thermo.rst @@ -154,7 +154,7 @@ On-the-fly Quantum-chemical calculation of Thermochemical Properties (QMTP) =========================================================================== An interface for performing on-the-fly quantum and force field calculations has been developed and integrated into RMG to complement the species thermochemistry databases and -group contribution methods [Magoon and Green]_. This interface is particularly interesting for the estimation of +group contribution methods [MagoonAndGreen]_. This interface is particularly interesting for the estimation of thermochemistry of molecules that are not present in one of the species thermochemistry databases, and which cannot be estimated with sufficient accuracy using the Benson group additivity framework. This pertains specifically to polycyclic fused ring containing species, whose ring strain cannot be modeled using @@ -283,7 +283,7 @@ References .. [Lay1995] Lay, T.; Bozzelli, J.; Dean, A.; Ritter, E. J. Phys. Chem. 1995, 99,14514-14527 -.. [Magoon and Green] Magoon, Gregory R., and William H. Green. "Design and implementation of a next-generation software interface for on-the-fly quantum and force field calculations in automated reaction mechanism generation." Computers & Chemical Engineering 52 (2013): 35-45. +.. [MagoonAndGreen] Magoon, Gregory R., and William H. Green. "Design and implementation of a next-generation software interface for on-the-fly quantum and force field calculations in automated reaction mechanism generation." Computers & Chemical Engineering 52 (2013): 35-45. .. [Allinger] Allinger, N. L., & Lii, J.-H. (2008). MM4(2008) and MM4(2003). diff --git a/examples/rmg/commented/input.py b/examples/rmg/commented/input.py index 91b01b2b11..6cc5173c9f 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) diff --git a/rmgpy/data/kinetics/family.py b/rmgpy/data/kinetics/family.py index 43e3836169..832e73a765 100644 --- a/rmgpy/data/kinetics/family.py +++ b/rmgpy/data/kinetics/family.py @@ -612,7 +612,7 @@ def __repr__(self): def distribute_tree_distances(self): """ - fills in nodal_distance (the distance between an entry and its parent) + Fills in nodal_distance (the distance between an entry and its parent) if not already entered with the value from tree_distances associated with the tree the entry comes from """ diff --git a/rmgpy/data/kinetics/groups.py b/rmgpy/data/kinetics/groups.py index 1616cb6d9c..256d50d4a4 100644 --- a/rmgpy/data/kinetics/groups.py +++ b/rmgpy/data/kinetics/groups.py @@ -83,7 +83,7 @@ def load_entry(self, index, label, group, kinetics, reference=None, referenceTyp Method for parsing entries in database files. Note that these argument names are retained for backward compatibility. - nodal_distance is the distance between a given entry and its parent specified by a float + nodalDistance is the distance between a given entry and its parent specified by a float """ if (group[0:3].upper() == 'OR{' or group[0:4].upper() == 'AND{' or