# 5. Example Input Files¶

Perhaps the best way to learn the input file syntax is by example. To that end, a number of example input files and their corresponding output have been given in the examples directory. Two of the RMG jobs are shown below.

## 5.1. Ethane pyrolysis (Minimal)¶

This is the minimal example file characterizing a very basic system for ethane pyrolysis and should run quickly if RMG is set up properly. It does not include any calculation of pressure-dependent reaction rates.

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

# List of species
species(
label='ethane',
reactive=True,
structure=SMILES("CC"),
)

# Reaction systems
simpleReactor(
temperature=(1350,'K'),
pressure=(1.0,'bar'),
initialMoleFractions={
"ethane": 1.0,
},
terminationConversion={
'ethane': 0.9,
},
terminationTime=(1e6,'s'),
)

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

model(
toleranceKeepInEdge=0.0,
toleranceMoveToCore=0.1,
toleranceInterruptSimulation=0.1,
maximumEdgeSpecies=100000,
)

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


This example models the pyrolysis of 1,3-hexadiene and demonstrates the effect of turning on the pressure-dependence module within RMG.

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

# Constraints on generated species
generatedSpeciesConstraints(
)

# List of species
species(
label='HXD13',
reactive=True,
structure=SMILES("C=CC=CCC"),
)
species(
label='CH4',
reactive=True,
structure=SMILES("C"),
)
species(
label='H2',
reactive=True,
"""
1 H u0 p0 {2,S}
2 H u0 p0 {1,S}
"""),
)
species(
label='N2',
reactive=False,
structure=InChI("InChI=1/N2/c1-2"),
)

# Reaction systems
simpleReactor(
temperature=(1350,'K'),
pressure=(1.0,'bar'),
initialMoleFractions={
"HXD13": 6.829e-4,
"CH4": 0.104,
"H2": 0.0156,
"N2": 0.8797,
},
terminationConversion={
'HXD13': 0.9,
},
terminationTime=(1e0,'s'),
)

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

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

quantumMechanics(
software='mopac',
method='pm3',
# fileStore='QMfiles', # relative to where it is run. Defaults within the output folder.
scratchDirectory = None, # not currently used
onlyCyclics = True,
)

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

options(
units='si',
saveRestartPeriod=(1,'hour'),
generateOutputHTML=False,
generatePlots=False,
)


## 5.3. Commented input file¶

This is a fully commented input file with all optional blocks for new users to better understand the options of rmg input files

# Data sources
database(
#overrides RMG thermo calculation of RMG with these values.
#libraries found at http://rmg.mit.edu/database/thermo/libraries/
#if species exist in multiple libraries, the earlier libraries overwrite the
#previous values
thermoLibraries = ['KlippensteinH2O2','primaryThermoLibrary','DFT_QCI_thermo','CBS_QB3_1dHR'],
#overrides RMG kinetics estimation if needed in the core of RMG.
#list of libraries found at http://rmg.mit.edu/database/kinetics/libraries/
#input each library as a ('library_name',True/False) where a True means that all
#unused reactions will be automatically added to the chemkin file
reactionLibraries = [],
#seed mechanisms are reactionLibraries that are forced into the initial mechanism
#in addition to species listed in this input file.
#This is helpful for reducing run time for species you know will appear in
#the mechanism.
seedMechanisms = ['KlippensteinH2O2','ERC-FoundationFuelv0.9'],
#this is normally not changed in general RMG runs.  Usually used for testing with
#outside kinetics databases
kineticsDepositories = 'default',
#lists specific families used to generate the model. 'default' uses a list of
#families from RMG-Database/input/families/recommended.py
#a visual list of families is available in PDF form at RMG-database/families
kineticsFamilies = 'default',
#specifies how RMG calculates rates.  currently, the only option is 'rate rules'
kineticsEstimator = 'rate rules',
)

