Computational Science Community Wiki

This is a guide to the steps to be taken to add a new chemical species, and reactions, to a KPP scheme. This guide will not tell you how to add your own chemical scheme to the model - that is a topic for another guide.

The guide will enable you to add a chemical species to WRF-Chem, have it passed to/from the KPP chemical mechanism (and modified in that mechanism), and then have the chemical species passed out in the output files. Only chemical processing, and transport via advection, will affect your new species. Adding other processes, such as dry/wet deposition, is not covered below.

This guide assumes that you have some familiarty with KPP notation. If you don't I recommend reading up on this first:

Chemical scheme source files are stored in the directory:

The KPP mechanism files are in sub-directories here:

Extra code inclusion files for these mechanisms are in sub-directories here:

Chemical species and mechanism information for WRF-Chem in general (as seperate from the KPP-generated mechanism) is stored in the chemical registry file:

Once all the changes are made then the code will need recompiling (from scratch, because of both the changes to the Registry and to the KPP source code). I recommend saving your working executables before carrying out this process, so that you can compare the results from different executables to ensure you have only changed what you wanted to.

Actions to take:

1) Add new chemical species to registry file:

Gas-phase chemical species are listed in the file like this:

(search for "# Chem Scalars") I recommend copying a line such as this one for SO2, and simply replace all instances of "so2" with your given chemical name.

2) Add the new chemical species to your chemical scheme (in the registry file):

The chemical species within a chemical scheme are defined within lines denoted by:

The chemical scheme name is in the second column (with _kpp added here, as this is how WRF-Chem labels all the KPP generated chemical schemes), the ID number is set in the third column, and the chemical species are all defined in the fifth column.

The chemical species order is: [all gas-phase species] [all aerosol species] The name of the *final* gas-phase species in this list is hard-coded into WRF-Chem - and there can be significance to the order of the initial gas-phase species (though I can't recall exactly what right now). I recommend adding your new species just before the final gas-phase species, to avoid indexing problems later.

For CRIMECH that last gas-species is "ic3h7no3".

3) Add the new chemical species to your KPP species file (*.spc), which is in the "mechanisms" directory. It should go in your #DEFVAR column.

4) Add the chemical reactions which affect your new species to the KPP equation file (*.eqn).

5) Important Note: KPP and WRF-Chem chemical names do not always match up. In the mechanisms folder is a file which defines how to match up KPP and WRF-Chem chemical names if they are not the same (*_wrfkpp.equiv). The most common example of this is OH - which is HO in WRF-Chem, but OH in most KPP mechanisms. I recommend using the same name in both KPP and WRF-Chem if you can - if you can't then match the names here. But be careful to never use a KPP name which exists as a WRF-Chem name for a different chemical species - the pre-processor cannot cope with these situations, and your compiled executable will simply be wrong.

6) If you wish to create a new rate calculation for your chemical reaction, add this to the definition file (*.def).

7) Not all required code can be passed through the KPP source code. For example, the calculations required to define RO2 cannot be inserted into the model code in this manner. To get around this limitation we use the include files mentioned above. Most of the include files seem to not be used very often - the key files of interest are: