RMG-Py: generating chemical reaction mechanisms from thermodynamics and rate data

Two tools in one repository: mechanism generation and Arkane

RMG-Py contains the Python version of Reaction Mechanism Generator, a tool for automatically generating chemical reaction mechanisms for modelling reaction systems including pyrolysis, combustion, atmospheric science and more.

The second half of the repository is Arkane, the package for calculating thermodynamics, high-pressure-limit rate coefficients and pressure dependent rate coefficients from quantum chemical calculations. That is a distinct job from mechanism generation, and it is the piece most people who use quantum chemistry would recognise. Arkane is compatible with a variety of ab initio quantum chemistry software programs: Gaussian, Q-Chem, Molpro, Orca, Psi4 and TeraChem.

The split matters for how you evaluate the project. RMG itself consumes thermochemistry and kinetics; Arkane produces them from quantum chemistry output. A workflow that starts from a DFT calculation goes through Arkane to get the numbers, and then those numbers feed the mechanism generation. People often need only one of the two.

The repository layout supports that separation. There is a top level rmg.py and Arkane.py, an rmgpy/ package and an arkane/ package, separate example directories under examples/rmg/ and examples/arkane/, a scripts/ directory, a documentation/ directory, an ipython/ directory, and a test/ directory with a pytest.ini. There is also an environment.yml for conda, a setup.py, a Makefile, an install_rms.sh script and a Dockerfile, so the project supports both a conda workflow and a containerised one.

Two related repositories are named separately. The RMG-database repository holds the source code for the latest version of the database, and the Dockerfile clones it alongside RMG-Py itself, with an RMS branch as well. The database is not a minor detail here, it is the substrate the generator reasons over.

What the generation actually does

The readme does not give a step by step walkthrough of the algorithm, which is a real gap for anyone trying to understand the mechanism from the documentation alone. What it does state is the scope and the inputs.

RMG generates mechanisms for reaction systems including pyrolysis, combustion and atmospheric science. The input is a set of species, and the output is a reaction mechanism connecting them, built by applying rules to grow the network until the species either appear or the search is exhausted.

That description is a summary of the published method rather than the readme, so it is worth being clear about what is documented and what is not. The documentation site linked from the readme covers installation, the user guide for RMG and for Arkane, and a separate API reference, and there is a PDF of the combined documentation. The mechanism generation details live in those documents and in the cited papers, not in the repository readme.

What the readme does give is the academic framing and the publication trail. The credits go to Professor William H. Green's research group at the Massachusetts Institute of Technology and to Professor Richard H. West's research group at Northeastern University. The readme asks users to cite the latest publication on Reaction Mechanism Generator v3.0 and other relevant publications when publishing results using the software, and lists three specific citations, starting with the 2016 Computer Physics Communications paper on automatic construction of chemical kinetic mechanisms, followed by the 2021 Journal of Chemical Information and Modeling paper on RMG v3.0, and then the 2022 paper on the RMG database for chemical property prediction.

That citation request is a useful signal about the maturity of the tool. A mechanism generator that has been the subject of successive peer reviewed papers, with a dedicated paper for the database itself, is a different kind of artifact from a research script.

Installing through conda or from source

The readme gives two routes and defers the detail to a documentation page.

You can either download the source from GitHub and compile it yourself, or download the binaries from Anaconda. The detailed instructions live on the Download and Install page of the documentation site, and the repository carries a conda badge pointing at the rmg package on Anaconda.

The Anaconda route is the one most users will take, and the reason is visible in the Dockerfile. The base image is condaforge/miniforge3, and the project also depends on Julia, which is installed in the container through juliaup rather than through conda.

# Parent Image
FROM condaforge/miniforge3:latest

# Install Bash shell
RUN ln -snf /bin/bash /bin/sh

The system dependencies are installed with apt and the Dockerfile comments explain why each one is needed. make, gcc and g++ are for building RMG, git is for downloading the RMG repositories, wget is for downloading the conda install script, libxrender1 is required by RDKit, and ca-certificates is added for HTTPS downloads.

The Julia install is the most interesting part of the file, because of the reason given.

RUN wget -qO- https://install.julialang.org | sh -s -- --yes --default-channel 1.10.11 && \
    /root/.juliaup/bin/juliaup add 1.10.11 && \
    /root/.juliaup/bin/juliaup default 1.10.11 && \
    /root/.juliaup/bin/juliaup list && \
    rm -rf /root/.juliaup/downloads /root/.juliaup/tmp
ENV PATH="/root/.juliaup/bin:$PATH"

The comment above it explains the pin: Julia is pinned to a patch version rather than the 1.10 channel, because juliacall segfaults on import under 1.10.12, and the channel floats to the newest patch. That is a concrete, reproducible failure mode, and it is documented in the build file rather than left for a user to hit.

The container also sets build arguments for the three branches it needs, defaulting to main for RMG-Py and RMG-database and for_rmg for RMS, with the note that they can be overridden at build time or in the continuous integration CI file.

The Makefile treats the install as a stateful step

The Makefile is worth reading because it reveals that installing this project is not a single command, and the build system treats it as a state to be tracked.

The key idea is a sentinel file. The comment says it is a sentinel file written after a successful pip editable install, that it lives in the source tree, and that it is deleted by make clean.

INSTALL_SENTINEL = .installed

