RMG-Py release v3.2.0

RMG-Py Version 3.2.0
====================
Date: August 2, 2023

- RMG-Py
    - Transport: Added halogens transport corrections to boiling point when estimating critical properties using group additivity
    - Updated solvation thermo GAV method to use more groups
    - Made it optional to generate_resonance_structures when loading species dicts
    - Added filter so radical/lone pair/formal charge is not added to surface site when generating resonance structures
    - Forbid surface bidentate vdW species
    - Add Transitory Edge Analysis species selection algorithm
    - Added get_react_thermo function to avoid deepcopy
    - Added decay framework for handling species RMG templates think exist, but really aren't wells
    - Added check to prevent multiple surface bonds from forming through a single adatom
    - Added multidentate adsorption correction for thermo estimation
    - Added error checks to make MOPAC calculations more robust
    - Added features to preserve atom order and template labels when generating reactions
    - Added coverage dependent effects to surface kinetics
    - Added support for halogen families in autogen tree script
    - Enabled pyrms for RMG Simulations and Edge Analysis
    - Added Liquid-Surface Reactor for RMG Electrocat
    - Added support for forbidden structures, more general than forbidden molecules
    - Removed hard-coded template matching code for Bimolec hydroperoxide decomposition
    - Added support for 2-parameter Troe reactions, only had 3-parameter Troe before
    - Included noncyclic long distance GAV correction for halogen regardless of its existence in the cycle
    - Added support for pdep networks with halogens
    - Added atom labels to molecule to_group method in order to keep the atom labels during conversion
    - Moved rmgrc to template file so user's settings won't be overwritten every pull from RMG-Py
    - Implemented two backup conformer embedding algorithms for robustness
    - Added Nitrogen groups to transport
    - Removed check for adsorbate getting adsorbed again which prevents Surface_Dissociation_to_Bidentate family
    - Modified the liquid reactor to be able to simulate as CSTR, semi-batch, and/or vapor liquid mass transfer interface
    - Added fragment code to rmgpy/molecule
    - Added PDEP improvements: simulation least squares methods and the Georgievskii et al. 2013 CSE variant to Arkane
    - Allow users to load thermo or kinetic libraries from a user-specified location
    - Add radical flux tolerance
    - Improved kH estimation code for solute
    - Allow irreversible PDEP reactions by setting Keq=inf
    - only calculate frequency and x in get_partition_function if semiclassical correction is needed
    - Implemented deadend radical species selection algorithm
    - Enable Metal, Facet, site and terrace specification in Molecule
    - Increase species label max length for chemkin to avoid S(14567) style species
    - Don't replace PDep kinetics of a library reaction
    - Added solvation to surfaces
    - Added some charge transfer reactions
    - Added lithium

- Auto Generated Trees
    - Enabled estimator to ascend autogenerated rate tree if uncertainty is too high in a lower node
    - Made some major improvements to automated tree extension generation and the cascade algorithm
    - Added support for quadruple bonds in auto tree generation
    - Added binding energies for N-S and C#S
    - Removed hard-coded special treatment for Peroxyl Disproportionation family during template matching
    - Increased ArrheniusBM fitting temperature upper limit to 2000K for RMG-database rate trees
    - Skipped number of products check for ATG tree generation of Intra_R_Add_Endocyclic and Intra_R_Add_Exocyclic

- RMS
    - Add Transitory Edge Analysis
    - Added surface reactions to RMS yaml format
    - Updated developer installation instructions to use main RMS branch
    - Add comment as input to to_rms() function
    - Change RMS to use keyword variables to avoid twin PR with RMG whenever RMG changes struct

- Arkane
    - Added check for convergence and other common errors in QM parsers
    - Updated the documentation that tabulates which levels of theory are supported by Arkane
    - Read actual scan angles for rotor calculations
    - Corrected Fourier fitting in torsion.pyx
    - Added Psi4 ESS adapter to Arkane
    - Added commit strings for RMG-Py and RMG-database to Arkane logs
    - Added BAC confidence interval estimates to Arkane logs
    - Added leave-one-out cross-validation for evaluating BAC fits
    - Enabled parsing of scan log files with linear bend (something like L 1 2 3 B)
    - Enabled assignment of PES (angles vs energies) directly in the Arkane input file
    - Added a readme file for Arkane
    - Updated QChem parser to only return the negative frequency from the last frequency block instead of the first
    - Added more unit tests
    - Save meaningful reaction label for PDEP reactions when creating RMG library
    - Added more examples
    - Added Arkane citation info: https://doi.org/10.1002/kin.21637, https://doi.org/10.1021/acs.jcim.2c00965
    - Allow RMG to read Arkane YAML files through the RMGObject even if they have mol or aux keywords

