UKCA Chemistry and Aerosol vn10.9 Tutorial 3

UKCA Chemistry and Aerosol Tutorials at vn10.9

When using the UM, it is likely that you will want to add new diagnostics, and we will cover writing out chemical fluxes in a later tutorial. Here we will cover selecting new diagnostics in STASH.

Task 3.1: add new output

TASK 3.1: Output 3-hourly-mean UKCA CO (section 34 item 010) field to the UPA output stream, and then add-in the equivalent diagnostic on pressure levels using the DP27CCM domain.

Hint
You will need to remember to run the TidyStashTransform macro once you have added the diagnostics in the STASH panel.

In the following page you will learn more about how the Unified Model's output is organised and managed. You should use this information to complete the task above. A worked solution is provided at the end of the tutorial.

What is STASH?

STASH is the Unified Model's storage handling and diagnostic system. It is designed to cope with the many different configurations that the UM can be used in, but still provide output in a consistent and standard way. A full technical description of STASH can be found in Unified Model Documentation Paper C4 which can be downloaded from the Met Office Science Repository Service (password required). You may also want to look through the UM STASH help here: https://code.metoffice.gov.uk/doc/um/latest/um-training/stashmaster.html .

Prognostic and Diagnostic Fields

The UM considers variables (or fields) to be of two different types, prognostic or diagnostic. Prognostic fields are ones which the model must have values for, prior to each timestep, as e.g. the equations of motion the model solves require these fields (these are fields such as specific humidity or potential temperature), so they must exist in the model start dump. Diagnostic fields are all other fields that are derived from prognostic ones, and as such the model does not need to have prior values for these. Ancillary files (such as emissions, SSTs etc) contain prognostic fields. UKCA requires around 137 prognostic fields in the GA7+StratTrop configuration, and could in theory provide almost 2000 diagnostic fields on model levels, many of which have pressure-level equivalents.

From a user's perspective, STASH is used to output fields during the run, and from this point of view it does not matter if these are prognostic or diagnostic fields. However, you will need to consider these differences when you add new chemical tracers.

STASH Sections and Items

Each field that is considered by STASH has a unique address which is given by a section and an item number. Prognostic fields are mostly held in section 0 (with the exception of tracers) and diagnostics are organised by areas of the code, e.g. short-wave radiation diagnostics are held in section 1, long-wave radiation diagnostics are held in section 2 etc. Some sections will always be on, and some sections will only be on if a certain process is selected, e.g. the interactive land-surface scheme. Each section can hold up to 999 items, where each item is a separate prognostic or diagnostic field, and can be either 2D or 3D.

Each field has its own entry in a STASHmaster file. There is a master list of fields which is held in the STASHmaster_A file, a copy of which is located in each branch at

rose-meta/um-atmos/vnX.Y/etc/stash/STASHmaster/STASHmaster_A

If you make changes to this to be committed to the trunk, for instance to add your own diagnostics, you will need to make changes to the

rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A

file, and then change where Rose looks for the metadata associated with your suite. If you are making changes for an older version to use in an existing suite (e.g. version 10.9) you would make changes in

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

This will be covered in more detail when you add new chemical tracers.

The term HEAD means the metadata for the HEAD of the trunk. When you branch from a stable release (e.g. vn10.9) the "latest" metadata version at the time and HEAD will be identical, but the trunk's HEAD metadata is continually updated and so it is unsafe to use this with an app. Developers working with the latest UM release will edit the HEAD metadata in their branches, and when they are merged onto the trunk that HEAD metadata will go on to form the metadata for the next stable release.

STASH output

Model fields output through STASH will be output to one (or more) output streams. In climate suites, these are of two types:

Climate meaning streams: These are always sent through some sort of dump-meaning time profile (typically TDMPMN) to the UPMEAN output stream. These will then result in files ending .pm... for monthly means, and .ps for seasonal means, .py for annual means, and .px for decadal means.
Model output streams: The details of these can be found at um $\rightarrow$ namelist $\rightarrow$ Model Input and Output $\rightarrow$ Model Output Streams. You can view each one in detail and make changes to e.g. the reinit_unit to change how frequently the files are made. These are of the form .pA..., where A could be one of a, b, c, d, e, f, g, h, i, j, or k.

STASH Panel

Figure 1: The STASH panel in Rose.

The STASH panel can be found at um $\rightarrow$ namelist $\rightarrow$ Model Input and Output $\rightarrow$ STASH Requests and Profiles $\rightarrow$ STASH Requests.

It is usually intially sorted by section/item numbers, but you can change the ordering by clicking on the items on the bar at the top (e.g. use_name). This can be helpful to see which items are going to which output stream.

Figure 1: The new STASH requests panel in Rose.

To add new output, click the New button (with the large plus symbol on it), and this will open the Add new STASH requests panel. This lists all the available STASH output by section. You can scroll down to the section you want, click the small arrow on the left, scroll down to the diagnostic that you want and either right-click on it and click Add STASH request, or select it and then click the Add button in the top right-hand corner of the panel.

Another option, especially if there is already a STASH request that has similar domain, time, and usage profiles, is to right-click the existing request, and select

