DSMACC chemical box model

From Geos-chem
Jump to: navigation, search

This page describes the DSMACC chemical box model (U. Leeds).


Brief description

The Dynamically Simple Model of Atmospheric Chemical Complexity (DSMACC) is designed to be a simple box model which can easily change its chemical scheme and can be used both for free running and constrained simulations. It is written in FORTRAN and uses the KPP chemical pre-processor, the TUV photolysis scheme and can use the Master Chemical Mechanism or other chemical mechanisms.

DSMACC is a useful and flexible tool. We are using it to test new GEOS-Chem chemical mechanisms.

New information on DSMACC can be found here. The code is freely available although support is limited!

Instructions for Use

Instructions for DSMACC are in the README, but are summarized below.

  1. Download the model (wget https://github.com/barronh/DSMACC/archive/master.zip)
  2. Unzip the archive (e.g., unzip master.zip)
  3. Navigate a terminal into DSMACC-master
  4. Run the test case (make check)

The test case includes a version 8 GEOS-Chem simulation that you can modify for your purposes. This test case is just a toy and is not meant for analysis.

--barronh 10:04, 25 October 2013 (EDT)

Authors and collaborators


The current version of DSMACC has been largely updated by Barron Henderson. Barron has developed all python-based parsers for GEOS-Chem and other mechanisms. Perl parser is not supported in current box model simulations.

I recently tested v9-02 with tremendous help from Barron. The current package can run both GC v8-02-03 and GC v9-02. If you have any questions, please contact Barron Henderson (University of Florida).

Model setup

First, download the code and configure

curl -kLO https://github.com/barronh/DSMACC/archive/master.zip
unzip master.zip
cd DSMACC-master/
./configure (to generate Makefile.defs)

The second step is to add these two lines to your .cshrc or .bashrc

setenv KPP_HOME /your-home-directory/DSMACC-master/kpp
setenv PATH /your-home-directory/DSMACC-master/kpp/bin:${PATH}


export KPP_HOME
export PATH=$KPP_HOME/bin:$PATH

The next step is to modify Makefile.defs change this line




Third step is to generate the executable for kpp

 make kpp/bin/kpp 

This will generate the executable file kpp.

Prepare the input file (This step is optional)

Using python parser (assuming you have python loaded up in your machine)

curl -kLO https://github.com/barronh/pykpp/raw/master/src/pykpp/models/prep/geoschem2kpp.py
python geoschem2kpp.py globchem.dat > globchem.eqn

This will produce globchem.eqn.

This step is not required in current package, as it is already done.

Mapping photolysis rates to TUV index

DSMACC uses TUV model to drive the photolysis reactions. You will need to modify the generated eqn for this. TUV reactions are described in usrinp.

This step is not required in current package, as it is already done.

Special treatment for special rates

You can define some special rates that not in the standard form of reaction rates. This can be done by modifying GEOSFunctions.inc.

This step is not required in current package, as it is already done.

Generate kpp files based on your mechanism

go to DSMACC-master/src folder

../kpp/bin/kpp ../test/geoschem-09-02.kpp dsmacc 

Here geoschem-09-02.kpp includes all the information for the mechanism. This will generate a series of .f90 files. To run v8-02-03 chemistry, you can just change geoschem-09-02.kpp to geos.kpp, which includes all v8-02-03 information.

Inputs and initial conditions

This section is copied from here. The model 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.

1st 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.

2nd 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).

3rd 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(1D)) 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(1D)) 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.

Run the model

compile the files that are generated by kpp. Type


in the DSMACC-master/src folder. This will generate the executable file dsmacc in DSMACC-master/bin folder.

To run the model, you should have a initialization file "Init_cons.dat", which describes the initial concentrations of all species.

Go to DSMACC-master/test folder,type


It is important to run this command in this folder, because this folder includes the Init_cons.dat, and a few other links to TUV (INPUTS/usrinp, DATAE1, DATAJ1, DATAS1). You can of course run this command in other folders with these files included.


1. KPP parser doesn't like any reaction without products. This will give you an error message like

