UKCA Chemistry and Aerosol UMvn13.0 Tutorial 6

UKCA Chemistry and Aerosol Tutorials at UMvn13.0

Difficulty	MEDIUM
Time to Complete	Under 1 hour
Video instructions	Walkthrough (YouTube)

Remember to run mosrs-cache-password.

What you will do in this tutorial

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 you will learn how to output diagnostics using the UM diagnostics system, STASH.

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 at the end.

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 global 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 restart files (also know as dump files). 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 UKCA tracers to the UM.

STASH Sections and Items

Each field that is considered by STASH has a unique number to identify it, 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 UM branch at

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

If you have not made and checked-out a UM branch yet, you will not be able to see this file. We will not look at this file now, but we will look at it in detail when you add new UKCA tracers to the UM.

The term HEAD means the metadata for the "HEAD" of the trunk. 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:

1. 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.
   • In UKESM suites, climate meaning has been turned off as it slows the model down considerably. It is likely that the use of climate meaning will be discontinued in future.
2. 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, k, etc., or sometimes numbers, e.g. 4, 5, etc..

Typically these fieldsfiles will be placed in a directory such as, e.g.

/work/n02/n02/$USER/cylc-run/[SUITE-ID]/share/data/History_Data

If you have additional archiving on in your suite these may then be moved elsewhere (e.g. MASS or JASMIN) and converted from 64-bit to 32-bit pp-files (with a new .pp extension).

STASH Panel

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.

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 Clone this section.

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.

Domain, time, and usage profiles

It can be quite confusing looking at the different profiles used for the STASH entries. These are broken down into:

• Domain profiles - these correspond to the grid used for the output. By convention they usually start with the letter D and then the following letters describe the grid used, e.g.
  • DALLTH - output on all model theta levels (e.g. all chemical tracers)
  • DIAG - a single level diagnostic field, but not the surface level (e.g. tropopause pressure)
  • DP27CCM - DP would mean a pressure-level output. Here it is on 27 levels for composition-climate modelling
• TIME profiles - these correspond to the time sampling used in the output. By convention they usually start with the letter T and then the following letters describe the time sampling used, e.g.
  • TALLTS - output all timesteps
  • T3HRMN - output a 3-hourly mean
  • T1H - output the field hourly without any meaning
• USAGE profiles - these correspond to the output stream (i.e. file) sent to. By convention they usually start with the letter U and then the following letters describe the file sent to, e.g.
  • UPA - send the output to the *.pa* file
  • UPMEAN - send the output to the monthly-meaning stream, e.g. *.pm* file. Note that newer suites instead send monthly-mean output to the UPM profile directly.

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.
  • Additionally, section 51 item 999 (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.
  • 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).

Note that currently only one pressure-level set can be used at any one time. For pressure-level output, you should mask the data by dividing by the Heaviside function (s51i999), which will mask/weight all points near the surface correctly. If a field is not masked, near-surface points will have zeros and/or small values that could adversely affect any calculations performed on those points.

Task 6.1: add new output

TASK 6.1: Output 3-hourly-mean UKCA CO (section 34 item 010) field to the UPA output stream. This field is on model theta levels and so should use the DALLTH domain profile. You should also output the equivalent diagnostic on pressure levels using the DP27CCM domain profile.

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

Worked Solution to Task 6.1

• 

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

• 

  1000hPa UKCA CO (x-y)

The specific Rose changes made are:

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

Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 237006)
+++ app/um/rose-app.conf	(revision 237052)
@@ -3806,6 +3806,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
@@ -3926,6 +3934,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:

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

If you open the .pa file in Xconv or cf-view, 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

Tutorials/UMvn13.0/sample_output/Task06.1/

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 diagnostic(s).

☐ Run the TidyStashTransform macro.

Tutorial 7

UKCA Chemistry and Aerosol Tutorials at UMvn13.0

---

Written by Luke Abraham 2022