UKCA & UMUI Tutorial 4

Adding new chemical tracers

As UKCA is a framework, it must have the infrastructure around it to allow it to work, with the infrastructure being the UM itself. In this tutorial you will add in two new chemical tracers. While you may think that you should start this by editing the UKCA code, in fact you should first adapt the UM and the UMUI so that it knows that these new tracers exist. Once you have created them you can then edit the UKCA code to use them to transport chemical species around.

For this tutorial you will need to make a new branch in the usual way. You should do this now.

1. Adding a tracer into the UMUI

1. Pick a free UKCA tracer slot

The UM has 150 tracers available for use by UKCA in STASH section 34. The first 100 of these are chemical tracers, which may (or may not) be in use by the various schemes that are currently available. The last 101-150 are reserved for aerosol and diagnostic tracers. You should therefore ensure that the tracers that you add are in one of the 1-100 slots, although many of these slots will already be in use by the scheme that you are using.

To choose the correct slot(s), you should first examine the nm_spec array which is in the ukca_setd1defs.F90 routine. To do this, cd into

vn8.2_your_branch/src/atmosphere/UKCA

and view the ukca_setd1defs.F90 file. This will give the following for the nm_spec array which is found around line 360:

     IF (L_UKCA_RAQ) THEN
         !This list of tracers is valid for the RAQ chemistry.
         !If MODE aerosols are used with it but their positions  
         !change in the array then the list needs to be updated.
         nm_spec(1:n_all_tracers) = (/                                     &
        'O3        ','NO        ','NO3       ','NO2       ','N2O5      ',  &
        'HO2NO2    ','HONO2     ','H2O2      ','CH4       ','CO        ',  &
        'HCHO      ','MeOOH     ','HONO      ','C2H6      ','ETOOH     ',  &
        'MeCHO     ','PAN       ','C3H8      ','N-PrOOH   ','I-PrOOH   ',  &
        'EtCHO     ','Me2CO     ','MeCOCH2OOH','PPAN      ','MeONO2    ',  &
        'O3S       ','C5H8      ','ISOOH     ','ISON      ','MACR      ',  &
        'MACROOH   ','MPAN      ','HACET     ','MGLY      ','NALD      ',  &
        'HCOOH     ','MeCO3H    ','MeCO2H    ','MVK       ','MVKOOH    ',  &
        'Cl        ','ClO       ','Cl2O2     ','OClO      ','Br        ',  &
        'BrO       ','BrCl      ','BrONO2    ','N2O       ','HCl       ',  &
        'HOCl      ','HBr       ','HOBr      ','ClONO2    ','CFCl3     ',  &
        'CF2Cl2    ','MeBr      ','N         ','O(3P)     ','ORGNIT    ',  &
        'MeCl      ','CF2ClBr   ','CCl4      ','CF2ClCFCl2','CHF2Cl    ',  &
        'MeCCl3    ','CF3Br     ','H2OS      ','CH3OH     ','H2        ',  &
        'SO2       ','H2SO4     ','DMS       ','MSA       ','DMSO      ',  &
        'NH3       ','CS2       ','COS       ','H2S       ','H         ',  &
        'OH        ','HO2       ','MeOO      ','EtOO      ','MeCO3     ',  &
        'n-PrOO    ','i-PrOO    ','EtCO3     ','MeCOCH2OO ','RNC2H4    ',  &
        'RNC3H6    ','C2H4      ','C3H6      ','C4H10     ','C4H9OOH   ',  &
        'MEK       ','TOLUENE   ','MEMALD    ','GLYOXAL   ','oXYLENE   ',  &
        'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC',  &
        'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  &
        'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC',  &
        'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC',  &
        'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du',  &
        'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ',  &
        'Cor_SOL_OZ','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH',  &
        'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX       ',  &
        'Dust_Div_1','Dust_Div_2','Dust_Div_3','Dust_Div_4','Dust_Div_5',  &
        'Dust_Div_6','Rn-222    ','Pb-210    ','XXX       ','XXX       '   &
         /)
     ELSE
