UKCA Chemistry and Aerosol UMvn13.0 Tutorial 7

UKCA Chemistry and Aerosol Tutorials at UMvn13.0

Difficulty	HARD
Time to Complete	2 or more hours
Video instructions	Walkthrough (YouTube)

Remember to run mosrs-cache-password.

What you will do in this tutorial

In this tutorial you will learn how to make the required changes in Rose and in the UM to include new tracers that are transported around by the model's advection and convection schemes.

In this example we will be considering both ALICE and BOB, but for your own work you may be considering any number of new tracers.

Task 7.1: Add new tracers into Rose

TASK7.1: Add in two new tracers in to slots 498 and 499 for the StratTrop and CRI-Strat2 chemistry schemes. The tracer in slot 498 will be called ALICE and the tracer in slot 499 will be called BOB. You should initialise these tracers to 1.000000e-15. You should also output these two tracers, as well as the pressure-level equivalents, through the UPA stream in STASH as 3-hour means.

Make a branch

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. This is done in two steps, the UKCA-side changes that we already considered in Tutorial 3, and the Rose-side changes that we will do now in the UM-UKCA suite.

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

You will have learned how to make UM branches in Tutorial 3. However, now you should use um.x_tr as the source of your branch as we are making a UM branch and not a UKCA branch.

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

fcm branch-create --type dev -k ticket_number your_branch_name fcm:um.x_tr@vn13.0

(note the use of vn13.0 here rather than um13.0 previously). Now check-out your branch by

fcm checkout fcm:um.x_br/dev/[your MOSRS userid]/vn13.0_your_branch_name

More information on FCM can be found at the FCM User Guide

You should

1. ensure that you assign the ticket to yourself when you create it. The easiest way to do this is to click start work under the modify ticket option.
2. When making changes always include your ticket number and MOSRS userid in your comment when you commit to your branch to enable the changes to be easily traced back to you. The easiest way to do this is to have each comment start with #ticket_number userid.
3. Ensure that you select a Milestone of Not for builds. Usual changes should be given this as a milestone, or Hopefully. You should only change this to a particular UM release when you are working on it to commit to the trunk.

Metadata

In Rose, the GUI appearance is controlled by metadata, and it is possible to edit this metadata to add new variables to panels. We will not do this in this tutorial, but you will need to change where Rose looks for metadata, as the STASHmaster_A file, used to define the prognostic and diagnostic fields available to the UM, is also metadata.

Using your new metadata within Rose

Here you should click on the um app in Rose and change the meta setting from um-atmos/vn13.0 to

/path/to/vn13.0_your_branch_name/rose-meta/um-atmos/HEAD

e.g.

/home/ubuntu/vn13.0_ukca_tutorial_solutions/rose-meta/um-atmos/HEAD

Then click Apply and then save the suite.

Rose Changes

Include your branch for code changes

Although we haven't made any code changes yet, you will (at some point) need to include your branch in Rose so that the UKCA code changes can be picked-up and compiled. To do this go to fcm_make $\rightarrow$ env $\rightarrow$ Sources and add a new branch by clicking the plus symbol in the um_sources section. You should then put

/path/to/vn13.0_your_branch_name

e.g.

/home/ubuntu/vn13.0_ukca_tutorial_solutions

(where /path/to/vn11.8_your_branch_name means the full linux path to your branch, e.g. /home/ukcatr01/vn11.8_UKCA_Tutorials etc.) if you wish to run from a working copy, and

branches/dev/[your MOSRS userid]/vn13.0_your_branch_name

e.g.

branches/dev/lukeabraham/vn13.0_ukca_tutorial_solutions

if you want to run from the repository. You can specify specific revision numbers by putting @REV at the end of this line (where REV is the revision number, e.g. 12345 etc.).

You should NOT include your UKCA branch at this time, only your new UM branch. We will add the UKCA branch later.

Note that if you specify revision numbers you will need to change these each time you make a change and commit it. Another potential issue here is the use of a mirror for the UM code. On some systems the code is not taken directly from MOSRS, but from a local mirror of the full repository. This usually updates every 5 minutes or so, so to check whether it has updated or not, you should type the command

fcm info fcm:um.xm

and check the last committed revision. If it is the same or higher than your last revision then your code changes will be picked-up. If it is less than your revision your code changes will not be included in the compile. On the VM, this is not an issue as there is no mirror.

STASHmaster_A

In Rose-based jobs, adding new UKCA tracers is done through editing the STASHmaster_A file directly. Take a look at the STASHmaster_A file, found in

