UKCA Chemistry and Aerosol Tutorial 4

Back to UKCA Chemistry and Aerosol Tutorials

What you will do in this tutorial

In this tutorial you will learn how to make the required changes in the UMUI and in UKCA to include new chemical tracers (although the UMUI steps also count when adding new aerosol or passive tracers). As you learn how to do this you will add two new tracers to the UKCA tutorial job you have already been running.

You will first learn how to make new tracers in the UMUI, before learning how to then use these tracers in UKCA.

Task 4.1: Make slots for two new tracers

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. You should also output these two tracers through the pa/UPA stream in STASH as daily means.

Note: If you were unable to successfully complete Task 3.1, then please take a copy of the b job from the Tutorial experiment (Tutorial: solution to Task 3.1 - outputting a diagnostic) and work from there, as this will allow you to only make the changes required for this task.

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.

You will have learned how to make UM branches in the NCAS-CMS FCM Tutorial. However, now you should use um_tr as the source of your branch.

For example, first you should make a ticket on the UM Trac pages (login required) and then make the branch like so

fcm branch-create --type dev -k ticket_number your_branch_name fcm:um_tr@vn8.4

before checking-out your branch by

fcm checkout fcm:um_br/dev/userid/vn8.4_your_branch_name

More information on FCM can be found at the NCAS-CMS FCM pages.

During this tutorial you will be tasked to add in two new tracers into your UM branch.

Part 1. Adding a tracer into the UMUI

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.4_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 370:

      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   ',  &
         'Nuc_SOL_ND','Nuc_SOL_SU','Ait_SOL_ND','Ait_SOL_SU','Ait_SOL_BC',  &
         'Ait_SOL_OC','Acc_SOL_ND','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  &
         'Acc_SOL_SS','Acc_SOL_DU','Cor_SOL_ND','Cor_SOL_SU','Cor_SOL_BC',  &
         'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','Ait_INS_ND','Ait_INS_BC',  &
         'Ait_INS_OC','Acc_INS_ND','Acc_INS_DU','Cor_INS_ND','Cor_INS_DU',  &
         'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_SO','Ait_SOL_SO','Acc_SOL_SO',  &
         'Cor_SOL_SO','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
         'Nuc_SOL_ND','Nuc_SOL_SU','Ait_SOL_ND','Ait_SOL_SU','Ait_SOL_BC',  &
         'Ait_SOL_OC','Acc_SOL_ND','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  & !110
         'Acc_SOL_SS','Acc_SOL_DU','Cor_SOL_ND','Cor_SOL_SU','Cor_SOL_BC',  &
         'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','Ait_INS_ND','Ait_INS_BC',  & !120
         'Ait_INS_OC','Acc_INS_ND','Acc_INS_DU','Cor_INS_ND','Cor_INS_DU',  &
         'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_SO','Ait_SOL_SO','Acc_SOL_SO',  & !130
         'Cor_SOL_SO','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,         SO: 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.

We can relate this back to the nm_spec array above. The following section of that array gives the CheST/StratTrop chemical species in black. Red species should be avoided as (in general working) they may cause a clash some current settings. Species in green are not currently used by any scheme and so can be over-written (although they may be used in future).

        '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), although any of the green tracers would do just as well.

You should not make any code changes to ukca_setd1defs.F90 at this time. If you do so you will have problems performing the fcm merge step later in this tutorial.

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 the full path to a file that describes the UKCA tracers that you are using (in this tutorial it is called UKCA_Tr_StratTropAeroMODE.prestash). Take a copy (using cp) of this file to your local directory 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).

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 (option 7) 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. If these fields existed in the start dump you are providing then you could set this option to 1.

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 an entry similar to, e.g.

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,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0,1,0,0,0,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,0,1,1,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,1,1,

TC_UKCA is a list of which tracers are on or not (1 being on, 0 being off). If, in this example, you were to go through the TC_UKCA list and add-up all the 1s you would find that they add-up to 104, and that you would only have a 1 where you have a corresponding number in the user STASHmaster file. Of the 104 UKCA tracers in use, two of them (numbers 149 and 150) are diagnostic tracers and are not considered by the chemistry scheme itself. Also, the H2O field used by UKCA comes from the UM's specific humidity field and so is not set in this list. (Note: in older UM versions there is also the TR_UKCA variable, which is the number of UKCA tracers.)

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_StratTropMODE.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,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0,1,0,0,0,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,0,1,1,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,1,1,

(with the change 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_StratTropAeroMODE.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,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0,1,0,0,0,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,0,1,1,1,0,0,0,0,1,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

This 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).

You will need to make this file executable so that the UM can run it. To do this, in the directory where the file exists do

chmod a+rx add_UKCA_Tr_StratTropAeroMODE.ed

Now, in the UMUI we go to Model Selection → 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.

Solution to Task 4.1: Make slots for two new tracers