- Bugfixes
    - Added check for multiplicity of reverse products if the family template reactants have multiplicity constraints
    - Added check for vdW multiplicity constraints in forward direction
    - Added check to see that empty surface site template group only matches empty surface site structure (and not vdW species with empty site)
    - Fixed regex bug in checking multiplicity of adjacency list
    - Fixed bug where RMG can output mechanisms in which two species have the same name
    - Added QM fallback to ML or GAV in case of bad conformer ID error from rdkit
    - Fixed many broken links in documentation
    - Fixed species missing metal attribute error
    - Fixed some automated tree generation parallelization bugs
    - Changed tree generation get_training_set method to use deepcopy to clear atom labels and to parse out the metal from the entry
    - Added a save_order attribute to some methods to preserve atom order in cases that need it
    - Fixed load chemkin function to allow extended elements and species that start with digits
    - Handle string data properly when averaging children solute
    - Fixed bug in get_w0 where a_dict didn't match the molecule because it was made before the molecule was deepcopied
    - Added check for pdep net reactions when removing species to prevent forbidden species from ending up in net reactions
    - Fixed bug where add_atom_labels_for_reaction mislabels reactants if family is its own reverse
    - Fixed bug where save_training_reactions occasionally mixes up atom labels
    - Added Ctc atom type to prevent RMG from crashing when trying to make [C+]#[C-] molecule, which was then added to the forbidden structures
    - Fixed bug where generate_resonance_structure does not preserve atom when keep_isomorphic=False and save_order=True
    - Fixed bugs related to RMS object construction, particularly Multi/Pdep/Arrhenius and falloff
    - Added check to always draw CO as 'CO' instead of 'OC'
    - Converted ThermoData object to a NASA object for compatibility with RMS
    - Corrected pyrms core/edge species/reaction handling for phase systems
    - Fixed incorrect reading in load_chemkin_file for surface species with site density specified
    - Added properties so group can be pickled without losing important information like ring membership
    - Fixed bug where atom map changes even if save_order=True
    - PDEP networks update before writing/filtering to avoid differences in barrier energy corrections between networks
    - Check for debug mode so rms can be imported in debug mode
    - Fixed group property has_wildcards to avoid AttributeError
    - Fixed several calls missing the 'r' at the start of regex pattern string
    - Fixed Fragment count_internal_rotors and is_atom_in_cycle attribute errors
    - Added missing term in Troe kinetics formula
    - Fixed some broken links in documentation
    - Change cython variables from cpdef to cdef to avoid warnings
    - Updated load_transport_file to skip any species in the transport file that's not in the species dictionary instead of crashing
    - Fixed CI error "Unable to dlopen(cxxpath) in parent! cannot open shared object file: File name too long"

- Testing
    - Updated reference number of reactions for Arkane test_reactions unit test
    - Changed molecule for rmgpy/data/thermoTest.py test_identifying_missing_group test because group is no longer missing
    - Added continuous integration test for links in documentation
    - Changed kinetics database tests to look for auto_generated tag instead of the hardcoded family list
    - Updated rmg test data with new 2+2 cycloaddition species and reactions
    - Remove cti file generation from regression tests to avoid Cantera IO error
    - Added tests to check number of reactants and products defined in ATG rate rules
    - CI is now done with mamba to drastically reduce runtime
    - Move regression testing into main CI.yaml
    - Simplify condition checking for scheduled vs pushed CI
    - Remove redundant step creating stable_regression_results dir for running on a schedule or push to main because it already is the stable result
    - Update CI.yml to allow CI tests on forks
    - Added "phony" target so make test will always remake when run (instead of checking whether the test folder is up to date)
    - Add a unit test to make a sample molecule for every atom type
    - Update CI.yml and environment.yml to allow CI to run on MacOS
    - Add regression testing for RMS's CSTR and constant V ideal gas reactors
    - Bugfix on CI documentation testing so errors are reported as failures
    - Relax tolerance on HinderedRotor.get_enthalpy() test to accomodate slightly different answer likely due to numerical issues
    - Regression tests report failure if a model changes significantly
    - Allow CI testing to be called from other repos
    - Regression tests pass by default and the user must look at the report to see details of comparison
    - Generate summary of regression test results to be displayed on annotation of PR results

- Miscellaneous
    - Added Docker install
    - Added check to only publish documentation documentation from RMG official fork
    - Fixed RMG-Py 3.1.0 release note bullet formatting
    - Changed installation instructions for WSL users to install graphviz system wide to include all dependencies
    - Changed get_all_solute_data function for RMG-website use in order to apply halogen or radical correction on top of library or GAV
    - Added openSUSE installation instructions
    - Changed default branch to main
    - Changed rmg.py shebang to use python-jl instead of python3 for compatibility with RMS/pyrms
    - Updated ketoenol template image to 1,3 sigmatropic rearrangement
    - Updated 2+2_cycloaddition images in documentation
    - Added licensing information to the README file
    - Updated installation instructions with main instead of master branch, latest Anaconda link, and ssh instead of https clone from github
    - Added support for Sticking Reactions in HTML reports
    - Added reminder in documentation to activate rmg_env before making tests
    - Check that family tree is not autogenerated before calling add_rules_from_training and fill_rules_by_averaging_up
    - Added warning to not to call add_rules_from_training and fill_rules_by_averaging_up on ATG trees, and return statement before error
    - Replaced BurkeH2O2 library with PrimaryH2O2 in relevant RMG examples
    - Added instructions to Documentation for fixing libmkl_ts.so.2 ImportError
    - Added new RMG-database paper to cite https://pubs.acs.org/doi/10.1021/acs.jcim.2c00965
    - Added .bib file for easy citation
    - Updated RMG-Py install instructions to remove old Julia instructions and to use mamba solver
    - Use conda-forge ncurses for compatibility with docker
    - Use conda-forge pyjulia instead of customized RMG channel version for better standardization
    - Update Cantera version requirement to 2.6
    - Upgrade to OpenMOPAC to fix license issues
    - Updated list of developers
    - Added Jupyter Notebook example for simulating and analyzing superminimal model
    - Robot automatically marks issues and PR's as stale after 90 days of inactivity and closes them after 30 more days of inactivity

Co-authored-by: Sevy Harris <harris.se@northeastern.edu>
Co-authored-by: Richard West <r.west@northeastern.edu>

Author: rwest

.conda/meta.yaml

@@ -1,7 +1,7 @@
 # For conda build
 package:
   name: rmg
-  version: 3.1.0
+  version: 3.2.0
 
 source:
   path: ../
@@ -64,7 +64,7 @@ requirements:
     - pyzmq
     - quantities
     - rdkit >=2018
-    - rmgdatabase >=3.1.0
+    - rmgdatabase >=3.2.0
     - scikit-learn
     - scipy
     - symmetry
@@ -84,6 +84,6 @@ test:
     - python %SCRIPTS\Arkane.py examples\arkane\networks\n-butanol\input.py # [win]
 
 about:
-  home: http://github.com/ReactionMechanismGenerator/RMG-Py
+  home: https://github.com/ReactionMechanismGenerator/RMG-Py
   license: MIT
   summary: "A program for automatically generating kinetic models of chemical reaction mechanisms."

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,5 +22,5 @@ Checklist before submission:
  - Is your code commented and understandable?
  - Have you updated related documentation?
  - Are the commits logically organized and informative?
- - Is your branch up to date with master?
+ - Is your branch up to date with main?
 -->

.github/workflows/CI.yml