Once this has been added to the main STASH panel, you will get a message, similar to Added request as namelist: streq(1). You will also find that a red warning triangle has appeared in the rose editor. This will disappear once you fill-in the dom_name, tim_name, and use_name entries for it. This can be done by clicking next to the red X that is in each column and selecting the correct value from the drop-down menu.

Once you have selected entries for each usage field, you will need to run the TidyStashTransform macro. When the STASH entry was created it was given the the namelist value streq(1), with the next as streq(2) etc.. This is a default value, and the correct namelist index needs to be generated for each STASH item (each is unique to the choices made, which also prevents duplicate entries being created). To do this, click the Macros drop-down menu from the top-left of the panel and select the stashindices.TidyStashTransform option. This will process the STASH requests, and any entries where the index doesn't match will be listed. Click OK, and this will then apply the correct index to the request, which will be the 5-digit STASH number followed by a string of seemingly-random letters and numbers, e.g. 34010_c4b8f1ad.

It is also possible to run any Rose macro (including stashindices.TidyStashTransform) by going to the Metadata $\rightarrow$ um menu at the top of the Rose GUI.

UKCA STASH sections

UKCA actually has 6 STASH sections - these are:

Section 34: This contains the prognostic UKCA variables on model theta levels, i.e. all the transported species, and several other fields which are required to be in the restart file.
Section 37: This is for UKCA tracer lateral boundary conditions for use in limited area configurations.
Section 38: This section is for GLOMAP-mode diagnostics on model theta levels.
Section 50: This section is for Chemical diagnostics on model theta levels (or single levels, e.g. surface).
Section 51: This section duplicates all the variables from Section 34, but on pressure levels.

To use this section l_ukca_chem_plev must be set to true in the UKCA panel.

Additionally, s51i999 must also be output, as this is the Heavyside function that is used to mask missing data from the pressure-level fields (as the UM fieldsfile format has missing data set to zero).

Section 52: This section duplicates all the variables from Section 50, but on pressure levels.

To use this section l_ukca_asad_plev must be set to true in the UKCA panel.

Additionally, s51i999 must also be output, as this is the Heavyside function that is used to mask missing data from the pressure-level fields (as the UM fieldsfile format has missing data set to zero).

Solution to Task 3.1

Surface (20m) UKCA CO (x-y)
1000hPa UKCA CO (x-y)

You were given the task

Output 3-hourly-mean UKCA CO (section 34 item 010) field to the UPA output stream, and then add-in the equivalent diagnostic on pressure levels using the DP27CCM domain

and were given the hints

You will need to remember to run the TidyStashTransform macro once you have added the diagnostics in the STASH panel.

For a working Rose suite that has completed this task, please see

ARCHER: u-as292@59777
vm: u-as297@59775

The specific Rose changes made are:

ARCHER:

Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 59739)
+++ app/um/rose-app.conf	(revision 59777)
@@ -3287,6 +3287,14 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(34010_c4b8f1ad)]
+dom_name='DALLTH'
+isec=34
+item=10
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(34106_ebb7bb67)]
 dom_name='DALLTH'
 isec=34
@@ -3407,6 +3415,14 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(51010_5e3d3bef)]
+dom_name='DP27CCM'
+isec=51
+item=10
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(51999_8b73e62f)]
 dom_name='DP27CCM'
 isec=51

vm:

Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 59757)
+++ app/um/rose-app.conf	(revision 59775)
@@ -3879,6 +3879,14 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(34010_c4b8f1ad)]
+dom_name='DALLTH'
+isec=34
+item=10
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(34106_ebb7bb67)]
 dom_name='DALLTH'
 isec=34
@@ -3999,6 +4007,14 @@
 tim_name='T3HMN'
 use_name='UPA'
 
+[namelist:umstash_streq(51010_5e3d3bef)]
+dom_name='DP27CCM'
+isec=51
+item=10
+package=
+tim_name='T3HMN'
+use_name='UPA'
+
 [namelist:umstash_streq(51999_8b73e62f)]
 dom_name='DP27CCM'
 isec=51

These differences can be found here:

PUMA: /home/ukca/Tutorial/vn10.9/worked_solutions/Task3.1/Task3.1_rose.patch

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

3    : 96    72    27    1     CO MASS MIX RATIO ON PRESS LEVS
6    : 96    72    38    1     CO MASS MIXING RATIO

Sample output from this task can be found at /work/n02/n02/ukca/Tutorial/vn10.9/sample_output/Task3.1/atmosa.pa19810901_00 on ARCHER.

Checklist

☐ Add new STASH diagnostic requests in: um

\rightarrow

namelist

\rightarrow

Model Input and Output

\rightarrow

STASH Requests and Profiles

\rightarrow

STASH Requests.

☐ Select the appropriate domain, time, and usage profiles for the new diagnostic(s).

☐ Run the TidyStashTransform macro.

☐ If outputting UKCA pressure-level diagnostics, remember to make sure that l_ukca_chem_plev and (possibly) l_ukca_asad_plev are set to True.

Tutorial 4

Written by Luke Abraham 2017