Please see this page for a solution to Task 4.1

Task 4.2: Add these two new tracers to UKCA

TASK4.2: Make the required code changes so that your ALICE and BOB tracers are now specified in the UKCA CheST/StratTrop scheme. You should set the conversion factor for each of these to 1.0.

Note: If you were unable to successfully complete Task 4.1 above, then please take a copy of the c job from the Tutorial experiment (Tutorial: solution to Task 4.1 - adding new chemical tracers to the UMUI) and work from there, as this will allow you to only make the changes required for this task.

Part 2. Adding new a new chemical tracer to UKCA

Now that you have created the new tracer(s) in the UM/UMUI, you can then tell UKCA to use this tracer slot to transport round a chemical species. To do this you will need to edit the UKCA source code.

FCM branches and merging

Before we can do this we need to check and see if there are any possible conflicts that may arise by making these changes. If you go to the FCM Atmosphere panel at Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration you can view the current branches used by this job, e.g.:

fcm:um_br/dev/jwalton/vn8.4_fix_endgame_grib_cloud_UKMO/src  12122  Y
fcm:um_br/dev/jwalton/vn8.4_iceberg_calving_UKMO/src         12116  Y
fcm:um_br/dev/jwalton/vn8.4_reinstate_ISCCP_UKMO/src         12111  Y
fcm:um_br/dev/luke/vn8.4_UKCA_Tutorials/src                  14638  Y
fcm:um_br/pkg/Config/vn8.4_ncas/src                          12550  Y

Most of these branches will not clash with our required changes. However, the fcm:um_br/dev/luke/vn8.4_UKCA_Tutorials/src (at revision 14638) branch will, as it directly changes parts of the chemistry scheme routines that we want to use. Before we can make our code changes we must first make a copy of this branch. While ideally you should be able to make a new branch and edit the source-code as is, often you need to make changes to an existing branch. The recommended way to do this is to make a new branch and then merge in the clashing branch with your own, then stop using the clashing branch in the UMUI.

You should already have made a new branch that you used to find the free tracer slots. Now cd into the highest-level directory of the branch, which contains

CodeOwners.txt  COPYRIGHT.txt  src/

From here you will need to merge in the vn8.4_UKCA_Tutorials branch. Do

fcm merge fcm:um_br/dev/luke/vn8.4_UKCA_Tutorials

You will then be asked to confirm the revision number (the latest, 14638, is the one used in the UMUI). Confirm by pressing return. Now you will be asked if you wish to go ahead with the merge. Confirm this by typing y and pressing return. This will now merge in all the changes from the UM trunk that the vn8.4_UKCA_Tutorials contains into your branch.

In the terminal, this will have the following output:

$ fcm merge fcm:um_br/dev/luke/vn8.4_UKCA_Tutorials
Eligible merge(s) from /UM/branches/dev/luke/vn8.4_UKCA_Tutorials@14672: 14638 14260 14259 14258 14257 14256 14255 14254
Enter a revision (or just press <return> for "14638"): 
--------------------------------------------------------------------------------
Merge: /UM/branches/dev/luke/vn8.4_UKCA_Tutorials@14638
 c.f.: /UM/trunk@11592
-------------------------------------------------------------------------dry-run
--- Merging r11593 through r14638 into '.':
U    src/control/top_level/atmos_physics1.F90
U    src/control/top_level/atm_step_4A.F90
U    src/control/top_level/atm_step.F90
U    src/control/top_level/um_input_control_mod.F90
U    src/include/common/version.h
U    src/include/common/clfhist.h
U    src/include/constant/chsunits.h
U    src/include/data/cenvirdt.h
U    src/script/control/qsatmos
U    src/atmosphere/UKCA/ukca_setd1defs.F90
U    src/atmosphere/UKCA/ukca_calcnucrate.F90
U    src/atmosphere/UKCA/asad_flux_dat.F90
U    src/atmosphere/UKCA/asad_bimol.F90
U    src/atmosphere/UKCA/asad_trimol.F90
U    src/atmosphere/UKCA/ukca_fastjx.F90
U    src/atmosphere/UKCA/ukca_radaer_struct_mod.F90
U    src/atmosphere/UKCA/ukca_main1-ukca_main1.F90
U    src/atmosphere/UKCA/ukca_radaer_compute_aod.F90
U    src/atmosphere/UKCA/ukca_aero_step.F90
U    src/atmosphere/UKCA/fastjx_specs.F90
U    src/atmosphere/UKCA/ukca_mode_setup.F90
U    src/atmosphere/UKCA/ukca_abdulrazzak_ghan.F90
U    src/atmosphere/UKCA/ukca_surfddr.F90
A    src/atmosphere/UKCA/ukca_scavenging_mod.F90
U    src/atmosphere/UKCA/ukca_coagwithnucl.F90
U    src/atmosphere/UKCA/ukca_d1_defs.F90
U    src/atmosphere/UKCA/asad_chem_flux_diags.F90
U    src/atmosphere/UKCA/ukca_rainout.F90
U    src/atmosphere/UKCA/ukca_mode_ems_um_mod.F90
U    src/atmosphere/UKCA/ukca_emission_ctl.F90
U    src/atmosphere/UKCA/ukca_activate.F90
U    src/atmosphere/UKCA/ukca_calc_drydiam.F90
U    src/atmosphere/UKCA/ukca_volume_mode.F90
U    src/atmosphere/UKCA/ukca_radaer_band_average.F90
U    src/atmosphere/UKCA/ukca_radaer_init-ukca1.F90
U    src/atmosphere/UKCA/asad_spimpmjp.F90
U    src/atmosphere/UKCA/ukca_aero_ctl.F90
U    src/atmosphere/UKCA/ukca_chem_strattrop.F90
U    src/atmosphere/UKCA/ukca_light.F90
U     src/atmosphere/UKCA/ukca_chem_tropisop.F90
U    src/atmosphere/UKCA/ukca_radaer_lut_mod.F90
U    src/atmosphere/UKCA/ukca_radaer_read_precalc.F90
U    src/atmosphere/UKCA/ukca_radaer_precalc_mod.F90
U    src/atmosphere/UKCA/ukca_setup_indices.F90
U    src/atmosphere/UKCA/ukca_radaer_read_luts.F90
U    src/atmosphere/UKCA/ukca_radaer_set_aerosol_field.F90
U    src/atmosphere/UKCA/ukca_init.F90
U    src/atmosphere/UKCA/ukca_option_mod.F90
A    src/atmosphere/UKCA/ukca_mode_check_artefacts_mod.F90
U    src/atmosphere/convection/convec2_mod-6a.F90
U    src/atmosphere/convection/glue_conv-gconv5a.F90
U    src/atmosphere/convection/ni_conv_ctl.F90
U    src/atmosphere/convection/convec2-conv24a.F90
U    src/atmosphere/radiation_control/rad_input_mod.F90
U    src/atmosphere/radiation_control/r2_lwrad3z.F90
U    src/atmosphere/radiation_control/r2_re_mrf_umist.F90
U    src/atmosphere/radiation_control/swrdiag_mod.F90
U    src/atmosphere/radiation_control/set_swdiag_logic.F90
U    src/atmosphere/radiation_control/diagnostics_lw.F90
U    src/atmosphere/radiation_control/init_swdiag_logic.F90
U    src/atmosphere/radiation_control/allocate_sw_diag.F90
U    src/atmosphere/radiation_control/r2_cloud_level_diag.F90
U    src/atmosphere/radiation_control/deallocate_swdiag.F90
U    src/atmosphere/radiation_control/deallocate_lwdiag.F90
U    src/atmosphere/radiation_control/lwrdiag_mod.F90
U    src/atmosphere/radiation_control/r2_swrad3z.F90
U    src/atmosphere/radiation_control/allocate_lw_diag.F90
U    src/atmosphere/radiation_control/fill_missing_data_sw.F90
U    src/atmosphere/radiation_control/r2_set_cloud_field.F90
U    src/atmosphere/radiation_control/set_lwdiag_logic.F90
U    src/atmosphere/radiation_control/fill_missing_data_lw.F90
U    src/atmosphere/radiation_control/diagnostics_sw.F90
U    src/atmosphere/radiance_core/radiance_calc.F90
-------------------------------------------------------------------------dry-run
Would you like to go ahead with the merge?
Enter "y" or "n" (or just press <return> for "n"): y
Merge succeeded.

Now if you type fcm status you can see which routines have been changed:

$ fcm status
M       src/control/top_level/atmos_physics1.F90
M       src/control/top_level/atm_step_4A.F90
M       src/control/top_level/atm_step.F90
M       src/control/top_level/um_input_control_mod.F90
M       src/include/common/version.h
M       src/include/common/clfhist.h
M       src/include/constant/chsunits.h
M       src/include/data/cenvirdt.h
M       src/script/control/qsatmos
M       src/atmosphere/UKCA/ukca_setd1defs.F90
M       src/atmosphere/UKCA/ukca_calcnucrate.F90
M       src/atmosphere/UKCA/asad_flux_dat.F90
M       src/atmosphere/UKCA/asad_bimol.F90
M       src/atmosphere/UKCA/asad_trimol.F90
M       src/atmosphere/UKCA/ukca_fastjx.F90
M       src/atmosphere/UKCA/ukca_radaer_struct_mod.F90
M       src/atmosphere/UKCA/ukca_main1-ukca_main1.F90
M       src/atmosphere/UKCA/ukca_radaer_compute_aod.F90
M       src/atmosphere/UKCA/ukca_aero_step.F90
M       src/atmosphere/UKCA/fastjx_specs.F90
M       src/atmosphere/UKCA/ukca_mode_setup.F90
M       src/atmosphere/UKCA/ukca_abdulrazzak_ghan.F90
M       src/atmosphere/UKCA/ukca_surfddr.F90
A  +    src/atmosphere/UKCA/ukca_scavenging_mod.F90
M       src/atmosphere/UKCA/ukca_coagwithnucl.F90
M       src/atmosphere/UKCA/ukca_d1_defs.F90
M       src/atmosphere/UKCA/asad_chem_flux_diags.F90
M       src/atmosphere/UKCA/ukca_rainout.F90
M       src/atmosphere/UKCA/ukca_emission_ctl.F90
M       src/atmosphere/UKCA/ukca_mode_ems_um_mod.F90
M       src/atmosphere/UKCA/ukca_activate.F90
M       src/atmosphere/UKCA/ukca_calc_drydiam.F90
M       src/atmosphere/UKCA/ukca_volume_mode.F90
M       src/atmosphere/UKCA/ukca_radaer_band_average.F90
M       src/atmosphere/UKCA/ukca_radaer_init-ukca1.F90
M       src/atmosphere/UKCA/asad_spimpmjp.F90
M       src/atmosphere/UKCA/ukca_aero_ctl.F90
M       src/atmosphere/UKCA/ukca_chem_strattrop.F90
M       src/atmosphere/UKCA/ukca_light.F90
M       src/atmosphere/UKCA/ukca_chem_tropisop.F90
M       src/atmosphere/UKCA/ukca_radaer_lut_mod.F90
M       src/atmosphere/UKCA/ukca_radaer_read_precalc.F90
M       src/atmosphere/UKCA/ukca_radaer_precalc_mod.F90
M       src/atmosphere/UKCA/ukca_setup_indices.F90
M       src/atmosphere/UKCA/ukca_radaer_read_luts.F90
M       src/atmosphere/UKCA/ukca_radaer_set_aerosol_field.F90
M       src/atmosphere/UKCA/ukca_init.F90
M       src/atmosphere/UKCA/ukca_option_mod.F90
A  +    src/atmosphere/UKCA/ukca_mode_check_artefacts_mod.F90
M       src/atmosphere/convection/convec2_mod-6a.F90
M       src/atmosphere/convection/glue_conv-gconv5a.F90
M       src/atmosphere/convection/ni_conv_ctl.F90
M       src/atmosphere/convection/convec2-conv24a.F90
M       src/atmosphere/radiation_control/rad_input_mod.F90
M       src/atmosphere/radiation_control/r2_lwrad3z.F90
M       src/atmosphere/radiation_control/r2_re_mrf_umist.F90
M       src/atmosphere/radiation_control/swrdiag_mod.F90
M       src/atmosphere/radiation_control/set_swdiag_logic.F90
M       src/atmosphere/radiation_control/diagnostics_lw.F90
M       src/atmosphere/radiation_control/init_swdiag_logic.F90
M       src/atmosphere/radiation_control/allocate_sw_diag.F90
M       src/atmosphere/radiation_control/r2_cloud_level_diag.F90
M       src/atmosphere/radiation_control/deallocate_swdiag.F90
M       src/atmosphere/radiation_control/deallocate_lwdiag.F90
M       src/atmosphere/radiation_control/lwrdiag_mod.F90
M       src/atmosphere/radiation_control/r2_swrad3z.F90
M       src/atmosphere/radiation_control/allocate_lw_diag.F90
M       src/atmosphere/radiation_control/fill_missing_data_sw.F90
M       src/atmosphere/radiation_control/r2_set_cloud_field.F90
M       src/atmosphere/radiation_control/set_lwdiag_logic.F90
M       src/atmosphere/radiation_control/fill_missing_data_lw.F90
M       src/atmosphere/radiation_control/diagnostics_sw.F90
M       src/atmosphere/radiance_core/radiance_calc.F90

Before you make any further changes you should commit these changes. Do this now by typing the command

fcm commit

press return and put in an appropriate comment when asked if you want to commit this branch and type y and then press return again.

Now you need to add this branch into the UMUI, and turn off the original vn8.4_UKCA_Tutorial_Solns branch. We will initially use a working copy.

• Go to the Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration' panel, scroll down the table and change the Y next to the fcm:um_br/dev/luke/vn8.4_UKCA_Tutorials/src branch to N.
• Add your own branch to this table. The revision URL will be off the form
  fcm:um_br/dev/your PUMA username/vn8.4_your_branch_name/src
  Leave the revision number column empty and put a N in the Use Y/N column.
• Turn on the button which says Include modifications from a user working copy and put the path to your source directory on PUMA in this box (e.g. something like /home/your PUMA username/.../vn8.4_your_branch_name/src etc.). Once we are happy that this code is working we can turn off the option to run from this copy, and turn on the option to run from the respository.

