Altering the Chemical Mechanism Input File

This page describes the chemical mechanism input file (e.g., chem_mech.in) and how to alter this file to update existing reactions (rates/products) or add new reactions and species. For teaching purposes, we have copied part of the default input file below (gray boxes) to describe how each section works. For brevity, we do not list all species or reactions and a red etc. indicates missing parts of the mechanism. For more information, CAM-chem uses the same chemical preprocessor as MOZART, which is described in great detail at http://www.cesm.ucar.edu/working_groups/Chemistry/chemistry.preprocessor.pdf.  

The first section lists all information related to the species in the chemical mechanism and includes the following four subsections:

a) This section, lists all species used in the chemical mechanism. In order to add a new species, add a row to this list and add your new species in the following format: "Species name -> Species Chemical Formula".  WARNING: species containing '_a' or '_c' will assumed to be aerosols, following the convention used in the Modal Aerosol Model (MAM).

b) This section lists the fixed species. When running with full chemistry only M, N2, and O2 should be fixed. When running with reduced chemical mechanisms (e.g., climate simulations with CESM2) often more species are added to this list. 

c) This section defines those species, for which a vertical column integral is required. The base photolysis routines require column integrals for O3 and O2. 

d) This section lists the non-transported species. These are species that do not need to be transported from grid box to grid box because their chemical lifetime is very short. In the default chemical mechanism, only radicals are included in this list. Any species not included in this list will be transported. Note: if a species is undergoing dry or wet deposition, it must be transported due to how the CESM code is structured.

2) The second section, groups all of the species defined in the first section into two classes: explicit and implicit. If you add a new species, you must add it to one and only one of these classes. The explicit species are solved via the forward Euler or explicit algorithm. Be careful adding new species to the explicit class, these species are assumed to have very long lifetimes. Do not put highly reactive species (e.g., OH) in the explicit solution class. The implicit species are solved with a backward Euler or implicit algorithm. If in doubt, put a new species in the implicit solution class. 

3) The third and final section lists all of the chemical reactions and is seperated into the following 3 sections. *** are used to specify comments and group subsections for ease of viewing as shown below.

a) This section lists out all the photolysis reactions.  Photolysis reactions are listed in the following format: "[unique_label] reactant + hv -> products". For new photolysis reactions, photolysis reaction rates can be mapped to preexisting photolysis reactions with an optional scaler as shown below in green. For these reactions use the following format: "[unique_label_of_new_reaction->,scaler*label_of_old_reaction] reactant + hv -> products"

b) This section lists out all of the chemical reactions in the following format: [unique_label] Reactants -> Products ; Reaction rate constant. The reaction rate constant can take a number of forms.

• If the reaction rate constant is temperature independent, write the reaction rate constant (e.g., magenta).
• If the reaction rate constant is temperature dependent, write a0, b0 according to the following Arrehenius equation: a0 * exp( b0/t ) where t is temperature (degrees Kelvin) (e.g., green).
• You can also input termolecular reactions, which are in the following form as defined by JPL (https://jpldataeval.jpl.nasa.gov/) (e.g. blue). For these termolecular rate constants, write the rate coefficients in the following order:  a0, a1, b0, b1, x and include a tag_ in front of each label. 

k0 = a0*(300/t)**a1

kinf = b0*(300/t)**b1

reaction rate constant = ko/(1+ko*M/kinf)*x^(1/(1+[log10(ko*M/kinf)]^2))

where

M = total atmospheric density (molecules/cm**3) (Note: The reaction rate constant above is written such that M must be included as a reactant as labeled in blue below).

x = "exponential factor". In JPL, the default exponential factor is 0.6.

t = temperature (degrees Kelvin)

• Reaction rates of other types can also be included in the mechanism, but they must be added manually to the following file: mo_usrrxt.F90 (e.g., purple)
  • To do this, add usr_ to the front of the label for these reactions. Copy the mo_usrrxt.F90 file from the source code located here: $code_directory$/components/cam/src/chemistry/mozart/ to $your_case_directory$/SourceMods/src.cam. Update the fortran code in this file for your individualized reaction rate constant.

c) This section lists out all species that have "external" or in situ (vertically distributed) chemical forcing. For species that will use values read from a dataset (e.g., species with vertically distributed emissions), add the species to this list in the following format: "name_of_species <- dataset".