Error :/home/j1m/boxmodel_jmao/kpp/models/./am3Functions.inc:1: Misplaced ';'

You can add DUMMY to the product.

2. KPP parser cannot read DOS format file. You will get some error message like

KPP is parsing the equation file.Error :/home/j1m/boxmodel_jmao/kpp/models/./geos_chem.spc:1: 'DEFVAR
': Unknown command (ignored)
Error :/home/j1m/boxmodel_jmao/kpp/models/./geos_chem.spc:2: Extra parameter on command line 'M'
Error :/home/j1m/boxmodel_jmao/kpp/models/./geos_chem.spc:2: Extra parameter on command line '='
Error :/home/j1m/boxmodel_jmao/kpp/models/./geos_chem.spc:2: Extra parameter on command line 'IGNORE'
;Error :/home/j1m/boxmodel_jmao/kpp/models/./geos_chem.spc:2: Extra parameter on command line ' '

To fix this, just do this for the input file in vi:

:set fileformat=unix

3. If you would like to debug with Totalview, you need to add a few compile options (-g -O0) to F90FLAGS in Makefile.defs. Something like this:

F90FLAGS=-cpp -O0 -g -fno-automatic -fbounds-check -fimplicit-none

Then recompile the executable (/bin/dsmacc).

Diagnosing the model

This subsection is copied from Mat's document. Once the model has been run you will need to diagnose the model output. Routines for doinng this have been developed at the university of Leeds. They are all written in the IDL programming language. These files can be found here. The diagnositc suite currently consists of a routine to read in the concentrations and rates simulated, and then one to perform a Rate Of Production Analysis (ROPA).

read data

Calling readin_data, filename, names, data in IDL will readin the Spec_*.dat or Rate_*.dat file called filename. The names of the chemical species and other parameters will be returned in the string array called names, and the information about the values of the parameters and chemical species concentrations will be returned in the real array data.

calculate production and loss rates

This routine looks at the different reactions producing or destroying a species or family and outputs the reactions rates in order of significant. It will also produce graphs and give text output.

Calling ropa, spec, names, concs, reacts, rates, factors=factors, graphics=graphics, text=text, title=title, p_reacts=p_reacts, p_rates=p_rates, l_reacts=l_reacts, l_rates=l_rates

causes the code to calculate a ropa for a species of family given in spec (e.g. 'O3' would analyse the rate of production of O3, while ['O3,'NO2','NO3', 'O(3P)','O(1D)'] would do an analysis for Ox). The list of species names used in the simulations is given names with their concentrations described in concs, the names of the reactions in the chemistry scheme is given in reacts, and the rates of those reactions is described in rates.

The average value of the simulations provided by concs and rates arrays are used.

factors describes the weighting factors to be used to account for some species having multiple weights in a family. So for the Ox family given above the weightings would be [1,1,2,1,1] to account for the fact that NO3 represents 2 Ox.

including /graphics, will make a graph of the output which shows the 10 most significant sources and sinks of the species or family selected.

Including /text will output the 10 most significant sources and sinks to the screen.

After running ropa.pro p_reacts, p_rates, l_reacts and l_rates will contain those reactions involved in the production or loss of the species or family selected sorted by their signiciance, with p_reacts and l_reacts containing the reaction names and p_rates and l_rates containing their rates.


  1. Emmerson, K.M., M. J. Evans, Comparison of tropospheric gas-phase chemistry schemes for use within global models, Atmos. Chem. Phys., 9, 1831-1845, 2009. PDF

Resolved Issues

Diurnal cycle

September 9th, 2014

Dylan Millet discovered a bug in the code for imposing diurnal cycle on photolysis rate. A new fix has been applied in the latest version of DSMACC.

The photolysis model for GEOS-Chem (did not affect MCM) was operating without a diurnal cycle even when time was changing. This was a bug in the driver.f90 and has been fixed on Sept 10th, 2014. Use the latest version to resolve this problem.

-Barron Henderson

Known issues

The heterogeneous reactions are not implemented yet. This can be done by modifying GEOSFunction.inc.