Computational Science Community Wiki

Differences between revisions 1 and 2
Revision 1 as of 2017-08-10 09:48:36
Size: 4618
Editor: DouglasLowe
Comment:
Revision 2 as of 2017-08-10 10:32:59
Size: 4971
Editor: DouglasLowe
Comment:
Deletions are marked like this. Additions are marked like this.
Line 32: Line 32:

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.
Line 98: Line 105:

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: http://people.cs.vt.edu/asandu/Software/Kpp/

Chemical scheme source files are stored in the directory:

  • chem/KPP/

The KPP mechanism files are in sub-directories here:

  • chem/KPP/mechanisms/

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

  • chem/KPP/inc/

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

  • Registry/registry.chem

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:

  • state real so2 ikjftb chem 1 - i0{12}rhusdf=(bdy_interp:dt) "so2" "SO2 mixing ratio" "ppmv"

(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:

  • package cri_mosaic_4bin_aq_kpp chem_opt==611 - chem:dms......

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:

  • extra_args_to_update_rconst_***.inc - extra arguments for the call to update_rconst
  • extra_args_update_rconst_***.inc - extra arguments for the update_rconst subroutine (make sure to match those passed)
  • extra_decls_update_rconst_***.inc - declare extra variables within update_rconst (including those being passed)
  • kpp_mechd_l_***.inc - declarations for variables in the KPP mechanism (one level above update_rconst)
  • kpp_mechd_ibu_***.inv - code for calculations made before the call to update_rconst should be included here