Using a working copy means that FCM will pick up any changes that you have made to your branch without you needed to fcm commit it.

Note: In general, you may, or may not, need to do this step. It is possible that you can make your edits on a fresh branch which contains only the UM trunk. However, it is likely that you will have conflicts of a sort with an existing branch, especially if the job you are using contains a large number (or a number of large) branches.

Reviewing your code changes and committing

After you have made code changes you will want to commit these to the repository using the

fcm commit

command. At this stage you may find it helpful to review those code changes using

fcm diff -g

which will bring up a xxdiff window comparing your working copy with the last version you checked in. It will highlight what changes have been made so you should be able to see more easily if there is a mistake. The

fcm status 

command will also give a listing of the changed files. If you have added a new file you will also need to

fcm add name_of_file

prior to fcm commit-ing it.

Frequent committing of code to the FCM respository is encouraged.

You don't even need to commit working code, as committing is a useful way of backing-up code changes.

Editing the advected tracer list

To edit the UKCA source code, go to your branch and cd into

 src/atmosphere/UKCA/

This directory contains the majority of the UKCA specfic code, and contains over 200 files.

Note: When we found which tracer slot to use, we did so consulting the nm_spec array in the ukca_setd1defs.F90 routine. Due to the changes you have just merged in, nm_spec can now be found around line 130 in the ukca_init.F90 routine. After version 8.4 nm_spec will now be found in ukca_init.F90.

You should open ukca_init.F90 and edit the nm_spec array so that the slot you have chosen now contains the name of your tracer. The nm_spec array tells UKCA what slot in the 150 reserved tracers is used for which transported chemical species.

Note: remember that this name is case sensitive, and be wary of tabs as these should not be used in Fortran programs. Also remember that the string length for a UKCA species is 10 characters.

Increase the number of tracers to be used

Also in ukca_setd1defs.F90 you will find code blocks which set values for various parameters depending on the scheme used. In this example you will need to scroll down to the section which defines the CheST/StratTrop chemistry, which is located in the Stratospheric Chemistry section. The following IF block tests against L_ukca_strattrop (i.e. CheST/StratTrop, the chemistry scheme used) and L_ukca_achem (which determines whether or not you require the additional chemistry used to drive the GLOMAP-mode aerosol scheme). The settings for this particular job have both of these logicals as .TRUE..

Inside this block you will find the following lines

            n_aero_tracers = 12
            n_chem_tracers = 71         ! No chem tracers

whether or not you are using the aerosol chemistry additions, as the base CheST/StratTrop chemistry is the same. You should increase the value of n_chem_tracers number by the number of chemical tracers that you are adding in the correct section of the IF block. If you are adding to a different chemistry scheme then you will need to make those changes accordingly.

Note: If you are using an older UM version which also requires the value of the TR_UKCA variable to be set (the total number of section 34 tracers which are switched on), you will find that this number may be different than that specified in the value of TR_UKCA which is set in the SIZES script. This is due to two reasons. The first is that there can be diagnostic tracers in section 34 (e.g. Age of Air, or Passive O3) which will appear in SIZES but not in the value of n_chem_tracers in ukca_setd1defs.F90. The second is that the UKCA H2O field is advected in section 0 and not section 34, and so will need to be included in ukca_setd1defs.F90, but is not needed in SIZES.

Editing the Chemistry Scheme Specification

For this example we are using the CheST/StratTrop chemistry scheme with the aerosol chemistry additions (as GLOMAP-mode is also being used), so we will need to edit the specification of this scheme so that it knows that it is using new tracer(s). The chemistry schemes are specified in the files called ukca_chem_scheme.F90. So we should open the file called ukca_chem_strattrop.F90.

The UKCA chemistry schemes are held within Fortran modules and are defined by different derived types which hold the specification of the different components required to describe the scheme. Looking through this file you will find two blocks which hold the different species used, called chch_defs_strattrop_chem (which is used when you are running chemistry-only) and chch_defs_strattrop_aer (which is used when you are running with the GLOMAP-mode aerosol scheme coupled to the chemistry). As we are currently using chemistry and aerosol, we will only need to edit the chch_defs_strattrop_aer specification. This currently looks like

