Overview

The Dynamically Simple Model for Atmospheric Chemical Complexity (DSMACC) is a tropospheric chemistry box model designed to help understand the composition of the troposphere in a flexible and friendly manner. It is written to address a range of problems ranging from calculating the expected concentrations of atmospheric radicals to comparing chemistry schemes.

Instructions

This descibes the steps necessary to run the model. These instructions assume basic knowledge of Linux Bash or C-Shell.

1. Install prerequisites
2. Run the test case
3. Modifying the model chemistry scheme (optional)
4. Re-compiling and compiling the model (optional)
5. Creating your own the model inputs
6. Running the model

Install prerequisites

DSMACC has relatively few requirements and all can be obtained free of charge. DSMACC itself requires a basic linux development environment. DSMACC also uses KPP (distributed with DSMACC), which requires a parser and a lexer.

1. Linux/Unix environment (including cygwin on windows)
2. C and Fortran compilers (e.g., GNU, Intel, or Portland Group)
3. Bison
4. FLEX

Test Case

The test case assumes that you have KPP installed with kpp in your PATH and the KPP_HOME environment variable set. (if not see [KPP Configuration](KPP Configuration)) These instructions will build the DSMACC model, and run it with example inputs. It will then compare your results with a set of archived results.

1. Click here to download code
2. Open a terminal and navigate to folder where the code was downloaded
3. type unzip DSMACC-master.zip
4. type cd DSMACC-master
5. type ./configure
6. type make

This will run a test case and produce some figures (requires python and numpy).

Chemistry Options

Standard KPP input

Which chemistry scheme you are going to run in the model is described by the series of files at the beginning of the model.kpp file. For example if you have the line #INCLUDE mcm_subset.kpp in your model.kpp file the chemistry included in that file will be included in chemistry scheme. For details about how to write these files see the kpp user manual.

MCM input

Using MCM is easiest using a single extracted subset that includes both inorganic and organic chemistry.

To make a new mcm_subset.kpp, go to http://mcm.leeds.ac.uk/MCM/roots.htt . Then select the base VOCs that you would like to simulate the chemistry of by selecting the check boxes associated with each species. Once all the VOC's have been selected click 'Added Selection to Marked List.' Then click on 'Extract' from the menu at the top of the page. Select "KPP, experimental KPP format". It is good practice to select "Include generic rate coefficients" and "Include inorganic reactions." and " Then, Click on Extract.

By default, the extract will be called mcm_subset.kpp that needs two updates: line endings and mcm_constants call. First, it has mixed line endings that will not work. Second, reactions with no products need a DUMMY species. Third, the mcm_constants call is set to overwrite generic rate coefficients, which is not desirable.

These can be fixed by (1) using consistent line endings, (2) commenting out mcm_constants call, (3) adding DUMMY as a product, and (4) fixing DUMMY definition in VARDEF. Each of the four steps is shown a separate command for vi and python.

For vi:

   vi +':e ++ff=dos' +':wq ++ff=unix' mcm_subset.kpp
   vi +':%s/^\s*CALL mcm_constants/! CALL mcm_constants/' +':wq' mcm_subset.kpp
   vi +':%s/= :/= DUMMY :/g' +':wq' mcm_subset.kpp
   vi +':%s/^ = IGNORE/DUMMY = IGNORE/' +':wq' mcm_subset.kpp

For python:

    python -c "txt = open('mcm_subset.kpp', 'rU').read(); # implicit line ending fix
    txt = txt.replace('CALL mcm_constants', '! CALL mcm_constants'); # comment out mcm_constants
    txt = txt.replace('= :', '= DUMMY :'); # add DUMMY to productless reactions
    txt = txt.replace('\n = IGNORE', 'DUMMY = IGNORE') # fix DUMMY species definition
    open('mcm_subset.kpp', 'w').write(txt);"

Now make a master kpp file. The easiest approach is to modify the copy in working. Replace the line #INCLUDE CRI_subset.kpp with #INCLUDE mcm_subset.kpp. Then follow the compilation instructions

Using the GEOS-Chem globchem.dat file

(this is under developement)

This uses the GEOS-Chem globchem.dat file to generate a series of files (globchem.eqn, globchem.spc and globchem.def.) in kpp format to use in the model;

change all species in globchem.dat to Active if possible. there are bugs in kpp code for some reactions with two lines. In order to make it work right, we have to modify the globchem.dat for reactions, HNO4+M; N2O5+M; HO2+MCO3; DMS+OH; change the reaction rate for photolysis reactions to match up with TUV if you have 5 lines for each reaction in glochem.dat (such as v8-02-05) change line 225 in Geos2kppbox_parser.pl from "4" to "5" type Geos2kppbox_parser globchem.dat to generate globchem.eqn, globchem.spc and globchem.def.

There are two steps to compiling the model. The first is to get kpp to generate the appropriate FORTRAN code and the second is to compile the FORTAN code into a program.

Compilation Instructions

Generate the code

First, build a master.kpp file (e.g., MCM input). In this tutorial, the master kpp file is assumed to be named master.kpp, but it can be anything (e.g., dsmacc.kpp mcm.kpp, cri.kpp, etc). To build the model code, you must run kpp from within the DSMACC/src directory with the master.kpp path as the first argument and dsmacc as the second argument. For this command to be successful, you will need KPP_HOME set in your environment and PATH updated to include ${KPP_HOME}/bin. The commands below demonstrate the full process, but you will need to update /path/to/master.kpp to point to your master file:

cd DSMACC-master/
export KPP_HOME=${PWD}/kpp/
cd src
export PATH=${KPP_HOME}/bin:${PATH}
kpp /path/to/master.kpp dsmacc

Assuming this is successful, you will see a success report that ends with:

    KPP has succesfully created the model "dsmacc".

If you see errors and do not get a success message, consult the kpp user handbook. Otherwise, you are ready to comple the code.

Making the model

To make the model as an executable, enter the DSMACC/src folder and type make. The model will be constructed and named dsmacc and be present in the DSMACC/bin folder.

Inputs and Initial Conditions

There are two model inputs that are necessary: photolysis inputs and initial conditions. Photolysis inputs should be symbolically linked or copied to your run directory. (tuv_new/DATABHH, tuv_new/DATAE1, tuv_new/DATAJ1, tuv_new/DATAS1 tuv_new/INPUTS).

Initial condition and control information are contained in a file called Init_cons.dat. It looks like a spreadsheet with columns representing different aspects of the initial conditions (time, pressure, latitude, concentrations) and the rows representing different independent simulations of the model. Use one of the test files (e.g., cri.Init\_cons.timeseries.dat) as a template.

1^st Line

If the first line of the file contains a positive integer this tells the model to run forwards into for that number of seconds. The output of each independent simulation is written to the files Spec_*.dat and Rate_*.,dat where the * represents an integer value representing the simulation number.

If the first line contains -1 the model is run forwards until a diurnal steady state has been reached with output for the final timestep of all the independent simulations being output into the files Spec_1.dat and Spec_2.dat

If the first line contains -2 the model is run forwards until a diurnal steady state has been reached with output for the final 24 hours for each independent simulations being written to the files Spec_*.dat and Rate_*.dat.

2^nd Line

The second row in the file should contain the parameters to be input into the model. Each parameter name is 15 characters long, separated by an space (it is read in by the FORTRAN format statement ‘100000(a15,x))’. The following parameters can be set (case sensitive).

Key Value

---

PRESS Pressure hPa H2O H2O (v/v) LAT Latitude (decimal degrees) LON Longitude (decimal degrees) TEMP Temperature (K) JDAY Julian day fractional O3COL Ozone column (Dobsons) ALBEDO The surface albedo (fraction) SAREA Surface area of aerosols (m^2/m^3) RP1 Radius of particles (m) SPECIES NAME Mixing ratio of species (v/v)

If a parameter is set which is not in the above list or is a species name as defined by the chemistry of the model the will stop (unless it starts with an X, XOH will not cause the model to crash).

3^rd Line

The third line gives information about which values should be constrained and which ones allowed to run freely in the model simulations. Each parameter is 15 characters long, separated by an space (it is read in by the FORTRAN format statement ‘100000(a15,x))’. contain either a "1" or a "0", indicating whether the parameter is to be constrained in the model, with a ‘1’ indicating constraint on the parameter and a ‘0’ indicating no constraint. Subsequent rows contain the input data to the model, with concentrations in mixing ratio.

Where total NOx is to be constrained it is necessary to constrain either NO or NO2, but not both. While the parameter ‘NOx’ must be included in the Init_cons.dat file for total NOx to be constrained, its values in the file can be set to zero.

In order to constrain NOx the model will calculate a number every 24 hours by which the NO (or NO2 if NO2 is constrained in preference to NO) must be multiplied so that its modelled value remains in agreement with its observed value input into the model. All NOx species will subsequently be multiplied by this value, and hence constrained by proxy to NO (or NO2).

If neither J (O(^1^D)) nor J (NO2) are included in the input file, clear-sky values will be calculated at the altitude in question (determined from the pressure input) using TUV cross-sections at solar zenith angles varying between 0 and 90 degrees in 5 degree steps. The solar zenith angle (SZA) at which the observations were made is then calculated from the observed latitude, longitude and time of day, and a spline fit to the calculated J-values as a function of SZA used to determine the appropriate J-value.

If J (O(^1^D)) or J (NO2) are present in the input file the model will compare calculated J-values to their observed values and scale all calculated values accordingly.

Unless otherwise stated in the input file the model assigns [CH4] = 1770 ppm, [H2] = 550 ppm, and an ozone column of 260 Dobsons.

Finally, run the new model

To run the model type ../bin/dsmacc

To log the diagnostic information produced by the model to a file type dsmacc > model_output

Credits

The original code development was by Mat Evans and Kathryn Emmerson at the University of Leeds. Subsquently developement / testing work has been undertaken by Barron Henderson (UF), Dylan Millet , Michael Berkley (U. Edinburgh), and Daniel Stone (U. Leeds). The interface for GEOS-Chem was developed by Jingqiu Mao (Harvard) and Mat Evans.

The DSMACC model code and testcase is available from here. It is based on the KPP chemistry integration code written at Virginia Tech by Adrian Sandu's group.

If you use the code and wish to cite the model please use:

Emmerson, KM; Evans, MJ (2009) Comparison of tropospheric gas-phase chemistry schemes for use within global models, ATMOS CHEM PHYS, 9(5), pp1831-1845 doi: 10.5194/acp-9-1831-2009 .