Adding Regression Tests

Introduction

This tutorial explains how to add a new regression test to the Continuous Integration (CI).

Input file creation

Create an RMG-Py simulation input file, and name it input.py. An example is shown below in Appendix A. Ensure that the option saveEdgeSpecies flag in the options section is set to True so that the edge model will also be saved to a file.

What is even more important: We appreciate if you would create a simulation case with several features of RMG-Py, e.g. pressure-dependence, QMTP, operating conditions, initial mixtures, pruning, seed mechanisms, reaction libraries, thermo libraries, species constraints, liquid phase cases, output options, etc… The more diverse our global test set of simulations becomes, the more ground we will cover of RMG-Py’s code.

RMG-Py reaction mechanism generation

With the created RMG-Py simulation input file, generate the reaction mechanism that corresponds to the created 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. Ensure that you are using the correct versions of RMG-Py (v 1.0.3) and RMG-database (v 1.0.2) to generate the reaction mechanism. Appendix B explains how you can check this. Once the RMG-Py simulation is finished, you need to keep a number of files. Retain the RMG.log file in the current working directory, and search for the core and edge reaction mechanism and their respective species dictionaries in the chemkin subfolder. Look for the following filenames:

• chem_annotated.inp
• species_dictionary.txt
• chem_edge_annotated.inp
• species_edge_dictionary.txt Save the five files for later use.

Fork and clone the RMG-tests repository and create a new branch

Fork the ReactionMechanismGenerator/RMG-tests repository to your own user account by pushing the “fork” button on the https://github.com/ReactionMechanismGenerator/RMG-tests page.

Clone your newly forked version of RMG-tests to your local computer: git clone https://github.com/<your user name>/RMG-tests.git

Enter the newly created RMG-tests folder, and create a new branch and give it an appropriate branch name (in this example: “octane”):

cd RMG-tests/
git checkout –b octane

Adding the newly created RMG simulation files

In the test/regression folder, create a new folder, give it the same name as the chosen branch name (in this example: “octane”), and copy the RMG-Py simulation input file in this folder.

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.

Updating git, and pushing the newly created branch to your online repository

Stage and commit the added/updated files through git. Provide a short summary message when committing:

git add .
git commit

A text editor will pop up. Provide a summary message that explains what type of simulation is added in the commit. Save and exit the text editor. git push origin octane

Now your changes in the newly created branch will be available on your own forked version of RMG-tests.

Create a pull request that proposes to merge your additions into the main version and push the “Create Pull Request” button.

Appendix A: RMG-Py simulation input file

# Data sources
database(
    thermoLibraries = ['primaryThermoLibrary'],
    reactionLibraries = [],
    seedMechanisms = [],
    kineticsDepositories = ['training'], 
    kineticsFamilies = 'default',
    kineticsEstimator = 'rate rules',
)

# Constraints on generated species
generatedSpeciesConstraints(
    maximumCarbonAtoms = 8,
)

# List of species
species(
    label='n-octane',
    reactive=True,
    structure=SMILES("CCCCCCCC"),
)

species(
    label='Ar',
    reactive=False,
    structure=SMILES("[Ar]"),
)

simpleReactor(
    temperature=(1500,'K'),
    pressure=(400,'Pa'),
    initialMoleFractions={
        "n-octane": 0.02,
        "Ar": 0.98,
    },
    terminationConversion={
        'n-octane': 0.5,
    },
    terminationTime=(1e0,'s'),
)

simulator(
    atol=1e-16,
    rtol=1e-8,
)

model(
    toleranceKeepInEdge=0.0,
    toleranceMoveToCore=0.5,
    maximumEdgeSpecies=100000
)

pressureDependence(
    method='modified strong collision',
    maximumGrainSize=(0.5,'kcal/mol'),
    minimumNumberOfGrains=250,
    temperatures=(300,3000,'K',8),
    pressures=(0.001,100,'bar',5),
    interpolation=('Chebyshev', 6, 4),
)

options(
    units='si',
    generateOutputHTML=False,
    generatePlots=False,
    saveEdgeSpecies=True,
)