/path/to/vn13.0_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A

If you are making changes for in an older version to use in an existing suite (e.g. version 10.9) you may instead have to make changes an explicitly named version, e.g.

rose-meta/um-atmos/vn10.9/etc/stash/STASHmaster/STASHmaster_A

Additionally, if multiple branches are used by a suite, each of which has associated metadata changes, these will all need to be merged together into a single separate metadata location when used with a suite. This will need to be done manually. However, for this tutorial you are able to make all the necessary changes within your branch.

The STASHmaster_A file is large, as it contains all the possible prognostic or diagnostic STASH items. Scroll down the file until you get to section 34, and you will see how the tracers are defined. The key entries to consider are highlighted in red. All entries are fixed-width, so when editing the file, ensure not to change the spacing, otherwise you will get errors. The location of the pipe ("|") characters is also very important.

#===============================================================================
# Section 34 UKCA Chemistry
#===============================================================================
#
1|    1 |   34 |    1 |O3 MASS MIXING RATIO AFTER TIMESTEP |
2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000110000111110 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 2101 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

The meaning of these entries is:

First Line:

• 34: The STASH section, in this case Section 34, UKCA prognostics.
• 1: The STASH item, in this case, the first item in s34, ozone.
• O3 MASS MIXING RATIO AFTER TIMESTEP: The name of the field in the STASHmaster file. This can be anything descriptive, but it isn't used by the model, and is only considered in Rose (or e.g. Xconv).

Second Line:

• 2: The Space Code, which tells the UM whether the field should be held in the restart dump or not. For prognostics, this should be 2 (which means that they should be stored in the restart dump), but for diagnostics that are only passed to output files, this should be 0.

Third Line:

• 000000000000000000110000111110: These are Options Codes which determine which scheme the STASH field (i.e. tracer in this case) are valid for. These are counted from the right, n1 to n30. Only some of these are used, and have the following meaning:
  • n1: Age-of-air tracer (ageair) or aerosol tracers
  • n2: Standard Tropospheric Chemistry scheme using the Backward Euler solver (trop)
  • n3: Regional Air Quality Chemistry scheme using the Backward Euler solver (raq)
  • n4: Tropospheric Chemistry with Isoprene scheme using the Newton-Raphson solver (tropisop)
  • n5: Stratospheric-Tropospheric Chemistry using the Newton-Raphson solver (strattrop, also know as CheST)
  • n6: Standard Stratospheric Chemistry using the Newton-Raphson solver (strat)
  • n7: Offline-oxidants scheme (to drive GLOMAP-mode) using the Newton-Raphson solver (offline)
  • n8: Offline-oxidants scheme (to drive GLOMAP-mode) using the Newton-Raphson solver (offline_be)
  • n11: CRI-Strat version 2 scheme using the Newton-Raphson solver (cristrat with i_ukca_chem_version > 119)
  • n12: CRI-Strat version 1 scheme using the Newton-Raphson solver (cristrat)

Therefore, looking at the option code for ozone (s34i001), it is valid for the trop, raq, tropisop, strattrop, strat, and cristrat chemistry schemes.

Fifth Line:

• 2101: This is the PP Field Code. Existing UKCA fields will have different numbers for these, but for all new fields, you should set this number to 0.

So to make a STASH entry for a single tracer called ALICE in slot s34i498 and BOB in slot s34i499 that are only valid in the StratTrop and CRI-Strat 2 schemes, the STASHmaster_A entry would look like

#
1|    1 |   34 |  498 |ALICE MASS MIXING RATIO AFTER TSTEP |
2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000010000010000 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |    0 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#
1|    1 |   34 |  499 |BOB MASS MIXING RATIO AFTER TSTEP   |
2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000010000010000 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |    0 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

Section 51

All STASH entries in Section 34 need a corresponding pressure-level field to be added to section 51. The equivalent STASHmaster_A entry for s51 ozone is:

#
#===============================================================================
# Section 51 UKCA Chemistry on pressure levels
#===============================================================================
#
1|    1 |   51 |    1 |O3 MASS MIXING RATIO ON PRESS LEVS  |
2|    0 |    0 |    1 |    1 |    3 |    1 |    2 |    0 |    0 |    0 |    1 |
3| 000000000000000000000000111110 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 2101 |    0 |    8 |    0 |    0 |    0 |    0 |    0 |
#

You will notice that there are a number of changes to various codes, and this is to do with defining the grid that the diagnostic is valid on, whether it can be held in the dump, etc. For more information on what these codes mean, please see Appendix C in UMDP C4, which can be obtained from the SRS here (password required).