! Tracers 98,99 & 100 are for lumped Nitrogen, Br and Cl for stratospheric chemistry,
!  but can only be renamed in STASHmaster file not in advt or nm_spec.
         nm_spec(1:n_all_tracers) = (/                                     &
        'O3        ','NO        ','NO3       ','NO2       ','N2O5      ',  &
        'HO2NO2    ','HONO2     ','H2O2      ','CH4       ','CO        ',  & !10
        'HCHO      ','MeOOH     ','HONO      ','C2H6      ','EtOOH     ',  &
        'MeCHO     ','PAN       ','C3H8      ','n-PrOOH   ','i-PrOOH   ',  & !20
        'EtCHO     ','Me2CO     ','MeCOCH2OOH','PPAN      ','MeONO2    ',  &
        'O3_S      ','C5H8      ','ISOOH     ','ISON      ','MACR      ',  & !30
        'MACROOH   ','MPAN      ','HACET     ','MGLY      ','NALD      ',  &
        'HCOOH     ','MeCO3H    ','MeCO2H    ','H2O       ','ISO2      ',  & !40
        'Cl        ','ClO       ','Cl2O2     ','OClO      ','Br        ',  &
        'BrO       ','BrCl      ','BrONO2    ','N2O       ','HCl       ',  & !50
        'HOCl      ','HBr       ','HOBr      ','ClONO2    ','CFCl3     ',  &
        'CF2Cl2    ','MeBr      ','N         ','O(3P)     ','MACRO2    ',  & !60
        'MeCl      ','CF2ClBr   ','CCl4      ','CF2ClCFCl2','CHF2Cl    ',  &
        'MeCCl3    ','CF3Br     ','H2OS      ','CH2Br2    ','H2        ',  & !70
        'DMS       ','SO2       ','H2SO4     ','MSA       ','DMSO      ',  &
        'NH3       ','CS2       ','COS       ','H2S       ','H         ',  & !80
        'OH        ','HO2       ','MeOO      ','EtOO      ','MeCO3     ',  &
        'n-PrOO    ','i-PrOO    ','EtCO3     ','MeCOCH2OO ','MeOH      ',  & !90
        'Monoterp  ','Sec_Org   ','SESQUITERP','SO3       ','AROM      ',  &
        'O(3P)_S   ','O(1D)_S   ','NO2       ','BrO       ','HCl       ',  & !100
        'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC',  &
        'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  & !110
        'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC',  &
        'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC',  & !120
        'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du',  &
        'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ',  & !130
        'Cor_SOL_OZ','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH',  &
        'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX       ',  & !140
        'Anth_Prec ','Bio_Prec  ','Anth_Cond ','Bio_Cond  ','XXX       ',  &
        'XXX       ','XXX       ','XXX       ','PASSIVE O3','AGE OF AIR'   & !150
         /)
     END IF
! Mode components: Su: sulphate, BC: black carbon, OC: organic carbon
!                  SS: sea-salt, Du: dust,         OZ: organic carbon 2
!                  NH: ammonium, NT: nitrate,      ND: number density

The settings in the UMUI UKCA panel will tell you whether you are using the RAQ chemistry or not (in this tutorial you are not). If you look through the ukca_chem_scheme.F90 file (e.g. ukca_chem_strattrop.F90) then you will see a list of the species that you are using. The following list gives the CheST/strattrop chemical species in black. Red species are either used by the aerosol chemistry or should be avoided, and species in green are not currently used by any scheme and so can be over-written.

        'O3        ','NO        ','NO3       ','NO2       ','N2O5      ',  &
        'HO2NO2    ','HONO2     ','H2O2      ','CH4       ','CO        ',  & !10
        'HCHO      ','MeOOH     ','HONO      ','C2H6      ','EtOOH     ',  &
        'MeCHO     ','PAN       ','C3H8      ','n-PrOOH   ','i-PrOOH   ',  & !20
        'EtCHO     ','Me2CO     ','MeCOCH2OOH','PPAN      ','MeONO2    ',  &
        'O3_S      ','C5H8      ','ISOOH     ','ISON      ','MACR      ',  & !30
        'MACROOH   ','MPAN      ','HACET     ','MGLY      ','NALD      ',  &
        'HCOOH     ','MeCO3H    ','MeCO2H    ','H2O       ','ISO2      ',  & !40
        'Cl        ','ClO       ','Cl2O2     ','OClO      ','Br        ',  &
        'BrO       ','BrCl      ','BrONO2    ','N2O       ','HCl       ',  & !50
        'HOCl      ','HBr       ','HOBr      ','ClONO2    ','CFCl3     ',  &
        'CF2Cl2    ','MeBr      ','N         ','O(3P)     ','MACRO2    ',  & !60
        'MeCl      ','CF2ClBr   ','CCl4      ','CF2ClCFCl2','CHF2Cl    ',  &
        'MeCCl3    ','CF3Br     ','H2OS      ','CH2Br2    ','H2        ',  & !70
        'DMS       ','SO2       ','H2SO4     ','MSA       ','DMSO      ',  &
        'NH3       ','CS2       ','COS       ','H2S       ','H         ',  & !80
        'OH        ','HO2       ','MeOO      ','EtOO      ','MeCO3     ',  &
        'n-PrOO    ','i-PrOO    ','EtCO3     ','MeCOCH2OO ','MeOH      ',  & !90
        'Monoterp  ','Sec_Org   ','SESQUITERP','SO3       ','AROM      ',  &
        'O(3P)_S   ','O(1D)_S   ','NO2       ','BrO       ','HCl       ',  & !100

