The chemical mechanisms and chemistry specific modifications are described in the CAM6 user guide: https://ncar.github.io/CAM/doc/build/html/users_guide/CAM-chem-specifics.html#chemical-mechanisms. A general description of gas-phase chemistry and current developments are provided in the Gas-Phase Chemistry model component description. There are 6 default mechanisms in CESM2 as described in the table below.

MechanismDescription# Species

# Reactions

Mechanism NamePre-processor Code
TSMLT1Troposphere, stratosphere, mesosphere, and lower thermosphere231583 (433 kinetic, 150 photolysis)MZ197_TSMLT1_20180423pp_waccm_tsmlt_mam4
TS1Troposphere and stratosphere221528 (405 kinetic, 123 photolysis)MZ198_TS1-simpleVBS_20180423pp_trop_strat_mam4_vbs
MAMiddle atmosphere: stratosphere, mesosphere, and lower thermosphere98298 (207 kinetic, 91 photolysis) pp_waccm_ma_mam4
MADMiddle atmosphere plus D-region ion chemistry135593 (489 kinetic, 104 photolysis) pp_waccm_mad_mam4
SCSpecified chemistry for WACCM2912 (11 kinetic, 1 photolysis) pp_waccm_sc_mam4
CAMSimplified chemistry for CAM to to allow tropospheric aerosol formation327 (6 kinetic), 1 photolysis) modal_aero

The input files and fortran routines for these default mechanisms are located in $CCSMROOT/components/cam/src/chemistry/ in the folder specified by the pre-processor code. CAM-Chem and WACCM compsets are defined in section 4.4 and 4.5 of the CAM6 user guide https://ncar.github.io/CAM/doc/build/html/users_guide/atmospheric-configurations.html. All CAM-Chem compsets default to the TS1 chemical mechanism and WACCM compsets default to TSMLT1 chemical mechanism. The TS1 and TSMLT1 chemical mechanisms are described in Emmons et al., 2019 (in preparation).

To review the chemistry used in a specific compset, build your case as described in Run CAM-Chem on Cheyenne. In the $CASEROOT/CaseDocs folder there are 2 files that describe the chemistry chem_mech.in and chem_mech.doc. Both have similar information describing the species and reaction rates. The chem_mech.doc file is in a more human readable format and includes the differential equations defining the production and loss terms of each species. The chem_mech.in file is the version read by the code, and the version you will alter to make changes to the chemical mechanism.

To update the chemistry, modify the chemical mechanism input file by:

  1. Build your case as described in Run CAM-Chem on Cheyenne.
  2. Copy the input file (chem_mech.in) from $CASEROOT/CaseDocs folder to another folder and rename the mechanism file (e.g., /home/mech/my_mech.in)
  3. Then alter this file as needed following these instructions: Altering the Chemical Mechanism Input File
  4. Then in env_build.xml file, add the following to the CAM_CONFIG_OPTS value "-usr_mech_infile /home/mech/my_mech.in". Note: substitute your own path and mechanism name here.
  5. You will need to rebuild your case for changes to take effect (see Run CAM-Chem on Cheyenne).

To wet deposit a new species

There are two methods to wet deposit a new species. Both involve source code changes. After making the changes below, you must rebuild your case for changes to take effect. Wet deposition in CAM-Chem is described in the Wet Deposition model component description.

The first and easiest method is to map the new species to deposit with the same rate as a species already undergoing wet deposition.

case( 'SO2t' )
test_name = 'SO2'

The second method is to add a new species to the henry's law table list. 

To dry deposit a new species

There are also two methods to dry deposit a new species. Both involve source code changes. After making the changes below, you must rebuild your case for changes to take effect. Dry deposition in CAM-Chem is described in the Dry Deposition model component description.

The first and easiest method is to map the new species to deposit with the same rate as a species already undergoing dry deposition.

case( 'XHNO3' )
test_name = 'HNO3'

The second method is to add a new species to the henry's law table list. 

Add emissions for a new species

If a new species is directly emitted, add emissions by:

Add lower boundary conditions for a new species

For long lived species (e.g., CH4), you can specify the lower boundary conditions instead of having direct emissions from the surface.

To add aerosol uptake for a new species

In the TS1 mechanism, organic nitrate aerosol uptake has been included using aerosol uptake coefficients (γ) similar to that used by Fisher et al. 2016.

If you desire to update these aerosol uptake coefficients, follow these instructions for: Adding Aerosol Uptake for Gas-Phase Species.

Note: The code as it is currently written removes the organic nitrates from the gas-phase, but does not have these organic nitrates contribute to secondary organic aerosol formation. Secondary organic aerosol formation is produced through a separate process.

Note: Currently, aerosol uptake of gas-phase compounds only occurs on the following types of aerosol: sulfate, ammonium nitrate, oc2, and secondary organic aerosol.