When making a new entry, the easiest thing to do is copy an existing entry and make the required changes to the item, name, PP field code, and option codes. As we are making new chemical tracers, it would be best to copy a section 51 chemical tracer (e.g. ozone) and then make the necessary changes to that. Copying in a section 34 entry and changing the section number will mean that the field will not be output.

Remember: You need to add 2 tracers, ALICE in s34i498 and BOB in s34i499 (and section 51 for pressure level equivalents).

Help text

You should also add appropriate help text into the

vn13.0_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf

file, e.g.

[stashmaster:code(34498)]
description=ALICE MASS MIXING RATIO AFTER TIMESTEP
help=UKCA Tutiorial Tracer ALICE Mass Mixing Ratio in kg/kg(Air)

[stashmaster:code(34499)]
description=BOB MASS MIXING RATIO AFTER TIMESTEP
help=UKCA Tutiorial Tracer BOB Mass Mixing Ratio in kg/kg(Air)

and

[stashmaster:code(51498)]
description=ALICE MASS MIX RATIO ON PRESS LEVS
help=UKCA Tutiorial Tracer ALICE Mass Mixing Ratio in kg/kg(Air)
    =on pressure levels

[stashmaster:code(51499)]
description=BOB MASS MIX RATIO ON PRESS LEVS
help=UKCA Tutiorial Tracer BOB Mass Mixing Ratio in kg/kg(Air)
    =on pressure levels

You should make these changes to STASHmaster_A and STASHmaster-meta.conf, and then fcm commit these changes. This is important, otherwise the running suite will not be able to see the changes you have made once you have included your new STASHmaster_A file in Rose.

Use your new STASHmaster file in Rose

Before you make these changes you should first save and close your suite.

To get Rose to recognise your STASHmaster file, you will need to make a number of changes:

1. Make sure to point the um metadata to your branch (if it isn't already) by editing the um meta path (you should already be doing this after following the instructions in the metadata section above).
2. You need to open the $HOME/roses/[SUITE-ID]/app/um/rose-app.conf file in a text editor (e.g. vim, emacs, nedit etc.) and add the line STASHMASTER=STASHmaster inside the [env] block near the top of the file.
3. You need to open the $HOME/roses/[SUITE-ID]/rose-suite.conf file in a text editor and add the following lines at the top of the file:

[file:app/um/file/STASHmaster]
source=fcm:um.xm_br/dev/[your MOSRS userid]/vn13.0_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@HEAD

• You need to ensure that you have committed your STASHmaster_A changes, otherwise your new tracer(s) will not be seen at run-time during the reconfiguration or atmosphere steps.
• Instead of using @HEAD you could also leave this blank, as this will also take from the head of the branch. Do not specify a specific revision number here (unless you have a particular reason for doing so).
• For the VM only it is also possible to specify the full path to the STASHmaster directory. This is because the suite runs on the same machine that the branch is on.

[file:app/um/file/STASHmaster]
source=/home/[your VM userid]/src/vn13.0_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster

You may wish to now fcm commit your suite changes. You can now re-open your suite.

When running your suite, if you get an error similar to:

[INFO] create: app/um/file
[FAIL] file:app/um/file/STASHmaster=source=fcm:um.xm_br/dev/[your MOSRS userid]/vn13.0_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@HEAD: bad or missing value

you should try running mosrs-cache-password again to cache your MOSRS credentials.

Initialise your new tracer(s)

Your new tracer(s) is a prognostic variable, as therefore the UM requires prior knowledge of the values it has to be able to run properly. To do this you need to go to um $\rightarrow$ namelist $\rightarrow$ Reconfiguration and Ancillary Control $\rightarrow$ Configure ancils and initialise dump fields. Here you will see a list of fields. You can change the order of these by e.g. STASH number, as this often makes it easier to view.

To add new fields, right click anywhere within the table and click Add new section. This will make a new entry with index 1, if you add another entry, it will be given index 2 etc.. Right-click on this and click on View namelist:items(X) (where X is the index number). This will open a new tab where you can select the STASH section and item for the field you want to initialise using the drop-down menus. Some UKCA tracers need to be given full 3D initial conditions in ancillary file format. However, for this example we will initialise the tracer to a small number, $1.000000\times 10^{-15}$. To do this, select the radio button for Set to a specified constant value and put 1.000000e-15 in the dialog box labelled user_prog_rconst at the bottom of the panel.

You will need to do this for each of the tracers you are adding, and you can add multiple prognostics per entry. You can also clone existing entries to speed up the process. When you have finished, you will need to go to the STASH Requests panel (see the STASH tutorial) and run the TidyStashTransform macro to correctly generate the required index value for each tracer initialisation.

Output your new tracers

To output your tracers, go to the STASH panel and output your tracers as described in the What is STASH? tutorial.

Remember: You need to add 2 tracers, ALICE in s34i498 and BOB in s34i499, as well as their pressure-level equivalents.

Run your suite

Now that you have made the required changes to Rose and in your branch, please run your suite. You may find that it fails on the fcm_make, recon, or atmos jobs. To find the errors and see output, you should either right-click the failed task in Gcylc and view the output, or go to the

/home/[your VM userid]/cylc-run/[SUITE-ID]

directory. Within this there are a number of directories. To see the log files, cd into

log/job/1/[JOB NAME]/NN

and view the job.err or job.out files. When the suite successfully runs, the fieldsfile output can be found in

/home/[your VM userid]/cylc-run/[SUITE-ID]/work/1/atmos/

Viewing output in Xconv

If you open the .pa file in Xconv, you should now see the following if you have outputted both the section 34 and section 51 fields:

4    : 96    72    27    1     Stash code = 51498
5    : 96    72    27    1     Stash code = 51499

11   : 96    72    38    1     Stash code = 34498
12   : 96    72    38    1     Stash code = 34499

Note here that these fields are not named ALICE and BOB, or however you have described them in your STASHmaster_A file. They are instead labelled by the unique STASH code identifier that you have defined for them. This is working as expected.

• Optional: It is possible (although not necessary) to tell Xconv to read the STASHmaster_A file from your branch. To do this, in Xconv go to Setup $\rightarrow$ Select STASH Master Files and then navigate to the location of the file in your branch's working copy in the left-hand side of the panel. When you have located it, highlight it and click Add. Then click Apply, Save, and Dismiss. Now Xconv will list the names of your species as you have called them in your STASHmaster_A file.

Numerical Noise

• 

  ALICE (s34i498) plotted using cf-view

• 

  Numerical noise in the ALICE tracer (s34i498) plotted using Xconv

• 

  Numerical noise in the BOB tracer (s34i499) plotted using Xconv

When your suite has run successfully, and you view the fields for your new tracer(s) in Xconv, you may find that they have a speckled appearance, rather than being constant. This is due to numerical noise that has been introduced as the tracers go through the UM timesteps. Once the field is converted to a 32-bit pp-file this should disappear. It will also cease to become apparent when emissions and reactions are applied to these tracers.

Worked solution to Task7.1

You were given the task:

• Add in two new tracers in to slots 498 and 499 for the StratTrop and CRI-Strat2 chemistry schemes. The tracer in slot 498 will be called ALICE and the tracer in slot 499 will be called BOB. You should initialise these tracers to 1.000000e-15. You should also output these two tracers, as well as the pressure-level equivalents, through the UPA stream in STASH as 3-hour means.

The specific Rose changes made are:

• https://code.metoffice.gov.uk/trac/roses-u/changeset/237080/c/q/9/8/8/trunk

Index: app/fcm_make/rose-app.conf
===================================================================
--- app/fcm_make/rose-app.conf	(revision 237052)
+++ app/fcm_make/rose-app.conf	(revision 237080)
@@ -46,4 +46,4 @@
 ukca_rev=$BASE_UKCA_REV
 ukca_sources=
 um_rev=$BASE_UM_REV
-um_sources=
+um_sources=/home/vagrant/vn13.0_ukca_tutorial_solutions
Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 237052)
+++ app/um/rose-app.conf	(revision 237080)
@@ -1,4 +1,4 @@
-meta=um-atmos/vn13.0
+meta=/home/vagrant/vn13.0_ukca_tutorial_solutions/rose-meta/um-atmos/HEAD
 
 [command]
 default=um-atmos
@@ -27,6 +27,7 @@
 RECON_STDOUT_FILE=pe_output/atmos.fort6.pe
 RUNID=atmos
 SPECTRAL_FILE_DIR=$UMDIR/vn$VN/ctldata/spectral/ga7
+STASHMASTER=STASHmaster
 
 [file:$DATAM]
 mode=mkdir
@@ -922,6 +923,19 @@
 !!user_prog_ancil_stash_req=
 !!user_prog_rconst=0.0
 
+[namelist:items(e897a2fb)]
+ancilfilename=
+domain=1
+!!interval=0
+l_ignore_ancil_grid_check=
+!!netcdf_varname=
+!!period=1
+source=6
+stash_req=34498,34499
+update_anc=.false.
+!!user_prog_ancil_stash_req=0
+user_prog_rconst=1.000000e-15
+
 [namelist:items(e8e484ca)]
 ancilfilename=
 domain=1
@@ -3830,6 +3844,22 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(34498_e7e57cc6)]
+dom_name='DALLTH'
+isec=34
+item=498
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
+[namelist:umstash_streq(34499_07c8a074)]
+dom_name='DALLTH'
+isec=34
+item=499
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(34968_49e5e12c)]
 dom_name='DALLTH'
 isec=34
@@ -3942,6 +3972,22 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(51498_ccb8d5a7)]
+dom_name='DP27CCM'
+isec=51
+item=498
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
+[namelist:umstash_streq(51499_5c041195)]
+dom_name='DP27CCM'
+isec=51
+item=499
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(51999_8b73e62f)]
 dom_name='DP27CCM'
 isec=51
Index: rose-suite.conf
===================================================================
--- rose-suite.conf	(revision 237052)
+++ rose-suite.conf	(revision 237080)
@@ -1,3 +1,6 @@
+[file:app/um/file/STASHmaster]
+source=fcm:um.xm_br/dev/lukeabraham/vn13.0_ukca_tutorial_solutions/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@HEAD
+
 [jinja2:suite.rc]
 BUILD=true
 OFFLINE=false

These differences can be found here:

Tutorials/UMvn13.0/worked_solutions/Task07.1/Task07.1_rose.patch

The specific UM changes made are:

• https://code.metoffice.gov.uk/trac/um/changeset/112626/main/branches/dev/lukeabraham/vn13.0_ukca_tutorial_solutions

Index: rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf
===================================================================
--- rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf	(revision 112622)
+++ rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf	(revision 112626)
@@ -20142,6 +20142,14 @@
    =and RU10AO2
    =Mass Mixing Ratio in kg/kg(Air)
 
+[stashmaster:code(34498)]
+description=ALICE MASS MIXING RATIO AFTER TIMESTEP
+help=UKCA Tutorial Tracer ALICE Mass Mixing Ratio in kg/kg(Air)
+
+[stashmaster:code(34499)]
+description=BOB MASS MIXING RATIO AFTER TIMESTEP
+help=UKCA Tutorial Tracer BOB Mass Mixing Ratio in kg/kg(Air)
+
 [stashmaster:code(34862)]
 description=Nucleation soluble mode dry diameter
 help=The dry diameter of the nucleation soluble mode (m). This is used
@@ -28730,6 +28738,16 @@
    =Mass Mixing Ratio in kg/kg(Air)
     =on pressure levels
 
+[stashmaster:code(51498)]
+description=ALICE MASS MIXING RATIO AFTER TIMESTEP
+help=UKCA Tutorial Tracer ALICE Mass Mixing Ratio in kg/kg(Air)
+    =on pressure levels
+
+[stashmaster:code(51499)]
+description=BOB MASS MIXING RATIO AFTER TIMESTEP
+help=UKCA Tutorial Tracer BOB Mass Mixing Ratio in kg/kg(Air)
+    =on pressure levels
+
 [stashmaster:code(51862)]
 description=Nucleation soluble mode dry diameter ON P LEVS
 help=The dry diameter of the nucleation soluble mode (m). This is used
Index: rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A
===================================================================
--- rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A	(revision 112622)
+++ rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A	(revision 112626)
@@ -19330,6 +19330,18 @@
 4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
 5|    0 |    0 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
 #
+1|    1 |   34 |  498 |ALICE MASS MIXING RATIO AFTER TSTEP |
+2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
+3| 000000000000000000010000010000 | 00000000000000000001 |    1 |
+4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
+5|    0 |    0 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
+#
+1|    1 |   34 |  499 |BOB MASS MIXING RATIO AFTER TSTEP   |
+2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
+3| 000000000000000000010000010000 | 00000000000000000001 |    1 |
+4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
+5|    0 |    0 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
+#
 1|    1 |   34 |  862 |DRY PARTICLE DIAMETER NUC-SOL       |
 2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
 3| 100000000200000000000040000044 | 00000000000000000001 |    3 |
@@ -29911,6 +29923,18 @@
 4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
 5|    0 | 2252 |    0 |    8 |    0 |    0 |    0 |    0 |    0 |
 #
+1|    1 |   51 |  498 |ALICE MMR ON PRESSURE LEVELS        |
+2|    0 |    0 |    1 |    1 |    3 |    1 |    2 |    0 |    0 |    0 |    1 |
+3| 000000000000000000010000010000 | 00000000000000000001 |    3 |
+4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
+5|    0 |    0 |    0 |    8 |    0 |    0 |    0 |    0 |    0 |
+#
+1|    1 |   51 |  499 |BOB MMR ON PRESSURE LEVELS          |
+2|    0 |    0 |    1 |    1 |    3 |    1 |    2 |    0 |    0 |    0 |    1 |
+3| 000000000000000000010000010000 | 00000000000000000001 |    3 |
+4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
+5|    0 |    0 |    0 |    8 |    0 |    0 |    0 |    0 |    0 |
+#
 1|    1 |   51 |  862 |DRY PARTICLE DIAM NUC-SOL ON P LEVS |
 2|    0 |    0 |    1 |    1 |    3 |    1 |    2 |    0 |    0 |    0 |    1 |
 3| 100000000200000000000040000044 | 00000000000000000001 |    3 |

These differences can be found here:

Tutorials/UMvn13.0/worked_solutions/Task07.1/Task07.1_um.patch

If you open the .pa file in Xconv, you should see the following fields:

4    : 96    72    27    1     Stash code = 51498
5    : 96    72    27    1     Stash code = 51499

11   : 96    72    38    1     Stash code = 34498
12   : 96    72    38    1     Stash code = 34499

Sample output from this task can be found at

Tutorials/UMvn13.0/sample_output/Task07.1/

Task 7.2: Add new tracers into UKCA

TASK7.2: Include your UKCA branch to use your new tracers and chemistry in your UM suite.

Required UM Code Changes

You have already made all the required changes to UKCA in previous tutorials. However, to use your new tracers, ALICE and BOB, within the UM, you need to edit the mapping that defines which tracers are placed in which slot.

src/control/ukca_interface/ukca_nmspec_mod.F90

In the UM there is a master mapping array that tells the UKCA code which transported species are placed into a particular item number in section 34. These are contained in the first 499 slots.

This array is called nm_spec, and it can be found in ukca_nmspec_mod.F90 in the src/control/ukca_interface/ directory. At UMvn13.0, it looks like this:

