Controlling UKCA tracers from vn9.0

From UKCA

Up to and including UM version 8.6, tracers were controlled by setting values in a 150 element array tc_ukca in the SIZES file. The UMUI set this up for existing chemistry schemes but for new chemistry schemes or if you wish to add/remove tracers from an existing scheme, a hand edit is needed. With the introduction of Rose, it was no longer possible to generate the tc_ukca array in the GUI and a different approach was needed. This page explains the new approach. Note that from 9.1 this approach also controls the non-transported prognostics.

Option codes - an introduction

In the STASHmaster_A file, for every variable there is a 30 digit number known as the option code. For example take stash item 0.152, River direction.

1|    1 |    0 |  152 |RIVER DIRECTION                     |
2|    3 |    0 |    1 |   23 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
3| 000000000000300000000000000000 | 00000000000000000001 |    3 |
4|    1 |    2 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 1906 |    0 |  129 |    0 |    0 |    0 | 9999 |  000 |

The option code is in line 3 of this record. The option code numbers are labelled from right to left as n30n29....n2n1. In the above record all option code entries are zero except n18 which is 3. This means that this option is only available if the river routing scheme is used. For a full list of option codes see Appendix C "STASHmaster File Definition" in UMDP C4 "Storage Handling And Diagnostic System (STASH)" from http://collab.metoffice.gov.uk/twiki/bin/view/Support/Umdp

If an option code is all zeros then it is always ON. It is important to note that the option codes can have different meanings for each section of the UM.

How UKCA option codes control which tracers are on

The routine which controls which UKCA tracers are on is in the UKCA subdirectory and called tstmsk_ukca.F90. The purpose of this subroutine is to return a logical value which is true if the tracer is on and false if it is off.

The code takes as input the 30 option codes n1,n2,n3 etc and uses these, in combination with the UKCA switches in the ukca_options module to decide which tracers should be on.

  1. If the option code is all zeros, the item is always available (to preserve compatibility with other sections).
  2. If the option code is non zero and UKCA is not on then the item is never available.
  3. the code then checks the value of n30.
    1. If n30=0 then whether this tracer is enabled depends on the chemistry scheme in use. The code then tests the value of a specific option code depending on the chemistry scheme. If the option code for the active chemistry is zero, then the tracer is off. If it is 1 then is on. If the option code is 2 then it is only on when using the extension to the chemistry scheme for aerosol modelling.
    2. If n30=1 then whether this tracer is enabled depends on the value of l_ukca_mode and imode_setup. If GLOMAP-mode is off, the tracer is off. If it is on, then it checks n1 if imode_setup=1 and n2 if imode_setup=2. If the tested option is 0, the tracer is off, if it is 1 then the tracer is on. Note at present only imode setups 1 and 2 are supported.

This is the list of which option codes are tested for which chemistry schemes.

  • n1 = age of air.
  • n2 = BE Tropospheric
  • n3 = BE RAQ
  • n4 = NR TropIsop
  • n5 = NR StratTrop
  • n6 = NR Strat

Adding or deleting a tracer from a chemistry/aerosol set up

To add/remove a tracer from a pre-existing chemistry or aerosol scheme, simply change the option code in STASHmaster_A for the chemistry scheme in question. So if for example you wanted to add tracer 61 to the BE tropospheric chemistry scheme, you would set option n2 to 1 for stashcode 3.061.

Adding tracers to a complete new chemistry or aerosol scheme

  1. Pick an unused option code to use - for example n7 at the moment.
  2. Work out which tracers you need to be on for the new scheme and set the new option code for them to 1 (or 2 if it is part of an optional aerosol chemistry extension)
  3. Add the new option code to the relevant CASE statement in tstmsk_ukca.F90