# List of species
#list initial and expected species below to automatically put them into the core mechanism.
#'structure' can utilize method of SMILES("put_SMILES_here"),
#for molecular oxygen, use the smiles string [O][O] so the triplet form is used
species(
label='butane',
reactive=True,		#this parameter is optional if true
structure=SMILES("CCCC"),
)
species(
label='O2',
structure=SMILES("[O][O]"),
)
species(
label='N2',
reactive=False,
1 N u0 p1 c0 {2,T}
2 N u0 p1 c0 {1,T}
"""),
)
# You can list species not initially in reactor to make sure RMG includes them in the mechanism
species(
label='QOOH',
reactive=True,
structure=SMILES("OOCC[CH]C")
)
species(
label='CO2',
reactive=True,
structure=SMILES("O=C=O")
)

#Reaction systems
#currently RMG models only constant temperature and pressure as homogeneous batch reactors.
#two options are: simpleReactor for gas phase or liquidReactor for liquid phase
#use can use multiple reactors in an input file for each condition you want to test.
simpleReactor(
#specifies reaction temperature with units
temperature=(700,'K'),
#specifies reaction pressure with units
pressure=(10.0,'bar'),
#list initial mole fractions of compounds using the label from the 'species' label.
#RMG will normalize if sum/=1
initialMoleFractions={
"N2": 4,
"O2": 1,
"butane": 1./6.5,
},
#the following two values specify when to determine the final output model
#only one must be specified
#the first condition to be satisfied will terminate the process
terminationConversion={
'butane': .99,
},
terminationTime=(40,'s'),
#the next two optional values specify how RMG computes sensitivities of
#rate coefficients with respect to species concentrations.
#sensitivity contains a list of species' labels to conduct sensitivity analysis on.
#sensitvityThreshold is the required sensitiviy to be recorded in the csv output file
#    sensitivity=['CH4'],
#    sensitivityThreshold=0.0001,
)

# liquidReactor(
# 	temperature=(500,'K'),
#     initialConcentrations={
# 		"N2": 4,
# 		"O2": 1,
# 		"CO": 1,
#     },
#     terminationConversion=None,
#     terminationTime=(3600,'s'),
#     sensitivity=None,
#     sensitivityThreshold=1e-3
# )
#liquid reactors also have solvents, you can specify one solvent
#list of solvents available at : http://rmg.mit.edu/database/solvation/libraries/solvent/
# solvation('water')

#determines absolute and relative tolerances for ODE solver and sensitivities.
#normally this doesn't cause many issues and is modified after other issues are
#ruled out
simulator(
atol=1e-16,
rtol=1e-8,
#    sens_atol=1e-6,
#    sens_rtol=1e-4,
)

#used to add species to the model and to reduce memory usage by removing unimportant additional species.
#all relative values are normalized by a characteristic flux at that time point
model(
#determines the relative flux to put a species into the core.
#A higher value will result in a larger, more complex model
#when running a new model, it is recommended to start with higher values and then decrease to converge on the model
toleranceMoveToCore=0.1,
#comment out the next three terms to disable pruning
#determines the relative flux needed to not remove species from the model.
#Lower values will keep more species and utilize more memory
toleranceKeepInEdge=0.01,
#determines when to stop a ODE run to add a species.
#Lower values will improve speed.
#if it is too low, may never get to the end simulation to prune species.
toleranceInterruptSimulation=1,
#number of edge species needed to accumulate before pruning occurs
#larger values require more memory and will prune less often
maximumEdgeSpecies=100000,
#minimum number of core species needed before pruning occurs.
#this prevents pruning when kinetic model is far away from completeness
minCoreSizeForPrune=50,
#make sure that the pruned edge species have existed for a set number of RMG iterations.
#the user can specify to increase it from the default value of 2
minSpeciesExistIterationsForPrune=2,
#filter the reactions during the enlarge step to omit species from reacting if their
#concentration are deemed to be too low
filterReactions=False,
)

options(
#only option is 'si'
units='si',
#how often you want to save restart files.
#takes significant amount of time. comment out if you don't want to save
saveRestartPeriod=None,
#Draws images of species and reactions and saves the model output to HTML.
#May consume extra memory when running large models.
generateOutputHTML=True,
#generates plots of the RMG's performance statistics. Not helpful if you just want a model.
generatePlots=False,
#saves mole fraction of species in 'solver/' to help you create plots
saveSimulationProfiles=False,
#gets RMG to output comments on where kinetics were obtained in the chemkin file.
#useful for debugging kinetics but increases memory usage of the chemkin output file
#gets RMG to generate edge species chemkin files. Uses lots of memory in output.
#Helpful for seeing why some reaction are not appearing in core model.
saveEdgeSpecies=False,
#Sets a time limit in the form DD:HH:MM:SS after which the RMG job will stop. Useful for profiling on jobs that
#do not converge.
#wallTime = '00:00:00',
keepIrreversible=False,
#Forces RMG to import library reactions as reversible (default). Otherwise, if set to True, RMG will import library
#reactions while keeping the reversibility as as.
)

# optional module allows for correction to unimolecular reaction rates at low pressures and/or temperatures.
pressureDependence(
#two methods available: 'modified strong collision' is faster and less accurate than 'reservoir state'
method='modified strong collision',
#these two categories determine how fine energy is descretized.
#more grains increases accuracy but takes longer
maximumGrainSize=(0.5,'kcal/mol'),
minimumNumberOfGrains=250,
#the conditions for the rate to be output over
#parameter order is: low_value, high_value, units, internal points
temperatures=(300,2200,'K',2),
pressures=(0.01,100,'bar',3),
#The two options for interpolation are 'PDepArrhenius' (no extra arguments) and
#'Chebyshev' which is followed by the number of basis sets in
#Temperature and Pressure. These values must be less than the number of
#internal points specified above
interpolation=('Chebyshev', 6, 4),
#turns off pressure dependence for molecules with number of atoms greater than the number specified below
#this is due to faster internal rate of energy transfer for larger molecules
maximumAtoms=15,
)

#optional block adds constraints on what RMG can output.
#This is helpful for improving the efficiency of RMG, but wrong inputs can lead to many errors.
generatedSpeciesConstraints(
#allows exceptions to the following restrictions
allowed=['input species','seed mechanisms','reaction libraries'],
#maximum number of each atom in a molecule
maximumCarbonAtoms=4,
maximumOxygenAtoms=7,
maximumNitrogenAtoms=0,
maximumSiliconAtoms=0,
maximumSulfurAtoms=0,
#max number of non-hydrogen atoms
#maximumHeavyAtoms=20,
#If this is false or missing, RMG will throw an error if the more less-stable form of O2 is entered
#which doesn't react in the RMG system. normally input O2 as triplet with SMILES [O][O]
#allowSingletO2=False,
# maximum allowed number of non-normal isotope atoms:
#maximumIsotopicAtoms=2,
)

#optional block allows thermo to be estimated through quantum calculations
# quantumMechanics(
# 	#the software package for calculations...can use 'mopac' or 'gaussian' if installed
# 	software='mopac',
# 	#methods available for calculations. 'pm2' 'pm3' or 'pm7' (last for mopac only)
# 	method='pm3',
# 	#where to store calculations
# 	fileStore='QMfiles',
# 	#where to store temporary run files
# 	scratchDirectory = None,
# 	#onlyCyclics allows linear molecules to be calculated using bensen group addivity....need to verify
# 	onlyCyclics = True,
# 	#how many radicals should be utilized in the calculation.
# 	#If the amount of radicals is more than this, RMG will use hydrogen bond incrementation method