nm_spec(1:a_max_ukcavars) = [                                                  &
'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
'C2H4      ','C4H10     ','oXYLENE   ','TBUT2ENE  ','APINENE   ',              &
'BPINENE   ','C2H2      ','BENZENE   ','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   ','C3H6      ','SO3       ','C4H9OOH   ',              &
'MEK       ','TOLUENE   ','NO2       ','BrO       ','HCl       ',  & !100
'Nuc_SOL_N ','Nuc_SOL_SU','Ait_SOL_N ','Ait_SOL_SU','Ait_SOL_BC',              &
'Ait_SOL_OM','Acc_SOL_N ','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OM',  & !110
'Acc_SOL_SS','Acc_SOL_DU','Cor_SOL_N ','Cor_SOL_SU','Cor_SOL_BC',              &
'Cor_SOL_OM','Cor_SOL_SS','Cor_SOL_DU','Ait_INS_N ','Ait_INS_BC',  & !120
'Ait_INS_OM','Acc_INS_N ','Acc_INS_DU','Cor_INS_N ','Cor_INS_DU',              &
'Nuc_SOL_OM','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','EtOH      ',  & !140
'i-PrOH    ','n-PrOH    ','HOCH2CHO  ','HOC2H4OOH ','EtCO3H    ',  & !145
'HOCH2CO3H ','NOA       ','EtONO2    ','PASSIVE O3','AGE OF AIR',  & !150
'i-PrONO2  ','MeO2NO2   ','HOC2H4NO3 ','PHAN      ','MeSCH2OO  ',  & !155
'MeS       ','MeSO      ','MeSO2     ','MeSO3     ','MSIA      ',  & !160
'CARB14    ','CARB17    ','CARB11A   ','CARB7     ','CARB10    ',  & !165
'CARB13    ','CARB16    ','UCARB10   ','CARB3     ','CARB6     ',  & !170
'CARB9     ','CARB12    ','CARB15    ','UCARB12   ','NUCARB12  ',  & !175
'UDCARB8   ','UDCARB11  ','UDCARB14  ','TNCARB26  ','TNCARB10  ',  & !180
'RN10NO3   ','RN13NO3   ','RN16NO3   ','RN19NO3   ','RA13NO3   ',  & !185
'RA16NO3   ','RA19NO3   ','RTX24NO3  ','RN10OOH   ','RN13OOH   ',  & !190
'RN16OOH   ','RN19OOH   ','RN8OOH    ','RN11OOH   ','RN14OOH   ',  & !195
'RN17OOH   ','RU14OOH   ','RU12OOH   ','RU10OOH   ','NRU14OOH  ',  & !200
'NRU12OOH  ','RN9OOH    ','RN12OOH   ','RN15OOH   ','RN18OOH   ',  & !205
'NRN6OOH   ','NRN9OOH   ','NRN12OOH  ','RA13OOH   ','RA16OOH   ',  & !210
'RA19OOH   ','RTN28OOH  ','NRTN28OOH ','RTN26OOH  ','RTN25OOH  ',  & !215
'RTN24OOH  ','RTN23OOH  ','RTN14OOH  ','RTN10OOH  ','RTX28OOH  ',  & !220
'RTX24OOH  ','RTX22OOH  ','NRTX28OOH ','RAROH14   ','RAROH17   ',  & !225
'RU12PAN   ','RTN26PAN  ','TNCARB12  ','TNCARB11  ','RTN23NO3  ',  & !230
'CCARB12   ','TNCARB15  ','RCOOH25   ','TXCARB24  ','TXCARB22  ',  & !235
'RN9NO3    ','RN12NO3   ','RN15NO3   ','RN18NO3   ','RU14NO3   ',  & !240
'RTN28NO3  ','RTN25NO3  ','RTX28NO3  ','RTX22NO3  ','AROH14    ',  & !245
'ARNOH14   ','AROH17    ','ARNOH17   ','ANHY      ','Acc_SOL_NN',  & !250
'Cor_SOL_NN','DHPCARB9  ','HPUCARB12 ','HUCARB9   ','IEPOX     ',  & !255
'HMML      ','DHPR12OOH ','DHCARB9   ','RU12NO3   ','RU10NO3   ',  & !260
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !265
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !270
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !275
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !280
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !285
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !290
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !295
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !300
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !305
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !310
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !315
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !320
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !325
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !330
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !335
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !340
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !345
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !350
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !355
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !360
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !365
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !370
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !375
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !380
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !385
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !390
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !395
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !400
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !405
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !410
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !415
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !420
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !425
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !430
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !435
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !440
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !445
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !450
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !455
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !460
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !465
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !470
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !475
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !480
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !485
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !490
'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !495
'XXX       ','XXX       ','XXX       ','XXX       '                & !499
 ]

This array is case sensitive and each string is a fixed length of 10 characters, with the whitespace being made up of spaces and not another type of white space (e.g. tabs).

When adding new tracers you should not overwrite tracers that are already in use by the chemistry scheme that you are using (e.g. StratTrop etc.), and it is best to also take care and avoid tracers in use by other schemes, if possible. You can see the tracers used by each scheme by looking in the chch_defs array at the top of the ukca_chem_master.F90 module.

Here you should put a new species, 'ALICE     ', into tracer slot 498 and 'BOB       ', into tracer slot 499 (both currently specified as 'XXX       ', which means that they are empty and not in use by any scheme at the moment).

Rose Suite changes

Now you will need to run your Rose suite again after making some minor changes.

Include your UKCA branch

As with your UM branch, you will now also need to include your UKCA branch in the same way. Go to fcm_make $\rightarrow$ env $\rightarrow$ Sources and add a new branch by clicking the plus symbol in the ukca_sources section. You should then put

/path/to/um13.0_your_branch_name

e.g.

/home/ubuntu/um13.0_ukca_tutorial_solutions

or point to the branch on the repository

branches/dev/[your MOSRS userid]/um13.0_your_branch_name

e.g.

branches/dev/lukeabraham/um13.0_ukca_tutorial_solutions

You can specify specific revision numbers by putting @REV at the end of this line (where REV is the revision number, e.g. 12345 etc.), remembering to update Rose each time you commit your branch.

i_ukca_chem_version

As we have specified these new species and reaction at chemistry version 131 you will need to update the value of i_ukca_chem_version to 131. This variable is found in the panel um $\rightarrow$ namelist $\rightarrow$ UM Science Settings $\rightarrow$ Section 34 - UKCA: UK Aerosols and Chemistry $\rightarrow$ Chemistry.

Worked solution to Task 7.2

• 

  Surface ALICE

• 

  Surface BOB

You were given the task

• Include your UKCA branch to use your new tracers and chemistry in your UM suite.

The specific Rose changes made are:

• https://code.metoffice.gov.uk/trac/roses-u/changeset/237210/c/q/9/8/8/trunk

Index: app/fcm_make/rose-app.conf
===================================================================
--- app/fcm_make/rose-app.conf	(revision 237191)
+++ app/fcm_make/rose-app.conf	(revision 237210)
@@ -44,6 +44,6 @@
 thread_utils=false
 timer_version=3A
 ukca_rev=$BASE_UKCA_REV
-ukca_sources=
+ukca_sources=/home/vagrant/um13.0_ukca_tutorial_solutions
 um_rev=$BASE_UM_REV
 um_sources=/home/vagrant/vn13.0_ukca_tutorial_solutions
Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 237191)
+++ app/um/rose-app.conf	(revision 237210)
@@ -2960,7 +2960,7 @@
 i_mode_setup=2
 i_ukca_activation_scheme=1
 i_ukca_chem=51
-i_ukca_chem_version=121
+i_ukca_chem_version=131
 i_ukca_conserve_method=2
 i_ukca_dms_flux=1
 i_ukca_hetconfig=0

These differences can be found here:

Tutorials/UMvn13.0/worked_solutions/Task07.2/Task07.2_rose.patch

The specific UM changes made are:

• https://code.metoffice.gov.uk/trac/um/changeset/112662/main/branches/dev/lukeabraham/vn13.0_ukca_tutorial_solutions

Index: src/control/ukca_interface/ukca_nmspec_mod.F90
===================================================================
--- src/control/ukca_interface/ukca_nmspec_mod.F90	(revision 112626)
+++ src/control/ukca_interface/ukca_nmspec_mod.F90	(revision 112662)
@@ -172,7 +172,7 @@
 'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !485
 'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !490
 'XXX       ','XXX       ','XXX       ','XXX       ','XXX       ',  & !495
-'XXX       ','XXX       ','XXX       ','XXX       '                & !499
+'XXX       ','XXX       ','ALICE     ','BOB       '                & !499
  ]

 IF (l_ukca_raq .OR. l_ukca_raqaero) THEN

These differences can be found here:

Tutorials/UMvn13.0/worked_solutions/Task07.2/Task07.2_um.patch

Sample output from this task can be found at

Tutorials/UMvn13.0/sample_output/Task07.2/

Checklist

☐ If required, copy an appropriate Rose suite to use to test your changes.

☐ Make a new ticket on the Met Office SRS Trac pages.

☐ Make a branch at the required MetUM version using fcm branch-create.

☐ Checkout your branch using fcm checkout.

☐ Choose slots for your new tracer(s) from the list in ukca_nmspec_mod.F90.

☐ Make the required changes to branch's STASHmaster_A file, to add the new tracers.

☐ Add help text for your tracers in your branch's STASHmaster-meta.conf file.

☐ fcm commit the STASH changes to your branch.

☐ Using a text editor, open the app/um/rose-app.conf file from your roses/[SUITE-ID] directory, and add the line STASHMASTER=STASHmaster in the [env] block, then save and close the file.

☐ Using a text editor, open the rose-suite.conf file from your roses/[SUITE-ID] directory, and add the following lines to the top of the file, before saving and closing it:

[file:app/um/file/STASHmaster]
source=fcm:um.xm_br/dev/[your MOSRS userid]/vnX.Y_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@HEAD

☐ Point the metadata in your suite to the rose-meta/um-atmos/HEAD of your branch's working copy.

☐ Include your branch in your suite at: fcm_make $\rightarrow$ env $\rightarrow$ Sources.

☐ Initialise your tracers in your suite at: um $\rightarrow$ namelist $\rightarrow$ Reconfiguration and Ancillary Control $\rightarrow$ Configure ancils and initialise dump fields.

☐ Output your tracers in STASH at: um $\rightarrow$ namelist $\rightarrow$ Model Input and Output $\rightarrow$ STASH Requests and Profiles $\rightarrow$ STASH Requests.

☐ Run the TidyStashTransform transform macro.

☐ Save your suite.

☐ In the roses/[SUITE-ID] directory, run fcm commit to commit your changes to the repository.

☐ Run your suite.

☐ Add your new tracer(s) from into the list in ukca_nmspec_mod.F90.

☐ fcm commit the changes to your branch.

☐ Use your UKCA suite in your branch.

☐ Update the value of i_ukca_chem_version as needed.

☐ Run your suite again.

Tutorial 8

UKCA Chemistry and Aerosol Tutorials at UMvn13.0

---

Written by Luke Abraham 2022