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.
This descibes the steps necessary to run the model. These instructions assume basic knowledge of Linux Bash or C-Shell.
- Install prerequisites
- Run the test case
- Modifying the model chemistry scheme (optional)
- Re-compiling and compiling the model (optional)
- Creating your own the model inputs
- Running the model
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.
- Linux/Unix environment (including cygwin on windows)
- C and Fortran compilers (e.g., GNU, Intel, or Portland Group)
- Bison
- FLEX
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.
- Click here to download code
- Open a terminal and navigate to folder where the code was downloaded
- type
unzip DSMACC-master.zip - type
cd DSMACC-master - type
./configure - type
make
This will run a test case and produce some figures (requires python and numpy).
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.
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
(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.
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.
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.
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.
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.
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).
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.
To run the model type ../bin/dsmacc
To log the diagnostic information produced by the model to a file type
dsmacc > model_output
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 .