TYPE(CHCH_T), PUBLIC :: chch_defs_strattrop_aer(1:87)=(/             &
!   1
chch_t(  1,'O(3P)     ',  1,'TR        ','Ox        ',  0,  0,  0),  & 
!   2
chch_t(  2,'O(1D)     ',  1,'SS        ','Ox        ',  0,  0,  0),  & 
!   3 DD: 1,WD: 1,
chch_t(  3,'O3        ',  1,'TR        ','Ox        ',  1,  1,  0),  & 
!   4
chch_t(  4,'N         ',  1,'TR        ','NOx       ',  0,  0,  0),  & 
!   5 DD: 2,
chch_t(  5,'NO        ',  1,'TR        ','NOx       ',  1,  0,  0),  & 
!   6 DD: 3,WD: 2,
chch_t(  6,'NO3       ',  1,'TR        ','NOx       ',  1,  1,  0),  & 
!   7 DD: 4,      EM: 1
chch_t(  7,'NO2       ',  1,'TR        ','NOx       ',  1,  0,  1),  & 
!   8 DD: 5,WD: 3,
chch_t(  8,'N2O5      ',  1,'TR        ','          ',  1,  1,  0),  & 
!   9 DD: 6,WD: 4,
chch_t(  9,'HO2NO2    ',  1,'TR        ','          ',  1,  1,  0),  & 
!  10 DD: 7,WD: 5,
chch_t( 10,'HONO2     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  11 DD: 8,WD: 6,
chch_t( 11,'H2O2      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  12 EM: 2
chch_t( 12,'CH4       ',  1,'TR        ','          ',  0,  0,  2),  & 
!  13 DD: 9,      EM:  3
chch_t( 13,'CO        ',  1,'TR        ','          ',  1,  0,  3),  & 
!  14 DD:10,WD: 7,EM:  4
chch_t( 14,'HCHO      ',  1,'TR        ','          ',  1,  1,  4),  & 
!  15       WD: 8,
chch_t( 15,'MeOO      ',  1,'TR        ','          ',  0,  1,  0),  & 
!  16 DD:11,WD: 9,
chch_t( 16,'MeOOH     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  17
chch_t( 17,'H         ',  1,'TR        ','HOx       ',  0,  0,  0),  & 
!  18
chch_t( 18,'H2O       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  19
chch_t( 19,'OH        ',  1,'TR        ','HOx       ',  0,  0,  0),  & 
!  20       WD:10,
chch_t( 20,'HO2       ',  1,'TR        ','HOx       ',  0,  1,  0),  & 
!  21
chch_t( 21,'Cl        ',  1,'TR        ','Clx       ',  0,  0,  0),  & 
!  22
chch_t( 22,'Cl2O2     ',  1,'TR        ','Clx       ',  0,  0,  0),  & 
!  23
chch_t( 23,'ClO       ',  1,'TR        ','Clx       ',  0,  0,  0),  & 
!  24
chch_t( 24,'OClO      ',  1,'TR        ','          ',  0,  0,  0),  & 
!  25
chch_t( 25,'Br        ',  1,'TR        ','Brx       ',  0,  0,  0),  & 
!  26
chch_t( 26,'BrO       ',  1,'TR        ','Brx       ',  0,  0,  0),  & 
!  27
chch_t( 27,'BrCl      ',  1,'TR        ','          ',  0,  0,  0),  & 
!  28       WD:11,
chch_t( 28,'BrONO2    ',  1,'TR        ','          ',  0,  1,  0),  & 
!  29
chch_t( 29,'N2O       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  30 DD:12,WD:12,
chch_t( 30,'HCl       ',  1,'TR        ','          ',  1,  1,  0),  & 
!  31 DD:13,WD:13,
chch_t( 31,'HOCl      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  32 DD:14,WD:14,
chch_t( 32,'HBr       ',  1,'TR        ','          ',  1,  1,  0),  & 
!  33 DD:15,WD:15,
chch_t( 33,'HOBr      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  34       WD:16,
chch_t( 34,'ClONO2    ',  1,'TR        ','          ',  0,  1,  0),  & 
!  35
chch_t( 35,'CFCl3     ',  1,'TR        ','          ',  0,  0,  0),  & 
!  36
chch_t( 36,'CF2Cl2    ',  1,'TR        ','          ',  0,  0,  0),  & 
!  37
chch_t( 37,'MeBr      ',  1,'TR        ','          ',  0,  0,  0),  & 
!  38 DD:16,WD:17,
chch_t( 38,'HONO      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  39             EM: 5
chch_t( 39,'C2H6      ',  1,'TR        ','          ',  0,  0,  1),  & 
!  40
chch_t( 40,'EtOO      ',  1,'TR        ','          ',  0,  0,  0),  & 
!  41 DD:17,WD:18,
chch_t( 41,'EtOOH     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  42 DD:18,      EM: 6
chch_t( 42,'MeCHO     ',  1,'TR        ','          ',  1,  0,  1),  & 
!  43
chch_t( 43,'MeCO3     ',  1,'TR        ','          ',  0,  0,  0),  & 
!  44 DD:19,
chch_t( 44,'PAN       ',  1,'TR        ','          ',  1,  0,  0),  & 
!  45             EM: 7
chch_t( 45,'C3H8      ',  1,'TR        ','          ',  0,  0,  1),  & 
!  46
chch_t( 46,'n-PrOO    ',  1,'TR        ','          ',  0,  0,  0),  & 
!  47
chch_t( 47,'i-PrOO    ',  1,'TR        ','          ',  0,  0,  0),  & 
!  48 DD:20,WD:19,
chch_t( 48,'n-PrOOH   ',  1,'TR        ','          ',  1,  1,  0),  & 
!  49 DD:21,WD:20,
chch_t( 49,'i-PrOOH   ',  1,'TR        ','          ',  1,  1,  0),  & 
!  50 DD:22,
chch_t( 50,'EtCHO     ',  1,'TR        ','          ',  1,  0,  0),  & 
!  51
chch_t( 51,'EtCO3     ',  1,'TR        ','          ',  0,  0,  0),  & 
!  52             EM: 8
chch_t( 52,'Me2CO     ',  1,'TR        ','          ',  0,  0,  1),  & 
!  53
chch_t( 53,'MeCOCH2OO ',  1,'TR        ','          ',  0,  0,  0),  & 
!  54 DD:23,WD:21,
chch_t( 54,'MeCOCH2OOH',  1,'TR        ','          ',  1,  1,  0),  & 
!  55 DD:24,
chch_t( 55,'PPAN      ',  1,'TR        ','          ',  1,  0,  0),  & 
!  56
chch_t( 56,'MeONO2    ',  1,'TR        ','          ',  0,  0,  0),  & 
!  57             EM: 9 
chch_t( 57,'C5H8      ',  1,'TR        ','          ',  0,  0,  1),  & 
!  58
chch_t( 58,'ISO2      ',  1,'TR        ','          ',  0,  0,  0),  & 
!  59 DD:25,WD:22,
chch_t( 59,'ISOOH     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  60 DD:26,WD:23,
chch_t( 60,'ISON      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  61 DD:27,
chch_t( 61,'MACR      ',  1,'TR        ','          ',  1,  0,  0),  & 
!  62
chch_t( 62,'MACRO2    ',  1,'TR        ','          ',  0,  0,  0),  & 
!  63 DD:28,WD:24,
chch_t( 63,'MACROOH   ',  1,'TR        ','          ',  1,  1,  0),  & 
!  64 DD:29,      
chch_t( 64,'MPAN      ',  1,'TR        ','          ',  1,  0,  0),  & 
!  65 DD:30,WD:25,
chch_t( 65,'HACET     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  66 DD:31,WD:26,
chch_t( 66,'MGLY      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  67 DD:32,
chch_t( 67,'NALD      ',  1,'TR        ','          ',  1,  0,  0),  & 
!  68 DD:33,WD:27,
chch_t( 68,'HCOOH     ',  1,'TR        ','          ',  1,  1,  0),  & 
!  69 DD:34,WD:28,
chch_t( 69,'MeCO3H    ',  1,'TR        ','          ',  1,  1,  0),  & 
!  70 DD:35,WD:29,
chch_t( 70,'MeCO2H    ',  1,'TR        ','          ',  1,  1,  0),  & 
!  71
chch_t( 71,'H2        ',  1,'TR        ','          ',  0,  0,  0),  & 
!  72 DD:36,WD:30,
chch_t( 72,'MeOH      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  73
chch_t( 73,'CO2       ',  1,'CT        ','          ',  0,  0,  0),  & 
!  74
chch_t( 74,'O2        ',  1,'CT        ','          ',  0,  0,  0),  & 
!  75
chch_t( 75,'N2        ',  1,'CT        ','          ',  0,  0,  0),  & 
!  76
chch_t( 76,'DMS       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  77 DD:37,WD:31,EM:10
chch_t( 77,'SO2       ',  1,'TR        ','          ',  1,  1,  1),  & 
!  78
chch_t( 78,'H2SO4     ',  1,'TR        ','          ',  0,  0,  0),  & 
!  79
chch_t( 79,'MSA       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  80 DD:38,WD:32
chch_t( 80,'DMSO      ',  1,'TR        ','          ',  1,  1,  0),  & 
!  81 DD:39,WD:33,EM:11
chch_t( 81,'NH3       ',  1,'TR        ','          ',  1,  1,  1),  & 
!  82
chch_t( 82,'CS2       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  83
chch_t( 83,'COS       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  84
chch_t( 84,'H2S       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  85
chch_t( 85,'SO3       ',  1,'TR        ','          ',  0,  0,  0),  & 
!  86 DD:40,      EM: 12
chch_t( 86,'Monoterp  ',  1,'TR        ','          ',  1,  0,  1),  & 
!  87 DD:41,WD:34
chch_t( 87,'Sec_Org   ',  1,'TR        ','          ',  1,  1,  0)   & 
  /)

You should note that even though there are 83 chemical tracers defined, there are actually 87 species considered in this scheme, as three (CO2, O2, and N2) are constants and O(1D) is set to be in steady-state and is not transported. This is set in the 4th column of the list:

• TR = tracer
• CT = constant
• SS = steady state

The 6th and 7th columns of the list control dry and wet deposition respectively. We will cover these in more detail in the adding dry deposition of chemical species and adding wet deposition of chemical species tutorials.

You should edit this list, adding the name your tracer(s) (exactly as it is called in the nm_spec array) on at the end (remember to correctly add/remove the comma on the last line!). Make sure that the last 3 columns are all set to 0. Also remember to increase the size of the chch_defs_strattrop_chem_aer array by the number of species that you are adding.

Define conversion factors for your new tracers

The unit of the tracers is kg(species)/kg(air) (i.e. mass mixing ratio, or mmr), but inside UKCA these species are converted to volume mixing ratio (or vmr). To enable UKCA to do this you will need to add the conversion factor(s) for your new tracer(s) into the code. This is done in the ukca_constants.F90 module (Note: in UM7.3 this is done in the c_v_m.h include file).

Open this file and add the required conversion factor(s). The naming convention for these is M_species is the molecular mass of the new species in g/mol, and C_species for the converson factor from vmr to mmr (calculated as M_species/M_air, where M_air=28.97). In actuality, only the C_species listing is always required, although you may need to add the M_species value later if you are emitting into the new species that you are adding.

Tell UKCA to use these conversion factors

After you have added these in, you will need to tell UKCA to use them for your species. To do this you need to edit the ukca_cspecies.F90 module, which contains code which contructs the c_species array of conversion factors for the advected tracers. This contains a subroutine called UKCA_CALC_CSPECIES which has a long block of code that contains entries like these:

     ...
     WHERE (advt == 'MEMALD    ') c_species = c_memald
     WHERE (advt == 'MVK       ') c_species = c_mvk
     WHERE (advt == 'MVKOOH    ') c_species = c_mvkooh
     WHERE (advt == 'TOLUENE   ') c_species = c_toluene
     ...

The advt array is automatically generated by UKCA at run-time from the CHCH chemistry scheme definition you edited earlier, so your new tracer(s) will exist within it. You need to add in a new line for each of your tracers which sets the value of the c_species array to your individual C_species parameter. Add the line(s) in at the end of block.

Increase the size of JPCTR and JPSPEC

As you have changed the number of chemical species, you will need to increase the size of two integer parameters that tell UKCA how many chemical species and how many chemical tracers it should consider.

• JPSPEC is the number of chemical species used in UKCA (effectively the size of chch_defs_strattrop_chem or chch_defs_strattrop_chem, whichever is being used by the UKCA configuration you are editing)
• JPCTR is the number of chemical tracers used in UKCA (always less-than or equal-to JPSPEC, effectively the number TR in chch_defs_strattrop_chem/chch_defs_strattrop_aer, or the new value of n_chem_tracers (+ n_aero_tracers) that you set in ukca_setd1defs.F90)

These are currently set automatically by the UMUI (depending on which chemistry scheme you choose). As this cannot be edited from within the UMUI you will need to make a hand-edit to change it. The values of JPSPEC and JPCTR are set in CNTLATM. Your hand-edit should contain a block similar to the following:

ed CNTLATM<<\EOF
/JPCTR/
d
i
 JPCTR = value of (n_chem_tracers + n_aero_tracers),
.
/JPSPEC/
d
i
 JPSPEC = new size of chch_defs_strattrop_chem or chch_defs_strattrop_aer array (whichever is being used by the UKCA configuration),
.
w
q
EOF

Save this hand-edit and make it executable, and place it in the table in Model Selection → Input/Output Control and Resource → User hand edit files with a Y in the Include Y/N column.

Numerical Noise

• 

  Tracer field from the UM fieldsfile prior to inclusion in UKCA

• 

  Tracer field from the UM fieldsfile after inclusion in UKCA showing the numerical noise

• 

  Tracer field from the UM pp-file after inclusion in UKCA showing that the numerical noise is no longer evident

When you first add your tracer to the Unified Model and then view it in an output file, you will see that the field contains zeros. However, after then adapting the UKCA code to include it (but not yet including any reactions or emissions etc) you may now find that the tracer field appears to be non-zero. If you look closer at the output you will find that the values in this field are exceptionally small, usually in the range of $10^{-{\mathcal {O}}(\geq 80)}$. This is because the UKCA chemical solver will be adding a small amount of numerical noise to this field. The output files from the UM are 64-bit fieldsfiles, and if you convert these to 32-bit pp-files by e.g. using ff2pp which can be found at

/work/n02/n02/hum/bin/ff2pp

on ARCHER, and

/projects/um1/vn8.4/ibm/utils/ff2pp

on MONSooN, you will see that these artifacts are removed when converted to 32-bit. The meaningful values of the tracers (usually in the $10^{-{\mathcal {O}}(6)}$ to $10^{-{\mathcal {O}}(12)}$ range) will be unaffected.

Solution to Task 4.2: Add these two new tracers to UKCA

Please see this page for a solution to Task 4.2

---

Written by Luke Abraham 2014