You should pick one of the green slots (although if you are adding more than 13 new tracers and you know that you will not need any of the red ones, these can also be used. In the future the number of UKCA tracers will be extended.

In this example we will over-write tracer number 65 (CHF2Cl).

2. Edit your user STASHmaster file

In your UMUI job go to Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. This will contain a listing of a file that describes the UKCA tracers that you are using, in this tutorial it is called UKCA_Tr_StratTrop.prestash. Take a copy of this file to your local direcory on PUMA. If you open this file you will see that each tracer has a listing which looks like

#
1|    1 |   34 |    1 |O3 MASS MIXING RATIO AFTER TIMESTEP |
2|    2 |    0 |    1 |    1 |    2 |   10 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000001 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 1861 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

Each of the areas coloured in red above is unique to each tracer, i.e. the name of the tracer and the number of the tracer. Since we are over-writing tracer 65, you would make a new entry in the STASHmaster file which reads

#
1|    1 |   34 |   65 |MY TRACERS NAME                     |
2|    2 |    0 |    1 |    1 |    2 |   10 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000065 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 1861 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

Note: the spacing of the pipes (|) in this file is important, so be careful not to change this.

Now, in the Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. panel replace the original user STASHmaster file with your new one containing the additional tracer(s).

3. Initialise your tracer(s)

Now you need to initialise your tracer. By placing it in a STASHmaster file which the UM reads, as a tracer is a prognostic field, it will need to be initialised to a value in the model start dump (which is done by the reconfiguration step). To set this go to Model Selection → Atmosphere → STASH → Initialisation of User Prognostics. This will open a panel containing a table listing all the STASH items listed in all your STASHmaster files. Scroll down this list until you get to your new tracer. While the STASH number and name of the tracer (which you set in your STASHmaster file) is present, all other columns will be blank.

The simplest options are either to set the Option column to 3 (which sets the field to zero) or to 6 and then give a value to set the field to in the If 6: CONSTANT column. In either case this will set every single gridcell to be the same value. You can, if needed, make up an ancillary file containing an initial condition if you required there to be spatial variation in your field (e.g. the ukca ozone field must always be initialised to an approximate initial condition in this way). This can be done using Xancil. Xancil will be covered in more detail in the adding new emissions tutorial.

4. Tell the UMUI about your new tracer

Unfortunately you cannot edit the UMUI directly to add-in your new tracer(s), and instead you must use a hand-edit. This is a script which run when you click the Process button, and what it does is to directly make changes to one or more of the scripts that is held in your $HOME/umui_jobs/jobid directory (you can think of the UMUI as making indirect changes), and it is these scripts which are copied across to the supercomputer when you click Submit.

If you go to your $HOME/umui_jobs/jobid directory and view the SIZES script, you will see that it contains the entries

TR_UKCA=72,

and

TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0,
0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,1,1,

TR_UKCA is the number of UKCA tracers, and TC_UKCA is a list of which tracers are on or not (1 being on, 0 being off). If you were to go through the TC_UKCA list and add-up all the 1s you would find that they add-up to 72, and that you would only have a 1 where you have a corresponding number in the user STASHmaster file.

You will need to make up a new list. However, rather than you having to put the 1 in the correct place by hand (not easy to do!), there is the make_tracer_list script on PUMA which is located in

/home/ukca/bin/make_tracer_list

This script is run on a STASHmaster file. If this script is run on the edited user STASHmaster file (which has tracer 65 included) the output is

$ make_tracer_list UKCA_Tr_StratTrop.prestash
 TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0,
 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0,
 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
 0,0,0,0,0,0,0,1,1,
 TR_UKCA=73,

(with the changes from before highlighted in blue). You will now need to add this data into the SIZES script using a hand-edit.

Hand-edits use the ed text editor, which can be run in a batch mode. We will need to make a script (e.g. add_UKCA_Tr_StratTrop.ed) which contains the following

ed SIZES<<\EOF
/TC_UKCA=/
d
d
d
d
d
i
 TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0,
 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0,
 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
 0,0,0,0,0,0,0,1,1,
.
w
q
EOF

ed SIZES<<\EOF
/TR_UKCA=/
d
i
 TR_UKCA=73,
.
w
q
EOF

The first block tells ed to search for the line TC_UKCA= and the delete this line and the next 4 lines, before inserting the text (i.e. this replaces the block in SIZES with the text here). The second block does the same but for the TR_UKCA value, hence only needed to delete 1 line.

Now, in the UMUI we go to Model Selectiom → Input/Output Control and Resource → User hand edit files. Put the full path to this file at the end of the list in the table and put a Y in the Include Y/N column.

Task 4.1

TASK4.1: Add in two new tracers in to slots 64 and 65. The tracer in slot 64 will be called ALICE and the tracer in slot 65 will be called BOB.

---

Written by Luke Abraham 2013