# Default target: ensure installed, then build any changed extensions in place.
all: check $(INSTALL_SENTINEL) build check

The default target therefore runs the dependency check, ensures the install has happened, builds the changed extensions in place, and checks again. The install only runs if the sentinel does not exist, which is what the comment on that rule says.

The install itself is a macro, and the check inside it is not optional.

define DO_INSTALL
	@ python utilities.py check-pydas
	python -m pip install --no-build-isolation -vv -e .
	@ touch $(INSTALL_SENTINEL)
endef

The check step is a separate target that runs two utility commands, one to check dependencies and one to check pydas, and the same pydas check runs at the start of the install. The build target then does an incremental in place extension build with setup.py and skips pip entirely.

There is a clean target that runs the clean utility, uninstalls the reactionmechanismgenerator package with pip, ignoring the failure if the package was not installed, and removes the sentinel file. A separate clean-solver target exists, and a q2dtor target that installs Q2DTor, the software for calculating partition functions and thermodynamic properties of molecular systems with two or more torsional modes, which Arkane can integrate to compute the quantum mechanical partition function of two dimensional rotors.

The build arguments in the Makefile set CC to gcc and CXX to g++, and the phony target list includes all, build, check, clean, install, decython, documentation, test and q2dtor.

The interactive site, the database and the documentation split

Three separate resources sit alongside the code, and each serves a different need.

The interactive website at rmg.mit.edu is described as a place to visualise RMG-generated models, view the databases, and perform thermodynamics and kinetics searches. That is a significant piece of the offering. Being able to browse the database in a browser rather than only querying it from a Python session changes how you explore what the tool knows, and how you check whether your species of interest is covered before you start a generation run.

The documentation is extensive and comes in two forms. There is a documentation site with separate user guides for RMG and for Arkane, plus an API reference, and there is a PDF version of the combined documentation and of the API reference hosted in the repository. For a scientific tool whose API surface is large, having a browsable API reference is what makes it usable by someone who is not its author.

The database has its own repository and its own publication, and the readme asks that the database paper be cited along with the mechanism generation papers when RMG-database is used. The database is a first class research output here, not a data dump.

Feedback routes are conventional and reasonable. Issues go on the GitHub issues page or by email to [email protected]. Contributions follow a CONTRIBUTING.md in the repository, and the top level also holds a CODE_OF_CONDUCT.md, a CITATIONS.bib and a CLAUDE.md file.

The resource list on the RMG website collects the relevant publications. The readme asks people to cite the latest publication on Reaction Mechanism Generator v3.0 and other relevant publications when publishing results using the software, which in practice means three specific references covering the 2016 method paper, the 2021 v3.0 advances paper and the 2022 database paper.

Where the limitations sit

The honest limitations here are about scope and about what you can check yourself.

First, the mechanism is only as good as the database. The generator works from published thermochemistry and kinetics held in the RMG database, and a species that is not in that database either cannot be used or has to be added with data you supply yourself. The database has a paper describing it for chemical property prediction, and a separate RMG-database repository holds the source code for the latest version, which tells you the data is versioned software rather than a static artefact.

Second, the documentation gap I noted earlier is real for the algorithm. The repository readme describes scope, installation routes, documentation links and citations, and it does not describe the generation algorithm itself. A reader has to go to the user guide or the papers. For a research tool maintained by a research group, that is a normal arrangement, but it means evaluating the method means reading the publications, not the repository.

Third, the dependency surface is large and includes a compiled extension. The Makefile checks dependencies and pydas, builds extensions in place, and the container needs gcc, g++, make, RDKit with libxrender1, and a pinned Julia with a Python bridge. The Julia pin is worth dwelling on as a class of problem: the comment records that juliacall segfaults on import under a specific patch release, and the build works around it by pinning exactly. If you are running this outside the container, that same failure can appear at import time, and the workaround is to match the pin.

Fourth, and most simply, a generated mechanism is a hypothesis, not a measurement. The tool builds a network that is consistent with the data and the rules, and validating it against experimental ignition delays or species profiles is the researcher's job. The package gives you the mechanism; it does not tell you it is right.

On alternatives, the difference in approach between this and a commercial kinetic modelling package is ownership of the data and the rules. A commercial tool gives you a maintained database and a supported workflow, and you accept the vendor's black box for how a mechanism is assembled. RMG-Py gives you the source of the generation code and the database as a separate repository you can read, fork and extend, and you take on the work of building and validating the database yourself if you need to add chemistry. For a research group publishing mechanisms and needing to justify every rule, that trade usually favours the open route. For an engineer who needs a working mechanism for a fuel next quarter and does not want to own the data, the vendor route is often the cheaper one.

Editorial conclusion

RMG-Py suits a combustion or atmospheric chemistry researcher who needs a defensible mechanism built from published thermochemistry and kinetics, and a student who wants to read how mechanism generation actually works, since the source is open and the database is inspectable. It does not suit an engineer who needs a mechanism for a specific fuel outside the shipped database, because generation is limited to what the database contains. Before you rely on a generated mechanism, check the database version and cite the required papers, since the readme asks that the v3.0 publication and the database publication be cited alongside any results, and note that the container build pins Julia to a specific patch version because of a segfault in a later one.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. ReactionMechanismGenerator/RMG-Py on GitHub
4. README
5. Releases