@@ -0,0 +1,63 @@
+name: Annotate pull request with regression summaries
+# Takes a regression summary from a workflow run and annotates the pull request with it
+# The pull request number is taken from the first line of the summary.txt file.
+# The summary file is in an artifact called regression_summary associated
+# with the workflow run that triggered this workflow.
+# based on https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow
+
+on:
+  workflow_run:
+    workflows:
+      - Continuous Integration
+    types:
+      - completed
+
+run-name: Annotate PR ${{ github.event.workflow_run.event.display_title }}.
+
+jobs:
+  on-success:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request' }}
+    steps:
+      - run: echo 'The triggering workflow passed'
+      - name: 'Download regression_summary artifact'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: context.payload.workflow_run.id,
+            });
+            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "regression_summary"
+            })[0];
+            let download = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifact.id,
+              archive_format: 'zip',
+            });
+            let fs = require('fs');
+            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/regression_summary.zip`, Buffer.from(download.data));
+
+      - name: 'Unzip artifact'
+        run: unzip regression_summary.zip
+
+      - name: 'Get pull request number'
+        run: |
+          echo "PR_NUMBER=$( head -n 1 summary.txt )" >> $GITHUB_ENV
+          # remove the first line from the file
+          sed -i '1d' summary.txt
+
+      - name: Write summary to pull request as a comment
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          filePath: summary.txt
+          pr_number: ${{ env.PR_NUMBER }}
+
+      - name: Report the github.event.workflow_run as json
+        if: ${{ failure() }}
+        run: echo $JSON
+        env:
+          JSON: ${{ toJson(github.event.workflow_run) }}

.github/workflows/annotate.yml

@@ -3,7 +3,8 @@ name: Build Documentation
 on:
   push:
     branches:
-      - master
+      - main
+  pull_request:
 
 jobs:
   build-documentation:
@@ -15,31 +16,61 @@ jobs:
         shell: bash -l {0}
     steps:
       - uses: actions/checkout@v2
-      - uses: conda-incubator/setup-miniconda@v2
+      - name: Patch the environment file
+        run: |
+          echo -e "\n  - libstdcxx-ng < 13\n" >> environment.yml
+          cat environment.yml
+      - name: Setup Mambaforge Python 3.7
+        uses: conda-incubator/setup-miniconda@v2
         with:
           environment-file: environment.yml
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
           python-version: 3.7
           activate-environment: rmg_env
+          use-mamba: true
       - name: Install sphinx
-        run: conda install -y sphinx
-      - name: Conda info
+        run: mamba install -y sphinx
+      - name: Mamba info
+        run: |
+          mamba info
+          mamba list
+      - name: Install and link Julia dependencies 
         run: |
-          conda info
-          conda list
+          julia -e "using Pkg; Pkg.add(PackageSpec(url=\"https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl\", rev=\"main\"))"
+          julia -e "using Pkg; Pkg.add(\"PyCall\"); Pkg.add(\"DifferentialEquations\")"
+          python -c "import julia; julia.install()"
       - name: Install and compile RMG
         run: |
           cd ..
           git clone https://github.com/ReactionMechanismGenerator/RMG-database.git
           cd RMG-Py
           sed -i '/embedsignature/s/# //g' setup.py
           make
-      - name: Make documentation
+      - name: Make documentation - for testing
+        if: ${{  github.event_name != 'push' || github.repository != 'ReactionMechanismGenerator/RMG-Py' }}
+        run: |
+          cd documentation
+          sphinx-build -b html -d build/doctrees/ source/ build/html -w errors.log -W --keep-going
+      - name: Report documentation errors
+        if: ${{ failure() }}
+        run: |
+          cat documentation/errors.log
+      - name: Make documentation - to publish
+        if: ${{  github.event_name == 'push' && github.repository == 'ReactionMechanismGenerator/RMG-Py' }}
         env:
             GH_TOKEN: ${{ secrets.RMG_DEV_TOKEN }}
         run: |
           make -C documentation continous_integration_setup clean html
+      - name: Check documentation links
+        continue-on-error: true
+        run: |
+          cd documentation
+          sphinx-build -b linkcheck -d build/doctrees/ source/ build/linkcheck | grep -e broken -e redirect | grep -v -e 'redirect  https://doi.org/' -e 'broken    https://doi.org/.* 403 Client Error: Forbidden'
       - name: Publish documentation
+        if: ${{  github.event_name == 'push' && github.repository == 'ReactionMechanismGenerator/RMG-Py' }}
         env:
+            GH_TOKEN: ${{ secrets.RMG_DEV_TOKEN }}
             COMMITMESSAGE: "Automatic documentation rebuild"
             GIT_AUTHOR_NAME: "RMG Bot"
             GIT_AUTHOR_EMAIL: "rmg_dev@mit.edu"

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Stale Issues and Pull Requests
+
+permissions:
+  issues: write
+  pull-requests: write
+
+on:
+  schedule:
+    - cron: "0 8 * * *"
+  workflow_dispatch:
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Stale Issues and Pull Requests
+        uses: actions/stale@main
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          stale-issue-message: 'This issue is being automatically marked as stale because it has not received any interaction in the last 90 days. Please leave a comment if this is still a relevant issue, otherwise it will automatically be closed in 30 days.'
+          stale-pr-message: 'This pull request is being automatically marked as stale because it has not received any interaction in the last 90 days. Please leave a comment if this is still a relevant pull request, otherwise it will automatically be closed in 30 days.'
+          days-before-stale: 90
+          days-before-close: 30
+          stale-issue-label: stale
+          stale-pr-label: stale
+          operations-per-run: 1000
+          exempt-issue-labels: bug
+          exempt-pr-labels: bug
+          close-issue-label: abandoned
+          close-pr-label: abandoned

.github/workflows/stale.yml

@@ -15,7 +15,7 @@
 # Image files generated by RMG
 *.png
 *.svg
-*.pdf 
+*.pdf
 
 # Temporary build files
 build/*
@@ -30,6 +30,7 @@ make.inc
 # Example output files
 examples/*
 !examples/*/input.py
+!examples/**/*.ipynb
 
 # NetBeans project files
 nbproject/*
@@ -40,9 +41,11 @@ nbproject/*
 .settings/*
 
 # PyCharm project files
+*/.idea/*
 .idea/*
 
 # VS Code settings
+*/.vscode/*
 .vscode/*
 
 # Unit test files
@@ -78,3 +81,18 @@ external/Q2DTor
 
 # egg files (pip install -e)
 RMG_Py.egg-info/*
+
+# deleted files
+**/.fuse_hidden*
+
+# RMG configuration file
+rmgpy/rmgrc
+
+scripts/treegen.log
+
+scripts/treegen_backup.log
+
+# regression testing files - ignore everything but input and regression input
+test/regression/*
+!test/regression/*/input.py
+!test/regression/*/regression_input.py

.gitignore

@@ -4,7 +4,7 @@
 #                                                                             #
 # RMG - Reaction Mechanism Generator                                          #
 #                                                                             #
-# Copyright (c) 2002-2021 Prof. William H. Green (whgreen@mit.edu),           #
+# Copyright (c) 2002-2023 Prof. William H. Green (whgreen@mit.edu),           #
 # Prof. Richard H. West (r.west@neu.edu) and the RMG Team (rmg_dev@mit.edu)   #
 #                                                                             #
 # Permission is hereby granted, free of charge, to any person obtaining a     #

.travis.yml

@@ -0,0 +1,44 @@
+@article{RMG,
+title = {{Reaction Mechanism Generator: Automatic construction of chemical kinetic mechanisms}},
+journal = {Computer Physics Communications},
+volume = {203},
+pages = {212-225},
+year = {2016},
+issn = {0010-4655},
+doi = {https://doi.org/10.1016/j.cpc.2016.02.013},
+url = {https://www.sciencedirect.com/science/article/pii/S0010465516300285},
+author = {Connie W. Gao and Joshua W. Allen and William H. Green and Richard H. West},
+}
+
+@article{RMG3,
+author = {Liu, Mengjie and Grinberg Dana, Alon and Johnson, Matthew S. and Goldman, Mark J. and Jocher, Agnes and Payne, A. Mark and Grambow, Colin A. and Han, Kehang and Yee, Nathan W. and Mazeau, Emily J. and Blondal, Katrin and West, Richard H. and Goldsmith, C. Franklin and Green, William H.},
+title = {{Reaction Mechanism Generator v3.0: Advances in Automatic Mechanism Generation}},
+journal = {Journal of Chemical Information and Modeling},
+volume = {61},
+number = {6},
+pages = {2686-2696},
+year = {2021},
+doi = {10.1021/acs.jcim.0c01480},
+}
+
+@article{RMG_Database,
+author = {Johnson, Matthew S. and Dong, Xiaorui and Grinberg Dana, Alon and Chung, Yunsie and Farina, David Jr. and Gillis, Ryan J. and Liu, Mengjie and Yee, Nathan W. and Blondal, Katrin and Mazeau, Emily and Grambow, Colin A. and Payne, A. Mark and Spiekermann, Kevin A. and Pang, Hao-Wei and Goldsmith, C. Franklin and West, Richard H. and Green, William H.},
+title = {RMG Database for Chemical Property Prediction},
+journal = {Journal of Chemical Information and Modeling},
+volume = {62},
+number = {20},
+pages = {4906-4915},
+year = {2022},
+doi = {10.1021/acs.jcim.2c00965},
+}
+
+@article{Arkane,
+author = {Dana, Alon Grinberg and Johnson, Matthew S. and Allen, Joshua W. and Sharma, Sandeep and Raman, Sumathy and Liu, Mengjie and Gao, Connie W. and Grambow, Colin A. and Goldman, Mark J. and Ranasinghe, Duminda S. and Gillis, Ryan J. and Payne, A. Mark and Li, Yi-Pei and Dong, Xiaorui and Spiekermann, Kevin A. and Wu, Haoyang and Dames, Enoch E. and Buras, Zachary J. and Vandewiele, Nick M. and Yee, Nathan W. and Merchant, Shamel S. and Buesser, Beat and Class, Caleb A. and Goldsmith, Franklin and West, Richard H. and Green, William H.},
+title = {{Automated reaction kinetics and network exploration (Arkane): A statistical mechanics, thermodynamics, transition state theory, and master equation software}},
+journal = {International Journal of Chemical Kinetics},
+volume = {55},
+number = {6},
+pages = {300-323},
+doi = {https://doi.org/10.1002/kin.21637},
+year = {2023}
+}