Unified Model Documentation Paper C04

Storage Handling and Diagnostic System (STASH)

UM Version : 10.1
Last Updated : 2015-03-13 (for vn10.1)
Owner : Richard Barnes

Met Office
FitzRoy Road
Exeter
Devon EX1 3PB
United Kingdom

c Crown Copyright 2015

This document has not been published; Permission to quote from it must be obtained from the Unified Model
system manager at the above address
 UMDP: C04
Storage Handling and Diagnostic System (STASH)

Contents
1 Introduction 1

2 Background — Original design ideas 2

3 STASH request processing system 3

3.1 Data addressing within the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2 STASHmaster file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.3 Top-level structure of the STASH addressing system . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.4 Primary addressing and reconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5 STASH Request Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Execution of STASH within the model 8

4.1 STWORK routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2 STASH service routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 Adding new fields (primary or diagnostics) 9

5.1 Adding diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.2 Adding prognostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

6 Acronyms 11

A STASH control file (STASHC) 12

A.1 STASHC, as read by UM code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

B STASH list array and other STASH arrays 15

C STASHmaster File Definition 20

D Updating STASHmaster Records 36

E D1 Addressing Array Contents 38

F Choosing an appropriate WGDOS packing accuracy 40

F.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
F.2 Worked Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
F.2.1 Example 1: Determine range of suitable packing codes . . . . . . . . . . . . . . . . . . . 40
F.2.2 Example 2: Determine number of bits required to pack with a given accuracy . . . . . . . 41
F.2.3 Example 3: Is it possible to pack a given row of data? . . . . . . . . . . . . . . . . . . . . 41

i c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

1 Introduction

The STASH system embraces the logical components of the UM responsible for generating versatile and op-
tional model diagnostic fields for a range of model configurations and applications, such that output is in a
standard format — the model fieldsfile — and new diagnostics can be readily introduced. In order to meet these
goals, STASH needs to know the data locations of all prospective data for output, and this is achieved by STASH
also controlling the set-up of all data addressing within the model.
Since the UM provides for automatic set-up of different configurations of the model, with different choices of
physics schemes and therefore potentially different combinations of prognostic and ancillary fields, STASH also
needs to have information on the choice of schemes, and which diagnostics are available for which scheme.
Each data field has its STASHcode (a combined model, section and item number) which uniquely labels any
primary, ancillary or diagnostic field. The basic building block of data for STASH is usually a horizontal field,
and most processing is performed level by level. STASH does not perform horizontal or vertical interpolation —
for example output fields on pressure or height surfaces must first be interpolated before being output by the
STASH routines.
The control of diagnostic requests begins in the GUI, where users can select from tables of available diagnostics.
During job processing a file named STASHC is created. Appendix A describes the content of STASHC namelists
produced by the Rose GUI. This file is read during model initialisation at run time and converted into an internal
collection of STASH related arrays, in particular a “STASHlist” array STlist that holds the STASH requests. During
execution of each timestep of the model run, there are a number of calls to the service subroutine STASH, which
may then extract, process and output any data requests, usually to a set of fieldsfiles on external disk storage.

1 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

2 Background — Original design ideas

The acronym STASH stands for “Spatial and Temporal Averaging and Storage Handling”. In view of the com-
plexity of tasks handled by the STASH system, it is worth mentioning the motivation which lay behind its original
development in the 1990s. A key aspect of the UM’s design was “plug-compatibility”. Plug-compatibility rules, to
which the “physics” routines conform, require that subroutines make no assumptions about the format of perma-
nent storage, that they do not call any routines which do so, and that they communicate with other routines only
via their argument lists. “Dynamics” routines also obey these rules as far as possible, given that they have to
calculate horizontal differences. It was desirable that any experimental diagnostic could be easily introduced into
a plug-compatible routine (PCR) without the developer having to know anything about the storage or averaging
needed.
To facilitate this, a very general user-friendly storage and averaging system is required. The system must cope
with a variety of non-meteorological processing such as averaging, but physical diagnostic calculations do not
come within its remit — it only deals with their results. It must be able to apply several possible treatments in time
(e.g. replace, accumulate), and a number of options for spatial treatment (e.g. full fields, zonal and meridional
means, limited-area and single-point data). A particular quantity may be diagnosed in more than one way at
once. Code of the complexity required for STASH processing is best not duplicated in different control routines,
and for clarity it is better kept distinct from other control functions. To reduce overheads, the various STASH
processing functions should be grouped in a single set of modular routines. Part of the design complexity lay in
the requirement to minimise memory overheads and re-use diagnostic space whenever possible.
Routines below subroutine STASH themselves form a generic system which is called by each internal model
section. The input to subroutine STASH comes either from the main data array D1 (a prognostic or a diagnostic
previously stored there by STASH) or from STASH’s own work array STASHwork. Diagnostic output produced
by a PCR is either stored in a local work array and later copied to STASHwork, or stored directly if STASHwork is
passed as an argument. When STASHwork is used directly (an “intercepted” diagnostic), the full vertical domain
is assumed, and no compression is allowed. For diagnostics copied from temporary workspace to STASHwork,
vertical compression is allowed. Vertical compression may be done by the copying routine or within the PCR.
For climate runs, all diagnostics that cannot be derived from other quantities must be held in the dumps (pro-
duced at specified intervals), where the automatic meaning programs can access them. For operational forecast
use, however, there is a requirement to produce post-processing fieldsfiles at more frequent intervals, for diag-
nostics that will not be in the dumps. It was most efficient to produce fieldsfiles for these quantities directly
from the STASH routine. STASH is therefore called not only after the PCRs which perform the integration of the
model governing equations, but also after a set of PCRs dedicated entirely to producing diagnostics.
The above account concentrates on diagnostics since they are arbitrarily variable and so more complicated to
deal with than the regular quantities that are passed between PCRs for the model code to run. In general the
term “diagnostic” is used to refer to all output from a PCR. This may even include the primary model variables if
they are processed by STASH. However the updating of primary fields, or production of field increments, will be
hardwired into each PCR and will not be part of the STASH system.
The “new dynamics” (vn5.0 onwards) and “ENDGame” (vn8.6 onwards) codes incorporate split physics, instead
of the sequential physics updates of the earliest dynamical core. Primary variables are not incremented after
each section, and there is no information to be gained from intercepting them between sections. Instead,
increments to primary variables are calculated, and these, along with ordinary diagnostics, can be requested.
In order to minimise associated lower-level code changes, STASH calls are made at the Atm Step interface,
which means that there is a separate numbered STASHwork array for each section.

2 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

3 STASH request processing system

3.1 Data addressing within the model

Data fields are held sequentially in the main data array D1, with primary fields in STASHcode order, followed by
any diagnostic fields in STASHcode order, and any secondary fields again in order. Here “primary fields” refer
to prognostic and ancillary fields, needed for initial data in the model dump to start a run. “Diagnostic fields”
are diagnostics with time meaning or other time processing such that a copy of their data needs to be held from
timestep to timestep, and also needs to be held in the dump for continuation runs (CRUNs). “Secondary fields”
are fields required throughout the timestep, but derived from initial data and so not needed in the dump.
When the Unified Model is run on multiple processors (MPP), each processing element (PE) carries the sub-
domain values of D1 according to the data decomposition requested for MPP parallel running. I.e. each PE has
its own D1 array which is populated from the input dump using MPP scattering routines, and reconstituted for
an output dump using MPP gathering routines.
The D1 array and its data pointers are hidden from the user above subroutines INITIAL and ATM STEP. The
definition of a prognostic variable has been extended from section zero (atmosphere) to section 33 (free tracers),
section 34 (UKCA chemical species) and beyond, but all are part of the atmosphere model and use the one
STASHmaster A file. Dimensioning of a few data addressing arrays by “4” is the last remnant of when the UM
code could potentially include ocean and wave submodels.
Other models are now developed in seperate code repositories and Atmosphere-ocean-ice coupling is covered
in UMDP-C02 .

3.2 STASHmaster file

The atmosphere model has a “STASHmaster” file (see Appendix C) which defines the characteristics of all
its data fields, including those for various atmospheric chemistry options. The STASHmaster file is linked to
a particular UM version, but the user may add or overwrite records, by editing the copy of “STASHmaster A”
in their branch or working copy. This is how additional prognostics and/or diagnostics are defined. The main
STASHmaster file resides on the UM repository trunk, and is read in during model initialisation. A copy is also
used within the Rose GUI software to enable diagnostics requests to be set up and verified.
Under the Rose suite environment, make any changes directly to the STASHmaster A file at
“rose-meta/um-atmos/HEAD/etc/stash/STASHmaster” in your branch/working copy.
The atmosphere model is divided into many processing sections, with a corresponding call to STASH for each
section in the routine Atm Step. The STASHmaster A file is a massive collection of field records ordered by
corresponding section numbers (0–99), 50 currently used, and, within each section, by item numbers (1–999).
Thus each STASHmaster field record is identified uniquely by the three numbers (internal model id currently
redundant, section no, item no). Table 1 defines sections in use or reserved for the atmosphere model.

3.3 Top-level structure of the STASH addressing system

The top-level control routine for initialising STASH request processing and the addressing system is STASH -
PROC — the figure below shows how the relevant subroutines are related.

3 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

Atmosphere STASH section Science section name

0 Primary fields (i.e. dump and derived fields in D1 array)
1 Short-wave radiation
2 Long-wave radiation
3 Boundary layer and surface
4 Large-scale precipitation
5 Convection
6 Gravity wave drag
8 Hydrology
9 Cloud scheme
10 Dynamics adjustment and Helmholtz solver
11 Tracer advection
12 Dynamics advection
13 Diffusion and filtering
14 Energy adjustments
15 Extra dynamics related diagnostics
16 Extra physics related diagnostics
17 Sulphur cycle chemistry
18 Atmospheric data assimilation (for QT increments)
19 Vegetation Distribution
20 Processed forecast diagnostics [used in FieldCalc small exec]
21 Thunderstorm electrification/Lightning
26 River routing
30 Processed climate diagnostics
31 Lateral boundary conditions/tendencies for input (by a LAM)
32 Lateral boundary conditions for output (from driving model)
33 Free tracer prognostics
34 UKCA chemistry and aerosol model prognostics
35 Stochastic Physics (for ensembles)
36 Free tracer lateral boundary conditions
37 UKCA chemistry and aerosol model LBCs
38 UKCA aerosol (GLOMAP mode) diagnostics
39 Nudging towards externally imposed values
40–49 VAR and PF models
50 UKCA chemistry diagnostics
51 UKCA chemistry diagnostics from section 34 on pressure levels
52 UKCA chemistry diagnostics from section 50 on pressure levels

Table 1: Atmosphere STASH sections in the UM

4 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

UM_SHELL
____________|_______________________________________
| | |
UM_Submodel_Init STASH_PROC U_MODEL
| _________|______
| | |
| compress_atmos_stashmaster INITIAL
| |
__________________________|______________________ INITCTL
| | | | | | |
RDBASIS | PRELIM OUTPTL INPUTL ADDRES WSTLST
| |
read_atmos_stashmaster PRIMARY
|
TSTMSK PSLEVCOD
|
TSTMSK_UKCA
The subroutines perform tasks as follows:
UM Submodel Init Sets up the arrays which define the submodel partitioning arrangements, i.e. they specify
how many submodels are in the run, and which internal models each submodel contains. (Now redundant)
STASH PROC Carries out the addressing of data fields and processing of STASH requests. The STASH con-
trol and addressing information generated by STASH PROC is held in a number of arrays, including the
STASHlist array, which contains the composite list of individual STASH requests. See Appendix B for de-
tails. These are passed to routine INITIAL via modules and a few remnant COMMON blocks. When this
processing is complete, it is then known which subset of the STASHmaster records are required for the
particular UM experiment. The total number of STASHmaster records (including any user-defined records)
is passed to U MODEL and used to dynamically allocate the STASHwork arrays.
compress atmos stashmaster Called by U MODEL to compress the space taken by the STASHmaster to
only the active records.
INITCTL Is called by INITIAL to transfer the STASH control and addressing information to arrays that are passed
to the STASH system.
Below STASH PROC:
RDBASIS Reads the STASHC file information containing diagnostic requests, and combines this with configu-
ration details and sizes held in SIZES and CNTLATM files.
read atmos stashmaster Opens and reads STASHmaster records into dynamically allocated arrays. Func-
tions EXPPXC and EXPPXI are provided to extract individual character and integer elements (respectively)
of STASHmaster data from the STASHmaster arrays.
PRELIM Generates a preliminary STASHlist array.
OUTPTL Calculates output lengths for diagnostics.
INPUTL Calculates input lengths for diagnostics.
ADDRES Determines addresses for primary and diagnostic data in array D1 and for transient diagnostics in
workspace array STASHwork.
PRIMARY Computes data lengths and addresses for primary fields.
TSTMSK Selects prognostic fields required for the scientific configuration and checks availability of requested
diagnostics. This important routine often needs to be updated when new prognostics or physics options
are added to the model. A sudsidiary routine TSTMSK UKCA is called if the UKCA chemistry and aerosol
scheme is being run, to deal with the specific complexities of its data and diagnostics.
WSTLST Prints STASH control arrays and finalises STASH initialisation.
PSLEVCOD, PSLIMS Interpret any pseudo-level requests.

5 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

3.4 Primary addressing and reconfiguration

The computation of data lengths and start addresses within the D1 array for primary fields is carried out by
routine ADDRES. The reconfiguration uses its own code Rcf Address that performs a similar task for the recon-
figured dump addressing.
Each STASHmaster record includes a “version mask” and an “option code”. The version mask is a 20-digit
binary integer string that defines which UM releases this STASH item is available to. The option code is a 30-
digit decimal integer string, which defines the availability of the STASH item within the internal model section
to which it belongs. See Appendix C for details. In general, a given STASH item in a particular section will be
available for certain versions of that section and not for others.
TSTMSK is called — by PRIMARY from ADDRES within the model and Rcf Address within the reconfiguration
— to perform the checking of version masks and option codes, and so determine the list of primary items
required for the particular UM experiment. The same system is used to check availability of diagnostics. A
list of section-versions is read from the SIZES namelist file for TSTMSK to check option codes against. The
sudsidiary routine TSTMSK UKCA is called if the UKCA chemistry and aerosol scheme is being run, to deal
with the specific complexities of its data and diagnostics.
Rcf Address generates the list of primary items for the reconfigured dump, while ADDRES also computes the
data length and start address in D1 for each primary field, taking into account horizontal domains, vertical levels
and pseudo-levels.
In general, the output dump produced by a UM run may contain additional non-primary fields. This will be the
case if any of the diagnostic requests has the dump specified as their output destination. When a dump is
reconfigured, the dump produced will only contain the primary fields from the original dump. Only a continuation
run (CRUN) preserves and uses any diagnostics fields in the output dump from one run when it is read into the
next run in a series.

3.5 STASH Request Processing

The processing of STASH requests is described in outline here.

The overall function of the STASH request processing system is to convert the raw STASHC requests into
STASH control data arrays, which are passed to the STASH subroutine for each UM section. The control data
tell the STASH system how to process the output for each diagnostic in time and space, and where to send the
output (dump, fieldsfiles, etc.). The principal STASH control array is the “STASHlist”, see Appendix B.
STASH requests are held as a set of namelists in the STASHC file, see Appendix A. In addition to the many
individual diagnostics selectable from the standard list which the Rose GUI presents, the user may have defined
further diagnostics in STASHmaster A directly into their branch or working copy.
A STASHmacro was a standard set of diagnostics that a user may include as a single choice. STASHmacros
are NOT available under the Rose Gui. Users must provide a full set of STASH requests themselves; no doubt
standard sets will be set up and shared.
Each STASH request has associated time, domain, and usage profiles, which are also in the STASHC file.
Routine RDBASIS reads the STASHC file information into various arrays, and also reads additional information,
such as the section/version specifications and settings of various switches, from the SIZES file. Routine read -
atmos stashmaster reads in the STASHmaster information (as explained above).
Initial processing of the STASH requests is performed by routine PRELIM, which generates the preliminary
STASHlist array. Each STASH request gives rise to at least one STASHlist record. For some types of time
processing, e.g. meaning, there may be more than one STASHlist record (one for the partial sums and one for
the final result), depending on what the processing periods are and what the output destination is. After the
preliminary STASHlist has been set up, other routines are called to tidy it up in various ways.
The diagnostics that the user has selected through the Rose Gui from their Rose Suite (including any user-
defined ones, together with any diagnostics required for “STASH macros”), constitute the “activated diagnostics”.
Developers must ensure all diagnostics are fully supported by their code.
The output and input data lengths for each diagnostic are calculated next. The output length is generally given
by (no. of horizontal data points × no. of levels × no. of pseudo levels). (The only exception to this is in the

6 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

case of a time series diagnostic request.) Output lengths are calculated by routine OUTPTL. The input length
is in many cases the same as the output length, but there are a number of cases where the two will differ. For
example, the input to some diagnostics (the non-intercepted ones — see section 2) is allowed to be on a subset
of the possible levels rather than on all the levels. Suppose that such a diagnostic is requested a number of
times, each with different (and possibly overlapping) sets of output levels. In such a case, the input levels list
would be the superset of all the output levels, with any overlap levels being counted once only. Each of these
diagnostics would have an input length determined by the number of levels in the superset, and an output length
determined by the number of levels in its particular output list. The same situation can occur for input and output
pseudo levels. Routine INPUTL constructs the supersets and computes the input lengths. INPUTL also deals
with diagnostics for which the input must be on all available pseudo levels; in such a case, the range of pseudo
levels is supplied as a list in the same array that contains the supersets of pseudo levels.
After the diagnostic data lengths have been computed, routine ADDRES performs the addressing computations
for the diagnostic space in D1 and the STASHwork array, including any secondary space which may be required.
This is just a matter of adding up the lengths in the correct sequence to obtain the start address for each data
field. The capability exists for diagnostics to be copies of section 0 prognostics; in such a case, the appropriate
slot in the primary section of D1 is used for the diagnostic.
Sections 33 and 34 are further prognostic sections within the atmosphere STASHmaster file, so that larger
numbers (up to 150 initially) of free tracers and chemical species may be chosen. Section 34 is for the UKCA
chemistry submodel. The addressing code treats sections 33 & 34 (and sections 31, 32, 37 & 38 for lateral
boundary fields) in a similar way to prognostic section 0.

7 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

4 Execution of STASH within the model

Subroutine STASH is a general top-level service routine called in many locations within the model. It is the top-
level interface to subroutine STWORK, which is called for each STASH variable. At each timestep, subroutine
SETTSCTL is executed to set logical flags, known as STASHflags, to determine first whether certain diagnostic
code can be skipped, and then to select which diagnostics do require processing through STASH during this
timestep.

4.1 STWORK routine

The main stages of processing through STWORK are as follows:

Start loop over STASH requests for the same variable.
Determine input and output lengths and levels, and relative positions,
dependent on the type of processing:- simple extraction, spatial, time-series.
If spatial processing (e.g. sub-areas, global/meridional means):
Time-series: extract and process via routine MULTI_SPATIAL
Standard extraction: through routine SPATIAL
If not spatial processing:
Direct extraction and copying
Output:
Determine output stream for fieldsfile
Pack output data if requested, via
PP_FILE/COEX for WGDOS packing, or
GRIB_FILE for GRIB packing
Set up lookup headers in routine PP_HEAD and write header data to fieldsfiles
Output to D1 array (either for the model dump or to secondary space)
Time processing (e.g. time means, accumulations)
through TEMPORAL subroutine if requested
End loop over STASH requests for this variable.

4.2 STASH service routines

To copy data into the transient STASHwork arrays, 2 routines are provided:-
COPYDIAG_3D copies selected levels from a 3D array into STASHwork, and
COPYDIAG performs the same function for a simple horizontal field.
In both “new dynamics” and “ENDGame” atmosphere models, transfer of data is simplified because diagnostics
have no halos and there is no need for special treatment of polar rows. However it is preferable to continue
to use the service routines to provide for possible future developments, and to standardise this function in the
code.

8 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

5 Adding new fields (primary or diagnostics)

You will need to make these related changes:–

1. Modify the STASHmaster A file for Rose in your branch/working copy, and
2. Make code modifications for the selected variable.
Once code is in place, all service functions for writing to a fieldsfile or dump should be available.
Notes on modifying the STASHmaster A file under Rose, are given in Appendix D. It is usually simplest to copy
the entry for an existing diagnostic with characteristics similar to the one to be created. Either add an entry to
those already held in the STASHmaster A file (preferred option), or override an existing record with the same
STASH section and item number. Under Rose the user is directly responsible for any modifications needed to
“rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster A”. UMUI/STASHmaster checking has been
replaced by a Rose Gui STASH validation macro.

5.1 Adding diagnostics

For each new STASHmaster record, STASH PROC generates space in the STASHwork array for diagnostics,
and SETTSCTL sets STASHflags as required. Then all that is necessary is to copy the field containing the
new diagnostic into the STASHwork array in the relevant subroutine where diagnostics for that section are being
calculated. Suitable code would look like:-
REAL new_diagnostic_3d(3d_field), & ! new item1
new_diagnostic(2d_field) ! new item2
IF (sf(item1,sect).or.sf(item2,sect)) THEN ! only calculate if requested
CALL calculate_new_diagnostic(new_diagnostic_3d,new_diagnostic,......)
END IF
IF (sf(item1,sect)) THEN
CALL copydiag_3d(stashwork(item1,sect,im_index),new_diagnostic_3d,....)
END IF
IF (sf(item2,sect)) THEN
CALL copydiag(stashwork(item2,sect,im_index),new_diagnostic,...)
END IF
where new items 1 and 2 are in section sect, stashwork is the STASH work array for that section and other vari-
ables are available through the #include “argsts.h” Fortran include file, which includes sf, stlist and other related
information. The existing call to STASH for this section will process data in the STASHwork array without further
intervention. The array “sf” could be replaced with “sf calc” since we should only be interested in instantaneous
extractions rather then time processed STASH requests. See Appendix B.

5.2 Adding prognostics

From the new STASHmaster record, STASH PROC generates space in the D1 array for the new prognostic,
which will normally be in section 0, though sections 31 and 32 are used for lateral boundary conditions (LBCs),
section 33 for free tracers and section 34 for the UKCA chemistry model species.
To add a new prognostic field to the UM Atmosphere model, use the following steps.
First set up a new “jpointer” in SET ATM POINTERS. For a single-level field add the following generic code:-
JFIELD = SI(item_number,sect_no,im_index)
where sect no will be 0 or one of the above, and im index will be 1 (for atmosphere). The item number is the
new prognostic’s STASH code.
For a multi-level field also add the following additional generic code:-
DO lev = 2,n_levels
JFIELD(lev) = JFIELD(lev-1)+off_size
END DO

9 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

where n levels is the number of levels of the field, and off size is one of the predefined values u field size, u -
halo size, u off size, theta field size, theta halo size, theta off size, etc., depending on the grid and halos the
field uses.
Then modify UM INDEX A by adding a new entry to A IXPTR, e.g.:-
A_IXPTR(last_item+1) = A_IXPTR(last_item) + N_LEVELS
where N LEVELS is the number of levels of the field added to A IXPTR before this new one.
Increase the length of A SPPTR LEN as follows:-
A_SPPTR_LEN = A_IXPTR(last_item+1) + N_LEVELS
where N LEVELS is the number of levels of the new field.
Also increase the length of A IXPTR LEN in file spindex.h by 1 for each new prognostic, and add the new
“jpointer” to the include files artptra.h, argptra.h, and typptra.h.
A Fortran pointer for the new field is required in atm fields mod:-
REAL, POINTER :: FIELD(:)
and an entry in arg atm fields.h:-
FIELD, &
plus an entry in typ atm fields.h:-
REAL :: FIELD(tdims_s%i_start:tdims_s%i_end, &
tdims_s%j_start:tdims_s%j_end, &
tdims_s%k_start:tdims_s%k_end)
or similar, where tdims s values are for a theta-type field and p,q,u,v,w dims values are also defined, with s
indicating “small” halos and l “large” ones. The number of levels for the field is k end-k start+1..
Finally, in order to have access to the new prognostic in atm step the FIELD needs to be assigned to the
appropriate part of the D1 array in set atm fields.
E.g. field => D1(JField(qdims%k_start) : &
JField(qdims%k_start) + &
field_length(theta_points,extended_halo,qdims%k_end-qdims%k_start+1) -1)
The new prognostic can now be used as needed, such as passing it down to other subroutines from atm step.
The reconfiguration will also cater for new STASHmaster records of primary fields, allocating space in the re-
configured dump, and allowing selection of a number of types of initialisation. For more complicated initialisation
dependent on other variables in the dump, explicit coding will be needed in the reconfiguration.

10 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

6 Acronyms

AC Analysis/Correction assimilation scheme

BE Backward Euler. One of the two approaches to solving the chemistry in UKCA
CFMIP Cloud Feedback Model Intercomparison Project
COSP CFMIP Observational Simulator Package - satellite obs simulator
CRUN Continuation Run of the Unified Model
cylc Suite scheduling software used by Rose (replaces SCS)
ELF Rotated equatorial lat-long grid (as in NAE and UKV models)
ENDGame Even Newer Dynamical Core for UM (alternative to New Dynamics)
EURO4 Replacement for NAE, covering UK and Europe at 4km resolution
FLUME FLexible Unified Model Environment
GLOMAP-mode Global Model of Atmospheric Process - modal verison; Aerosol component of UKCA
GPCS General Purpose Computing System (Mainframe at the Met Office)
GUI generic Graphical User Interface
JULES Joint UK Land Environment Simulator
LAM Limited Area Model
LBC Lateral Boundary Condition (for a LAM model)
MDI Missing Data Indicator
MPP Massively Parallel Processing
NAE North Atlantic & European (a retired Met Office Limited Area Model)
NR Newton Raphson. One of the two approaches to solving the chemistry in UKCA
OASIS Ocean Atmosphere Sea Ice Soil (a model coupler)
PCR Plug Compatible Routine
PE Processing Element (of an MPP computer)
PRISM Partnership for Research Infrastructures in earth System Modelling
Program for Integrated earth System Modelling (a European consortium)
Rose (Met Office) Environment for Scientific Suites and Applications
SCS (Met Office) Suite Control System (replaced by cylc)
STASH Spatial and Temporal Averaging and Storage Handling (diagnostic output system)
STOCHEM An old chemistry model, no longer supported, replaced by UKCA
UKCA UK Chemistry and Aerosol - Atmospheric chemistry model interfaced with the UM
UK4 4km resolution limited area model covering United Kingdom
UKV Variable resolution LAM covering United Kingdom
UM (Met Office) Unified Model
UMDP Unified Model Documentation Paper
UMUI Unified Model User Interface (replaced by Rose Gui from vn9.0)
VAR Variational Assimilation scheme
vn UM version
WGDOS In-house method for packing output fields in a reduced no. of bits to a specified precision

Table 2: Acronyms

11 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

A STASH control file (STASHC)

A.1 STASHC, as read by UM code

The STASHC file is made up of namelists (namelist:streq(:) namelist:domain(:) namelist:time(:) namelist:use(:))

each of which may be configured by the Rose UM gui. A dedicated Rose STASH Gui has been developed to
perform this task under Rose. The file is in namelist format.
NAMELIST/STREQ/ Each STREQ defines a STASH diagnostic request:
ISEC Section number
ITEM Item number
DOM NAME Domain profile name, each described after the STREQ namelists block
TIM NAME Time profile name, each described after the DOMAIN namelists block
USE NAME Usage profile name, each described after the TIME namelists block
PACKAGE A name that can be used to group diagnostics together and help identify those groupings. For
example ”PPVAR LS” could be used to identify all diagnostics required for DA Linearised states.
Each named profile is unique and all STASH requests are colocated together; there are no separate STASH-
macro blocks as in the old UMUI STASHC version, but requests may be grouped by package.

NAMELIST/DOMAIN/ Each DOMAIN specifies a domain profile.

DOM NAME the name of domain profile, as requested within STREQ
IOPL Level type code:
1. Model rho levels
2. Model theta levels
3. Pressure levels
4. Geometric height levels
5. Single level
6. Deep soil levels
7. Potential temperature levels
8. Potential vorticity levels
9. Cloud threshold levels
For IOPL=1, 2 or 6 (“model” levels) specify ILEVS:
ILEVS=1 Contiguous range of model levels defined by LEVB,LEVT — first & last level.
ILEVS=2 Integer list (LEVLST) of specified levels. For IOPL=3 (pressure levels) specify RLEVLST — a real
valued list of required levels.
PLT Pseudo level type:
0 None
1 SW radiation bands
2 LW radiation bands
3 Atmospheric assimilation groups
8 HadCM2 Sulphate Loading Pattern Index
9 Land and Vegetation Surface Types
10 Sea ice categories

12 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

11 Number of land surface tiles x maximum number of snow layers

12–16 COSP pseudo level categories for satellite observation simulator project
?? (Aerosol emission classes — reserved but not yet implemented)
Pseudo levels are specified by an integer pseudo-levels list PSLIST. There is as yet no “contiguous range”
facility allowing them to be specified by first & last level only.
IOPA Horizontal domain type:
1. Global
2. N hemisphere
3. S hemisphere
4. 30–90 N
5. 30–90 S
6. 0–30 N
7. 0–30 S
8. 30S–30N
9. Area specified in whole degrees
10. Area specified in gridpoints
For IOPA=9,10 specify area limits INTH,ISTH,IWST,IEST
IMSK Gridpoint masking option:
1. All points
2. Land points only
3. Sea points only
4. Better use of non-MDI data in max/min time processing
IMSK=4 must be paired with a suitable Time profile, processing for max, min or accumulated values. It will
then use all non-MDI values instead of returning MDI if any value in the time window is MDI.
IMN Spatial meaning option:
0 None
1 Vertical
2 Zonal
3 Meridional
4 Horizontal area
IWT Weighting option:
0 None
1 Horizontal
2 Volume
3 Mass
TS Logical switch for time series option. If TS=.true., time series domains are defined by the following arrays:
TSNUM No. of time series domains
TNLIM, TSLIM, TELIM, TWLIM Horizontal domain limits
TBLIM, TTLIM Vertical limits (model levels)
TBLIMR, TTLIMR Vertical limits (real levels)

13 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

NAMELIST/TIME/ Each TIME defines a time profile.

TIM NAME the name of time profile, as requested within STREQ
ITYP Time processing code. Specifies how the diagnostic is to be processed and has the following values:
0 Not required by STASH, but space required. Turns off diagnostics that are not required for a particular
run but for which workspace is required within a PCR.
1 Replace. The default action.
2 Accumulate. Accumulates the output from a diagnostic over the model run. Accumulation may be
every timestep or less frequently, as defined by IOFF, ISAM and UNT2. Zeroing may take place at
times defined by INTV and UNT1.
3 Time mean. Again, means may be every timestep or less frequently, as defined by IOFF, ISAM and
UNT2. Zeroing may take place at times defined by INTV and UNT1.
4 Append time-series. Increases the size of a field with time.
5 Maximum. Gives max value over an interval defined by INTV and UNT1.
6 Minimum. Gives min value over an interval defined by INTV and UNT1.
7 Trajectories. Increases the size of a field with time.
INTV Processing period for options ITYP=2–7 (−1 for indefinitely).
UNT1 Units for processing period (1 timesteps, 2 hours, 3 days, 4 dump periods).
IOFF Offset, i.e. starting point for sampling if frequency not unity.
ISAM Sampling frequency for ITYP=2–7 options.
UNT2 Units for sampling frequency (1 timesteps, 2 hours, 3 days, 4 dump periods).
IOPT Switch for output times option:
1. Regular output times. Specify ISTR, IEND, IFRE — start time, end time, frequency.
2. List of output times at irregular intervals.
Specify ITIMES=no. of output times, ISER=list of times.
3. Range of dates for outputting data.
Specify start date ISDT and end date IEDT, each as 6 element arrays: Year, month, day, hour, minute,
second.
UNT3 Units for output times (1 timesteps, 2 hours, 3 days, 4 dump periods).
NAMELIST/USE/ Each USE specifies a usage profile.
USE NAME the name of usage profile, as requested within STREQ. Use these to group STASH requests into
a manageable set of output streams.
LOCN Output destination code:
1 Dump store with user specified tag
2 Dump store with climate mean tag
3 Write out to output stream
5 Mean diagnostic direct to mean fieldsfile
6 Secondary dump store with user tag
FILE ID Output stream file identifier string (for LOCN=3). Corresponds to the same set of dynamically allocated
file ids set in the NLSTCALL PP namelists.
MACROTAG User specified TAG (for LOCN=1,2,6)

14 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

B STASH list array and other STASH arrays

STASH related control information is defined in Fortran include file #include “typsts.h” and passed by argument
through #include “argsts.h”. This contains a number of arrays, the most significant being:-
STASHlist STlist(LEN STLIST,TOTITEMS) generated by STASH PROC and holding a single processed STASH
request in each row. All requests which are either active or require workspace are held; there are TOTITEMS
of them. Some are duplicated if they are to be processed in more than one way. The 33 entries in each row of
STlist, grouped by function, are:
• Item number — Section number
• Processing code
• Frequency — Start timestep — End timestep — Period
• Gridpoint code — Weighting code — Input bottom level — Input top level
• Northern row — Southern row — Western column — Eastern column
• Input code — Input length
• Output code — Output length in D1 — Output address in D1 — Output first level — Output last level
• Position of PP header for field in D1 — Pointer for time series
• STASHlist tag
• Input pseudo level list pointer — Output pseudo level list pointer
• Internal model identifier
• Position of item in D1 array for relevant sub model
• Offset for sampling
• Output address in dump — Output length in dump — Output length of a single level on dump
A description of the above entries now follows:
ENTRIES 1 & 2 STASH item (1–999) & section numbers (0–99),
but, in practice, ppxref sections (0–50).
ENTRY 3 Processing code.
Specifies how the diagnostic is to be processed.
0 Not required by STASH, but space required.
1 Replace
2 Accumulate
3 Time mean
4 Append time-series
5 Maximum
6 Minimum
7 Trajectories
ENTRY 4 Frequency (input and output).
Specifies the frequency at which processing occurs, in timesteps. The Rose Gui allows this to be entered
in a variety of units (hours, dump periods, etc.), and STASH PROC converts it to timesteps. Note that
a diagnostic can only be processed at those timesteps at which its model routines are called, and that
processing will occur only when the calling and processing timesteps coincide. E.g. if the LW radiation
PCR is called every 12 timesteps and the processing frequency is set to 8 timesteps (both starting at 0
timesteps), then no processing will occur until 24 timesteps. The Rose Gui should ensure that processing
of diagnostics from a section can only be requested at those timesteps at which that section is called.
A value of -n in entry 4 indicates that processing is required at the timesteps specified in the STASH output
times table STASHtimes(time,n). Entries 5–7 are then ignored.

15 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

ENTRIES 5 & 6 Start & End Timesteps.

Specify the timesteps at which processing starts/ends. The Rose Gui allows convenient time units to be
used. STASH PROC converts to timesteps.
ENTRY 7 Period.
Specifies the number of timesteps in the period for the accumulating and meaning options, and for the
recycling of the appending options, referred to in entry 3. May be specified as in entries 5 & 6. For the
appending options this entry defines the length of the time-series or trajectory dataset allocated.
ENTRY 8 Gridpoint code.
Specifies the gridpoints at which processing will occur.
1. All points
2. Land points (MDI for sea)
3. Sea points (MDI for land)
4. Full use of non-MDI gridpoint data in max/min time processing
In the following options m can be 1, 2 or 3, referring respectively to All points, Land points and Sea points.
1m Vertical mean over domain specified by entries 12–15,21–22
2m Zonal mean over levels specified by entries 21,22
3m Meridional mean over levels specified by entries 21,22
4m Field mean over domain specified by entries 12–15,21–22
Thus, options 1, 2 or 3 allow the simple extraction of a sub-field of the diagnostic, as defined by entries
12–15, while entries 1m–4m allow that sub-field to be meaned in various ways. Note that these fields will
be output over the full area and padded with missing data indicators if the data are not available for the full
model domain. Zonal and meridional means will always use the full model area.
ENTRY 9 Weighting code.
0 None
1 Horizontal area weighting
2 Volume weighting
3 Mass weighting
Note: warning — volume weighting has not been fully implemented and tested; mass weighting of diag-
nostics is not normalised.
ENTRY 10 Input first level.
Specifies the type of input level selection.
100 Indicates a single special level
-N Points to levels list N
M Input on range of model levels starting at level M
Note: warning — this could cause a problem when the number of model levels (currently 50–85) reaches
100.
ENTRY 11 Input last level.
Definition depends on Entry 10. If Entry 10 negative then: ENTRY 11 Levels list contains
1. model levels
2. pressure levels
3. heights
4. theta levels [+ soil]
5. PV levels (potential vorticity)
6. Cloud threshold levels

16 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

If Entry 10 = 100 then ENTRY 11 contains vertical level code LBVC If Entry 10 = M then ENTRY 11
indicates last input model level
ENTRIES 12–15 N/S rows, W/E columns.
Define the horizontal domain over which the diagnostic is processed. The GUI offers a number of preset
area options (e.g. 30N to 90N) and also allows the area to be specified in degrees lat/long or row/column
numbers. For a rotated equatorial lat/long grid (usually used for limited area models) the lat/long refers to
the transformed (rotated) coordinate system. If the lat/long specified does not coincide with model points
then the smallest area enclosing that specified will be computed.
ENTRY 16 Input code.
Specifies the source of the input to STASH.
0 Use primary field at D1(SI(item,section,model))
1 Use space at index SI(item,section,model)
-j Use diagnostic at D1(LIST S(20,j))
The STASHmaster item number within each section references output diagnostics in the PCR CALL argu-
ment. If the diagnostic is a primary field then D1(SI(item,section,model)) will be passed across in the PCR
CALL. If the diagnostic is transitory and calculated within workspace then STASHWORK(SI(item,section,model))
will be passed across. SI(i,s,m) will generally point to workspace. If no workspace is required at all then
the SI(i,s,m) will point to STASHWORK(1) to avoid allocating workspace that is not used. Option 0 allows a
primary variable to be processed by STASH. Option -j allows a diagnostic that has already been processed
into D1(LIST S(20,j)) to be reprocessed by STASH.
ENTRY 17 Input length.
The length of the diagnostic before STASH processing. This is computed by STASH PROC.
ENTRY 18 Output code.
Defines the output destination for the diagnostic. Has the following values:
1. Dump store
2. Secondary dump store
-nn. Output to Fortran unit nn
ENTRY 19 Output length.
The length of the diagnostic after STASH processing. This is computed by STASH PROC. Output length
will differ from input length if (for example) the levels on which output is requested are fewer than the levels
on which the diagnostic is input. For MPP jobs, it will be the length of the diagnostic for that PE.
ENTRY 20 Output address.
Start location of the diagnostic field in D1 after STASH processing. Used by STASH to locate diagnostics in
the dump which require reprocessing. In the MPP context, it is the start location in the D1 array containing
the data for that PE.
ENTRY 21 Output first level.
Specifies type of level selection required. Has the following values:
-N Points to levels list N
M Output on a range of model levels starting at level M
ENTRY 22 Output last level.
Definition depends on entry 21. If Entry 21 negative then:
ENTRY 22 is
1. Model levels
2. Pressure levels
3. Heights
4. Theta levels
5. PV levels (potential vorticity)

17 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

6. Cloud threshold levels

If Entry 21 = M then Entry 22 indicates last output model level
ENTRY 23 Position of PP header for field in D1.
Allows for whether each field is single or multi-level.
ENTRY 24 Pointer for time series.
References an entry in STASH SERIES INDEX, which in turn references a set of subdomain records in
STASH SERIES.
ENTRY 25 STASHlist tag.
Given by Tg+1000*Tm where Tg=user tag and Tm=time mean tag.
Tm is defined by Tm=M1 + 2*M2 + 4*M3 + 8*M4, where Mn=1 if the diagnostic is required in a climate
mean fieldsfile for climate mean period n, and Mn=0 if the climate mean is not required for period n.
n=1,2,3,4 allowing up to 4 climate meaning periods; typically month, season, year, decade.
For further details, see UMDP-C05 — Control of means calculations.
ENTRY 26 Input pseudo dimension list.
Points to the list of pseudo dimension indices defining the pseudo levels on which the field will be passed
to STASH. This will be the superset of all the output pseudo levels for that item.
ENTRY 27 Output pseudo dimension list.
Points to the list of pseudo dimension indices requested for output from the diagnostic.
ENTRY 28 Internal model id.
Atmosphere 1. [Ocean 2, Slab Ocean 3 — pre-UM7.0, Wave 4 — pre-UM6.2.]
ENTRY 29 Position of item in D1 array for relevant sub model.
The D1 ADDR array contains information relating to all items in the D1 array dimensioned by submodel,
whereas the STASH list includes information about diagnostics only, and is not dimensioned by submodel.
Entry 29 is a pointer to the records relating to the STASH item in the D1 ADDR array. For example, D1 -
ADDR(d1 address,STLIST(29,K)) gives the address in D1 for item K which differs from the dump address
because of the MPP decomposition.
Appendix E contains information on the D1 ADDR array in the Unified Model.
ENTRY 30 Offset for sampling.
When the sampling frequency is more than one time unit, it is possible to specify an offset.
For example, if sampling every 2 timesteps, then with a zero offset, timesteps 1,3,5,7. . . are sampled. With
an offset of 1, timesteps 2,4,6,8. . . are sampled.
ENTRY 31 Output address in dump.
Start location of the diagnostic field in the model dump.
ENTRY 32 Output length in dump.
The length of the diagnostic in the dump. For multi-level diagnostics, this will be the total length of the
diagnostic. Note that this length represents the full model grid and not the grid for the individual PE (see
Entry 19).
ENTRY 33 Output Length of a single level in dump.
See Entry 32. This is the length for a single level of the diagnostic. For single level diagnostics, entries 32
and 33 will be the same.
The model uses the STlist entries to produce a “PP-header” for each diagnostic which is processed to the dump
or fieldsfiles. If the diagnostic exists at multiple levels then after processing it will be stored as a number of fields,
each with its own PP header.
Other Arrays are:-

STTABL(NSTTIMS,NSTTABL)
The tables of processing times (input & output) for diagnostics which have a negative value in entry 4 of the
STASHlist record.

STASH LEVELS(NUM STASH LEVELS+1,NUM LEVELS LIST)

The levels lists are held in the 2-d STASH LEVELS array. The first element in each column is the no. of levels

18 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

in that list. The array is of type integer, suitable for model level numbers. When the levels are real values, e.g.
pressure (HPa) or theta (K) levels, they are multiplied by 1000, so allowing for an accuracy of 3 decimal places.

STASH PSEUDO LEVELS(NUM STASH PSEUDO+1,NUM PSEUDO LIST)

These are the lists of indices for pseudo-levels, which may be requested for any STASH item which has a
pseudo-dimension (e.g. radiation bands).

STASH SERIES INDEX(2,NSTASH SERIES BLOCK)

STASH SERIES(TIME SERIES RECORD LEN,NSTASH SERIES RECORDS)

Index to and table of subdomain records defining the sampling regions used for averaging when extracting time
series data from a field. Sampling regions may have up to 3 dimensions.

STASHindex STindex(2,NITEMS, 0:NSECTS,N INTERNAL MODEL)

Gives the starting index and number of indices for each STASH item. It is a pointer to the STlist.

SF(0:NITEMS,0:NSECTS)
STASHflags to determine whether this diagnostic is switched on or off this timestep. This is re-evaluated every
timestep in the subroutine SETTSCTL. If SF(0,section)=.false. then there are no STASH requests this timestep
for this section. This will include all STASH requests including output of time processed requests. If a field
is calculated on different timesteps (e.g. radiation timesteps) the time processed field will not coincide with a
timestep where the instantaneous value is valid. Please see sf calc below.

SF CALC(0:NITEMS,0:NSECTS)
STASHflags to determine whether this diagnostic is switched on or off this timestep with any time processing
requests removed. Time processing always has two STASH requests, one being the extraction of instantaneous
value and the other being an output from the time processing field. These do not always coincide so if you need
to know whether a diagnostic needs calculating then this array should probably be used. This is currently used in
radiation but should probably be used in all science sections which need to know whether to output a calculation.
This is re-evaluated every timestep in the subroutine SETTSCTL. If SF CALC(0,section)=.false. then there are
no STASH requests this timestep for this section.

SI(NITEMS,0:NSECTS,N INTERNAL MODEL)

Holds addresses of variables in D1 or STASHwork arrays.

The n internal model dimension has not been removed from these arrays, but is hard-wired to 1 as only the first
dimension, for atmosphere, is now valid.

19 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

C STASHmaster File Definition

There is one huge (1.1MB) STASHmaster file for the UM atmosphere model. STASHmaster A consists of a
series of 5-line records, one for each primary or diagnostic field, ordered by section number and item number.
Each record gives a complete definition of the characteristics of the field to which it refers. The STASHmaster A
file is used by the Rose Gui, reconfiguration, and the UM itself. Each released version of the UM has its own
STASHmaster file and users may modify the STASHmaster A file within a branch.
A single STASHmaster A contains both NewDynamics and ENDGame prognostics.
The template for each STASHmaster record is as follows:
#|Model |Sectn | Item |Name |
#|Space |Point | Time | Grid |LevelT|LevelF|LevelL|PseudT|PseudF|PseudL|LevCom|
#| Option Codes | Version Mask | Halo |
#|DataT |DumpP | PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PCA |
#|Rotate| PPFC | USER | LBVC | BLEV | TLEV |RBLEVV| CFLL | CFFF |
Model, Section, Item identify the record.
Model = 1, atmosphere; (2, ocean; 3, slab ocean; 4, wave; disused.)
Section numbers are in the range 0–50. Section 0 is for primary fields, section 33 for free tracer prog-
nostics and section 34 for UKCA tracer prognostics.
Item numbers are in the range 1–999.
Name is a 36-character description of the STASH item. SI units are assumed; otherwise units should be
specified as part of the name.
Space The space code. Specifies the space requirements of a STASH item. If a diagnostic is calculated only
when required by STASH (i.e. under a STASH flag), or is only copied to STASHwork under a STASH flag,
then the space code is 0. The possible values of space code are:
0 Diagnostic field for which space is required only when the diagnostic is requested.
2 Section 0, 33 or 34 items only: primary field available to STASH.
3 Section 0, 33 or 34 items only: primary field unavailable to STASH which is addressed in the dump
and D1. This is the case for fields which are not full horizontal fields, especially those compressed
onto land points only.
7 Non-primary field which points back to a section 0 field.
9 Extra items at the end of D1 for internal fields (i.e. fields required through the timestep, derived from
dump fields), including LBC input fields.
10 Field not held in D1 or the dump, including LBC output fields.
Point Section zero point-back. This is used for non-section 0 items with space code 7. Any such field is a copy
of a primary field. The value of “point” is the section 0 item number of which it is a copy.
Time Time availability code. Specifies at which timesteps the diagnostic or prognostic is available. The following
diagnostic time codes can be selected:
1 Every timestep.
2 Every long wave radiation timestep.
3 Every short wave radiation timestep.
4 Every coupling period.
13 Every convection timestep.
14 Every leaf phenology timestep
15 Every vegetation competition timestep.
16 Every river-routing timestep.

20 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

17 Every UKCA chemistry timestep.

The following prognostic time codes can be selected:
18 Every long wave radiation timestep.
19 Every short wave radiation timestep.
Grid Grid type code. Specifies the type of grid on which the field is defined.
1 Data on atmospheric theta points.
2 Data on atmospheric theta points, values over land only.
3 Data on atmospheric theta points, values over sea only.
4 Data on atmospheric zonal theta points.
5 Data on atmospheric meridional theta points.
11 Data on atmospheric uv points.
12 Data on atmospheric uv points, values over land only.
13 Data on atmospheric uv points, values over sea only.
14 Data on atmospheric zonal uv points.
15 Data on atmospheric meridional uv points.
17 Atmospheric scalar.
18 Data on atmospheric u points on the ’c’ grid.
19 Data on atmospheric v points on the ’c’ grid.
21 Data compressed to atmospheric land points.
22 Data on the ozone grid.
23 Data on the river-routing grid.
26 Lateral boundary data at atmospheric theta points.
27 Lateral boundary data at atmospheric u points.
28 Lateral boundary data at atmospheric v points.
29 Orography field for atmospheric LBCs.
LevelT The level type code. Specifies the type of levels on which a field is defined.
0 Unspecified level.
1 Data on atmosphere rho levels.
2 Data on atmosphere theta levels.
3 Data on pressure levels.
5 Single level data.
6 Data on deep soil levels.
7 Data on theta levels.
11 (Data on ISCCP levels - not supported.)
LevelF and LevelL The first and last level codes. Specify the first and last levels on which a field is defined.
-1 Unset, this code must be used for single level data.
1 First atmospheric level.
2 Top atmospheric level.
3 Top wet level.

21 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

4 Top atmospheric level-1.

5 First level in boundary layer.
6 Last level in boundary layer.
7 First level above boundary layer.
8 First soil level.
9 Last soil level.
10 First tracer level (allowed to be > 1).
11 Last tracer level (= Top atmospheric level).
12 Last gravity wave drag level +1.
13 First gravity wave drag level.
14 Last gravity wave drag level.
15 First level in vertical diffusion routine.
16 Last level in vertical diffusion routine-1.
17 Last level in vertical diffusion routine.
18 Last level in boundary layer -1.
19 Top level of atmosphere +1.
20 First soil level+1.
23 Top ozone level.
24 Number of atmos levels * sw bands.
25 (number of atmos levels+1) * sw bands.
26 (number of wet levels)* sw bands.
27 Number of atmos levels * lw bands.
28 (number of atmos levels+1) * lw bands.
29 (number of wet levels)* lw bands.
32 Number of SW radiation bands.
33 Number of LW radiation bands.
34 Number of soil hydrology levels.
35 Number of cloudy levels.
38 Zeroth atmospheric level, i.e. when lowest level is the surface (used for vertical velocity, radiation
increments, boundary layer stresses)
39 Number of ISCCP levels. (Not supported)
40 Indicator for bottom level. 0 for Endgame and 1 for New Dynamics.
Note that most derived levels (e.g. X* sw bands) are redundant - use pseudo levels instead.
PseudT Pseudo level type. This code defines the type of pseudo level that the diagnostic is defined on.
0 None
1 SW radiation bands.
2 LW radiation bands.
3 Atmospheric assimilation groups.
4 Radiation bands for calculating aerosol optical depth
8 HadCM2 Sulphate Loading Pattern Index

22 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

9 Land and Vegetation Surface Types.

10 Multiple-category sea-ice.
11 No. of land surface tiles multiplied by maximum no. of snow layers.
12 COSP Radar Reflectivity bins.
13 COSP Number of Hydrometeors.
14 COSP Backscattering ratio bins.
15 COSP ISCCP tau bins.
16 COSP Maximum number of subcolumns allowed to be output.
?? (Aerosol emission classes - reserved but not yet implemented.)
Further information on particular pseudo-level types:
Radiation bands for calculating aerosol optical depth are hard-wired to 6 wave-lengths: 380, 440, 550,
670, 870 and 1020nm.
Surface types under pseudo-level type code 9 (also related to pseudo-level type code 11):
0 - Aggregation over all surface types1
1 - Broadleaf Tree
2 - Needleleaf Tree
3 - C3 Grass
4 - C4 Grass
5 - Shrub
6 - Urban
7 - Water
8 - Soil
9 - Ice
PseudF First pseudo level code. Defines the lower bound of the possible values of pseudo level for a field.
1 Dimension starts at 1.
20+n Dimension starts at the first group for the atmospheric assimilation set n. Sets are:
1. P* observation type.
2. Theta observation types.
3. U,V observation types.
4. Relative Humidity observation types.
5. Rainfall rate observation types.
PseudL Last pseudo level code. Defines the upper bound of possible values of the pseudo level for a field.
1 The number of short wave bands.
2 The number of long wave bands.
3 The number of bands on which aerosol optical depth is calculated
6 The number of sulphate loading patterns.
7 The total number of surface types.
8 The number of surface types that are vegetation.
1 It is possible to run JULES aggregating the surface properties onto a single tile. If this has been done then surface fields that are on

pseudo levels will be output with a pseudo level code of 0. This indicates they are aggregated properties.

23 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

9 The number of land surface tiles.

10 Number of sea-ice categories.
11 New snow scheme: (all tiles) * (max no. of snow levels)
12 COSP Radar Reflectivity bins
13 COSP Number of Hydrometeors
14 COSP Backscattering ratio bins
15 COSP ISCCP tau bins
16 COSP Maximum number of subcolumns allowed to be output
20+n The last group for the atmospheric assimilation set n.
The values of the upper bounds can be found in the UM deck PSLIMS.
LevCom The level compression flag. This code defines which of the available levels are passed as input to
STASH.
0 STASH receives input on all available levels and pseudo-levels.
1 STASH receives the diagnostic input on the STASH input levels list.
Compression is performed in either the routine or the interfacing. A flag of 1 must be used for multi-level
items not on model levels.
Option Code The sectional option code.
The option code is a 30-digit decimal code which defines under what conditions an item is unavailable to
STASH. Each STASH section has its own definitions for the option codes. The digits are labelled from left
to right n30,n29,. . . ,n1. The rules for interpretation of the option codes are as follows. The UM subroutine
src/control/top level/tstmsk.F90 performs this task in both the reconfiguration and the model.
N.B. Rationalisation of existing codes and a future extension of available codes were implemented at
vn7.5. This resulted in changes to a number of STASHmaster records. In section 0, n10n9 is a 2-digit
code to cater for the “Classic” aerosol scheme’s many options.
Available in all Atmosphere sections — VAR reconfiguration indicator.
n17 VAR reconfiguration indicator
0 Item not required for VAR reconfiguration.
1 Item included for VAR reconfiguration.
Atmosphere sections 0,31,32,33,34,36,37 — Prognostics (including tracers) and LBCs.
See later for any option codes used separately for sections 31, 32, 33 & 34.
n3n2n1 Tracer number. Values up to 150 allowed for section 33 free tracers and sections 36, 37 - lateral
boundary conditions for free tracers and UKCA respectively.
Item included only if the n3n2n1 tracer switch is set.
n3 Hydrology indicator.
0 Item not dependent on hydrology scheme.
5 Item included for large scale (TOPMODEL) hydrology scheme.
n4 Aerosol climatology indicator.
0 Item not dependent on any aerosol climatology.
1 Item included only for biogenic aerosol climatology (stash code 351).
2 Item included only for biomass burning aerosol climatology (stash 352,353,354).
3 Item included only for black carbon aerosol climatology (stash codes 355,356).
4 Item included only for sea salt aerosol climatology (stash codes 357,358).
5 Item included only for sulphate aerosol climatology (stash codes 359,360,361).

24 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

6 Item included only for dust aerosol climatology (stash codes 362–367).
7 Item included only for organic carbon fossil fuel climatology (stash 368,369,370).
8 Item included only for delta aerosol climatology (stash code 371).
n5 Orographic roughness or slope indicator.
0 Item not dependent on orographic roughness.
1 Item included when orographic roughness used.
2 Item included when orographic gradients used in GWD.
3 Item included when orographic slope correction used in SW radiation.
4 Item included when using unfiltered orography for horizon angles.
n6 Interface indicator.
0 Item not dependent on interface.
1 Item included only in limited area models.
2 Item included only for models with lower boundary.
n7 Coupling indicator.
0 Item not dependent on coupling.
1 Item included only if OASIS coupling is used.
2 Item currently unconditionally excluded.
3 Item currently included if OASIS coupling is used, with an iceberg calving ancillary.
7 Coupled run with DMS ocean flux, but always excluded. (Redundant)
n8 Extra fields indicator.
0 Item not dependent on extra fields.
1 Item included only for SST anomaly runs.
2 Item included only for decoupled screen temperature.
3 Item included only for deep convective gusts scheme.
4 Item included only for total aerosol runs.
5 Item included only for total aerosol emission runs.
6 Item included only if snow albedo scheme used.
7 Item included only if tke closure scheme used.
8 Item included only if Energy Adjustment Scheme (section 14) used.
9 Item included only if Thunderstorm Electrification Scheme (section 21) used.
n10n9 “Classic” aerosol indicator. (Items 2, 3, 4, 6 and 9 not available if UKCA is using the new emissions
scheme (l ukca new emiss=.TRUE.).
0 Item not dependent on any “Classic” aerosol scheme.
1 Item included only for SO2 sulphur cycle.
2 Item included only for SO2 with surface emissions.
3 Item included only for SO2 with high level emissions.
4 Item included only for SO2 with natural emissions.
5 Item included only for SO2 with DMS cycle.
6 Item included only for SO2 with DMS cycle and emissions.
7 Item included for SO2 with O3 oxidation included.

25 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

8 Item included for SO2 with O3 oxidation and NH3 included.

9 Item included only for SO2 with O3 oxidation and NH3 emissions.
10 Item included only for SO2 with online oxidants
11 Item included only for SO2 with DMS cycle and emissions.
21 Item included for soot scheme only.
22 Item included for soot scheme with surface emissions.
23 Item included for soot scheme with high-level emissions.
24 Item included for biomass scheme only.
25 Item included for biomass scheme with surface emissions.
26 Item included for biomass scheme with high-level emissions.
27 Item included for mineral dust scheme, both 2- & 6-bin (prognostic).
28 Item included for mineral dust scheme, 2- & 6-bin (diagnostic lifting only).
31 Item included for nitrate scheme.
35 Item included for organic carbon fossil fuel (OCFF) scheme.
36 Item included for OCFF scheme with surface emissions.
37 Item included for OCFF scheme with elevated emissions.
38 Item included for mineral dust scheme, 6-bin only (prognostic).
n11 Vegetation parametrization indicator.
0 Item not dependent on vegetation parametrization.
1 (Removed) Item included only if direct vegetation parametrization not used.
2 Item included only for direct vegetation parametrization with or without competition.
3 Item included only for direct vegetation parametrization with competition.
4 Item included only when the surface SW albedo is constrained to observations.
5 Item included only when the surface VIS and NIR albedos are constrained to observations.
6 Item included only if separate aggregation of thermal roughness lengths is enabled.
n12 Mixed phase precipitation.
0 Item not dependent on Mixed phase precipitation.
3 Item included if Mixed phase precip and prognostic cloud ice (crystals) used.
4 Item included if Mixed phase precip and prognostic rain used.
5 Item included if Mixed phase precip and prognostic graupel used.
6 Item included if PC2 cloud scheme included.
7 Item included if Turbulent mixed phase cloud scheme is in use.
n13 Convective cloud amount, radiation and history indicator. (CCRad scheme treats effects of convective
cloud on radiation more consistently)
0 Item not dependent on convective cloud.
1 Item included only if CCA is 2D (anvil code OFF).
2 Item included only if CCA is 3D (anvil code ON).
3 Item included only if CCRad scheme used.
5 Item included only if store convection history fields in dump.
n14 Available.

26 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

n15 Carbon cycle indicator.

0 Item not dependent on carbon cycle.
3 Item included for carbon cycle.
n16 JULES surface exchange scheme indicator.
0 Item not dependent on JULES scheme.
1 (Removed) Item included if JULES snow scheme is used.
2 Item included if multiple layer JULES snow scheme is used.
3 Item included if snow soot albedo effect is used.
4 Item included if URBAN-2T/MORUSES scheme is used.
5 Item included if FLAKE lake scheme is used.
n17 VAR reconfiguration indicator. (Usable in all Atmos sections)
0 Item not required for VAR reconfiguration.
1 Item included for VAR reconfiguration.
n18 Coastal tiling, river routing, sea surface and sea-ice categories indicator.
0 Item not dependent on these surface schemes.
1 Item included only if coastal tiling is used.
2 Item included if open sea albedo uses variable chlorophyll content.
3 Item included if river routing scheme is used.
4 Item included if inland basin flow scheme is used.
5 (Reserved for grid-2-grid LAM river routing scheme — not yet implemented.)
6 Item included if single sea ice category selected.
7 Item included if multiple sea-ice categories selected.
8 Item included if sea ice categories fully used.
9 Item included if multi-level sea ice scheme is used.
n19 Tropopause based ozone indicator.
0 Item not dependent on tropopause based ozone scheme.
1 Item included only if tropopause based ozone is used.
n20 Thermal Vegetation Canopy Indicator.
0 Item not dependent on thermal vegetation canopy.
1 Item included for snow canopy scheme.
n21 Separate convective cloud amount indicator
0 Item not dependent on separate convective cloud amounts
1 Item included if deep convection cloud amount is used
2 Item included if mid-level convection cloud amount is used
3 Item included if shallow convection cloud amount is used
n22 Available.
n23 Available.
n24 Available.
n25 Photosynthetically Active Radiation (PAR) indicator.

27 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

0 Item not required.

3 Included if PAR increments used (not currently active)
n26 Available.
n27 Available.
n28 Cariolle ozone tracer scheme indicator.
0 Item not dependent on Cariolle ozone tracer scheme.
1 Included if Cariolle ozone tracer transport and basic chemistry used
n29 Endgame model indicator
0 Item not dependent on Endgame switch.
1 Included if Endgame model is being used.
2 Excluded if Endgame model is being used.
n30 Option codes metacharacter.
0 Use the standard set of option codes above.
n Use set ”n” option codes. (Currently unused; allows for future expansion.)

Atmosphere section 1 - Shortwave Radiation.

n1 Global model indicator.
0 Item not dependent on global/LAM option.
1 Item available only for global atmosphere.
n2 Cloud Microphysics indicator.
0 Item not dependent on cloud microphysics.
1 Item available only if cloud microphysics used.
n3 HadCM2 approximate radiative effects of sulphate indicator. (UM vn4.3 to vn5.4 incl.)
0 Item not dependent on HadCM2 approximate radiative effects of sulphate.
1 Item available only if HadCM2 approximate radiative effects of sulphate used.
n4 Indirect effect of sulphate aerosol (SA) in SW Radiation.
0 Item not dependent on Indirect effect of SA in SW radiation.
1 Item available only if Indirect effect of SA in SW radiation requested.
n5 Effect of Sea-Salt parametrization in SW Radiation.
0 Item not dependent on effects of Sea-Salt in SW Radiation.
1 Item available only if direct or indirect effects of Sea-Salt in SW radiation requested.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud Scheme is used.

Atmosphere section 2 - Longwave Radiation.

n1 Matching of ozone tropopause.
0 Item not dependent on this option.
1 Item available if this option selected.
n6 PC2 Cloud Scheme indicator.

28 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

0 Item not dependent on cloud scheme.

1 Item available only if PC2 cloud Scheme is used.
n7 COSP satellite observation simulator (no code implemented in tstmsk.F90)
0 Item not COSP related
1 Item available as COSP diagnostic

Atmosphere section 3 - Boundary Layer.

n1 Orographic roughness indicator.
0 Item not dependent on orographic roughness.
1 Item available only if orographic roughness is used.
n2 SO2 sulphur cycle/NH3/Soot indicator.
0 Item not dependent on sulphur cycle or soot scheme.
1 Item available only if SO2 sulphur cycle used.
2 Item available only if NH3 scheme used.
3 Item available only if soot scheme used.
4 Item available if biomass scheme is used.
5 Item available if mineral dust scheme is used.
6 Item available if organic carbon fossil-fuel (OCFF) scheme is used.
7 Item available if nitrate scheme is used.
8 Item available if mineral dust scheme diagnostics are used.
n3 Carbon cycle indicator.
0 Item not dependent on carbon cycle.
1 Item included only for carbon cycle used.
n4 Multiple sea-ice categories indicator.
0 Item not dependent on multiple sea-ice categories.
1 Available if multiple sea-ice categories selected.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud scheme is used.
n7 Mineral dust scheme indicator.
0 Item not dependent on mineral dust scheme.
1 Item available if 2- or 6-bin dust scheme is used
2 Item available only if 6-bin dust scheme is used

Atmosphere section 4 - Large scale precipitation.

n2 SO2 sulphur cycle/NH3/Soot indicator.
0 Item not dependent on sulphur cycle or soot scheme.
1 Item available only if SO2 sulphur cycle used.
2 Item available only if NH3 scheme used.
3 Item available only if soot scheme used.

29 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

4 Item available if biomass scheme is used.

5 Item available if mineral dust scheme is used.
6 Item available if organic carbon fossil-fuel (OCFF) scheme is used.
n5 Turbulent mixed phase scheme indicator
0 Item not dependent on turbulent mixed phase scheme.
1 Item available only if turbulent mixed phase scheme is used.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud scheme is used.
n7 Mineral dust scheme indicator.
0 Item not dependent on mineral dust scheme.
1 Item available if 2- or 6-bin dust scheme is used
2 Item available only if 6-bin dust scheme is used

Atmosphere section 5 - Convection.

n2 SO2 sulphur cycle/NH3/Soot indicator.
0 Item not dependent on sulphur cycle or soot scheme.
1 Item available only if SO2 sulphur cycle used.
2 Item available only if NH3 scheme used.
3 Item available only if soot scheme used.
4 Item available if biomass scheme is used.
5 Item available if mineral dust scheme is used.
6 Item available if organic carbon fossil-fuel (OCFF) scheme is used.
n3 2D or 3D convective cloud amount indicator.
0 Item not dependent on convective cloud.
1 Item included only if CCA is 2D (anvil code OFF).
2 Item included only if CCA is 3D (anvil code ON).
n4 Indicator to allow whole convection scheme to be switched off.
0 Item not available if convection option switched off
1 Item remains available if convection section included but convection switched off.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud scheme is used.
n7 Mineral dust scheme indicator.
0 Item not dependent on mineral dust scheme.
1 Item available if 2- or 6-bin dust scheme is used
2 Item available only if 6-bin dust scheme is used

Atmosphere section 6 - Gravity Wave Drag.

n2 Orographic Drag scheme indicator.

30 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

0 Item not dependent on orographic drag scheme.

1 Item available if orographic drag scheme is used.
n3 Spectral gravity wave indicator.
0 Item not dependent on spectral gravity wave scheme.
1 Item available if spectral gravity wave scheme is used.

Atmosphere section 8 - Hydrology.

n1 Large scale (TOPMODEL) hydrology scheme.
0 Item not dependent on TOPMODEL hydrology scheme.
1 Item available if TOPMODEL hydrology scheme is used.
n22 River routing diagnostics.
0 Item not dependent on river routing scheme.
1 Item available only if river routing scheme included.
2 Item available only if inland basin flow scheme included.
Atmosphere section 9 - Cloud Parametrization.
n2 Cloud area parametrization indicator.
0 Item not dependent on cloud area parametrization.
1 Item available only if cloud area parametrization used.
n3 RHcrit parametrization indicator.
0 Item not dependent on RHcrit parametrization.
1 Item available only if RHcrit parametrization used.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme
1 Item available only if PC2 cloud scheme is used.
Atmosphere section 12 - Primary Field Advection.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud scheme is used.
Atmosphere section 16 - Extra physics diagnostics.
n2n1 The tracer number.
Item available only when the n2n1 tracer switch is set.
n6 PC2 Cloud Scheme indicator.
0 Item not dependent on cloud scheme.
1 Item available only if PC2 cloud scheme is used.
Atmosphere section 17 - CLASSIC Aerosol section.
n1 Aerosol scheme indicator.
0 Item not dependent on aerosol schemes.
1 Item included only for sulphur cycle.
2 Item included only for soot scheme.
3 Item available if biomass scheme is used.

31 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

4 Item available if dust scheme is used.

5 Item available if OCFF (organic carbon fossil fuel) scheme is used.
6 Item available if biogenic aerosol scheme is used.
7 Item available if Sea-salt PM scheme is used.
8 Item available if nitrate aerosol scheme is used.
9 Item available if any of the above aerosol schemes is used.
n2 Sulphur cycle options indicator.
0 Item always included in sulphur cycle.
1 Item included only if DMS included.
2 Item included only if O3 oxidation included.
Atmosphere section 18 - Data Assimilation.
n1 Non-prognostic IAU increment indicator. (From vn6.1)
0 Item not used.
1 Item will be searched for in IAU increments file.
Atmosphere section 21 - Thunderstorm electrification
n2 Scheme selection indicator
0 Available to all schemes
1 Only available when the McCaul et al (2009) lightning scheme is used.
Atmosphere section 26 - River routing.
n22 River routing diagnostics.
0 Item not dependent on river routing scheme.
1 Item available only if river routing scheme included.
2 Item available only if inland basin flow scheme included.
Atmosphere section 31 - Lateral boundary updating.
n6 Interface indicator for boundary values and tendencies.
1 Item included only in limited area models.
Atmosphere section 32 - Lateral boundary generation.
n8 Extra fields indicator.
0 Item not dependent on extra fields.
4 Item included only for total aerosol runs.
n12 Mixed phase precipitation.
0 Item not dependent on mixed phase precipitation.
3 Item included only if mixed phase precip and prognostic cloud ice crystals is used.
4 Item included only if mixed phase precip and prognostic rain is used.
5 Item included only if mixed phase precip and prognostic graupel is used.
6 Item included only if mixed phase precip and PC2 could scheme is used.
Atmosphere section 33 - Free tracers.
n3n2n1 - The tracer number (range 1–150).
Item included only if n3n2n1 free tracer switch is set.
Atmosphere sections 34 and 50 - UKCA chemistry scheme prognostics and diagnostics.

32 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

n30 The option codes for UKCA prognostics and diagnostics are used slightly differently from other sec-
tions to deal with the highly complex requirements of the UKCA chemistry and aerosol scheme and
to allow for future expansion of the code without needing a major redesign. The logic for the UKCA
option codes sits in its own subroutine tstmsk ukca which is located in the UKCA directory.
If the option code is all zeros, the item is always available (to preserve compatibility with other sec-
tions). If the option code is non zero and UKCA is not on then the item is never available.
If UKCA is on then the code first tests the value of n30 to establish whether the item depends on the
chemistry scheme or the aerosol configuration.
n30=0 The availability of this item depends on the chemistry scheme in use. The code then tests the
value of a specific option code depending on the chemistry. This is the list of which option codes are
tested for which chemistry schemes:
• n1 = Only used by Age-or-air tracer, active if n1=1 and L UKCA AGEAIR = .TRUE.
• n2 = BE Tropospheric
• n3 = BE RAQ
• n4 = NR TropIsop
• n5 = NR StratTrop
• n6 = NR Strat
• n7 = NR Offline oxidants
• n8 = BE Offline oxidants
If the checked option code is zero, then the item is not available. If it is 1 then is available. If it is 2
then it is only available when using the extension to chemistry for aerosol modelling. Other possible
values can be considered depending on the user needs; as an example (since vn9.1), if n3=3 then
the item will only be available when the new emission system is turned ON (i.e. if l ukca new emiss
is TRUE).
n30 = 1 The availability of this item depends on the set up of the GLOMAP-mode aerosol scheme in use.
If GLOMAP-mode is off the item is not available. The code then tests the value of a specific option
code depending on the value of i mode setup. If the checked option code is zero, then the item is not
available. If it is 1 then it is available.
• n1 = i mode setup = 1
• n2 = i mode setup = 2
Atmosphere section 36 - Free tracer lateral boundary updating.
n3n2n1 - The tracer number (range 1–150).
n6 Interface indicator for boundary values and tendencies.
1 Item included only in limited area models.
Atmosphere section 37 - UKCA tracer lateral boundary updating.
n3n2n1 - The chemical species number (range 1–150).
n6 Interface indicator for boundary values and tendencies.
1 Item included only in limited area models.
Version Mask. A 20 digit binary code. Each STASH section can have up to 20 versions, and each version uses
some subset of the item numbers in that section. Version 0 of a section is the null version, i.e. that section
is not activated, so none of the STASH items in that section would be available to the run. The UM inputs
define which versions of each section are available. Some sections use i ¡section¿ vn runtime variables
to select the various versions, other only have a single version available. The version mask digits are
numbered from right to left; a 1 in position N implies that this item is available to version N of that section.
A 0 implies that it is not. E.g. a section version of 6A (or 6B or 6C, etc.) would have a version mask of
00000000000000100000

33 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

A single UM routine src/control/top level/h vers mod.F90 maintains the links between the runtime code
and the version mask in the STASHmaster, so to check whether a diagnostic is actually available to a
certain code version.
Halo Halo code. Defines size of halo.
1. Single point halo.
2. Extended halo.
3. No Halo.
DataT Data type code: 1 Real, 2 Integer, 3 Logical.
DumpP PP LBPACK code for data in the dump. See UMDP-F03 .
PC1-A Packing accuracy codes. These codes are used to control packing of data within fieldsfiles at output.
Values for each of the output streams are set in the GUI via the NLSTCALL PP namelists (one per output
stream). The types of packing currently allowed are:-
PC1 WGDOS packing profile 1 — Operational output
PC2 WGDOS packing profile 2 — Standard Climate output (OLD)
PC4 WGDOS packing profile 4 — Stratosphere model output
PC5 WGDOS packing profile 5 — Standard Climate packing
PC6 GRIB packing takes a positive value unlike the above WGDOS packing schemes
PCn values are interpreted as follows:-
-99 outputs the fields in an unpacked state, irrespective of the chosen packing profile.
For GRIB packing value indicates number of bits used.
WGDOS fields are packed to an absolute precision of 2**PackCode. The number is usually negative, so
a packing code of -1 gives an accuracy of 0.5 (1/2), -3 an accuracy of 0.125 (1/8) etc.
The packed number is stored in the format: data = offset + scale factor * packed value
The algorithm packs each model row separately. On each model row the offset is set to the minimum
value in that row. Each model row uses a different offset. The scale factor is expressed as a power of
2. E.g. in a temperature row with a maximum of 300K, a minimum of 285K and a packing code of -1, the
offset would be 285 and the scale factor would be 0.5. Therefore, the value 290.2 would be stored as: 285
+ 0.5 * 10 and when decoded the precision constraint means the value would become 290.0.
In addition to the precision, there is a second constraint when choosing a packing code. The total size
of the number used to represent the packed value cannot be more than 32 bits. In practical terms this
means that if you choose a packing code which is too accurate the packing will fail. E.g. to pack 1.0E6
with a packing code of -13 (absolute accuracy of 2**-13=0.00012207) you need 33 bits. This is too high
an accuracy and WGDOS packing will fail. The absolute accuracy you want determines an upper limit on
the packing code and the biggest value you need to pack (after subtracting the offset) provides a lower
limit on the packing code. To check your packing code is safe you need to estimate the maximum range
you are likely to have on a model row. The packing accuracies are ignored if the whole output stream is
set to “not packed”.
Further examples showing how to choose appropriate packing codes are shown in appendix F.
Rotate Rotation code. This is for wind diagnostics. It indicates whether STASH receives the wind components
relative to the rotated model grid or the regular lat/long grid (for ELF models).
0 Data are either non-vectorial or is relative to the model’s grid.
1 Data are passed to STASH relative to the lat/long grid.
PPFC PP field code. This is the field code defining the data to (older) PP graphics applications and is only used
to specify the PP header item (23=lbfc) on output. A list of currently reserved PP field codes is maintained
at the Met Office; if further details are required please contact the UM system team. Example lbfc codes:
0 unspecified for PP applications
1 height
8 pressure

34 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

16 temperature
USER Not used.
LBVC PP vertical coordinate type. Defined and documented in UMDP F03, this is the field code defining the
vertical coordinate of an output field to (older) PP graphics applications, i.e. such that there is a common
value for each horizontal field. LBVC is used to specify the PP header item (26=lbvc) on output, but is also
required within STASH to generate other PP header output items, such as (52=blev) in the correct format.
Example lbvc codes:
0 level unspecified
1 height
8 pressure
65 hybrid height (as atmosphere model levels)
128 mean sea level
129 surface level
130 tropopause level
131 maximum wind level
132 freezing level
BLEV,TLEV Not used - set to 0. [Originally defined as base/top level reference codes, but the appropriate PP
output header items are set dynamically in STASH.]
RBLEVV Not used - set to 0. [Originally defined as ref lbvc=LBRVC, but the appropriate PP output header
items are set dynamically in STASH.]
CFLL, CFFF Historical, operational level/field codes used on the GPCS. These are field codes defining the
data to the output process applications and are only used within the UM to specify the PP header
items (33=lblev;32=lbtyp) on output. Specifically these are still required for some operational applications
through the FFREAD utility on the GPCS. For non-operational fields set CFLL=CFFF=0. Set CFLL=8888
for no level or special level; =9999 for surface.
Rules for the Level Compression Flag The value of the level compression flag determines whether the
input to STASH from a field is passed in on all available levels and pseudo levels (flag=0) or on a list of
specified levels (flag=1). The only restrictions on the flag value are:
(1) Any item with a non-zero space code must have a levels flag of zero.
(2) Any item with levels type 3,4,7,8, or 9 (non-model levels) must have a levels flag of 1.
(3) If the levels type is 5 (single level) then the flag is zero if the pseudo-type is zero, and 1 if the pseudo-
type is non-zero.
If the levels type is 1, 2 or 10 (model levels) then the flag may be 0 or 1 (0 for an intercepted diagnostic —
see above).

35 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

D Updating STASHmaster Records

Users may define their own STASHmaster records which can either supplement the records in the system
STASHmaster or overwrite existing STASHmaster records. By this means users can obtain new diagnostic,
prognostic and ancillary fields, or correct existing STASHmaster records.
It is important to choose a new STASHitem number for any new record, so that conversion routines and post-
processing can deal with a new set of STASHmaster records without confusion. For Met Office users, STASH-
master files for each model version can be found from the UM Homepage under Metadata. There is also a
link to a list of STASH codes reserved for the future versions; requests for new STASHitem numbers should be
made to [email protected].
The user must also provide appropriate changesets to the source code to calculate any new field they define in
this way and interface it to the STASH routines.
Care should be taken when making new records to copy the line formatting precisely as a small error (e.g.
in packing code) can cause a large problem which may not become apparent until the STASH routines are
executed and new diagnostics viewed. See C or below for details.
If a new STASH record is a prognostic the user must specify an initialisation choice in the corresponding Rose
metadata and GUI panel.
The format for any STASHmaster record is shown below. The header sections H1,H2,H3, labels and end-of-file
are already in STASHmaster A. Any line starting with a # is ignored by Rose and the UM. Note the following:
(1) Most integers do not have leading zeros, but the option code and version mask are strings of single
integers and must have all 30 or 20 digits including leading zeros.
(2) The exact spacing of all the entries is most important.
H1| SUB MODEL_NUMBER=1
H2| SUBMODEL_NAME=ATMOS
H3| UM_VERSION=9.2
#
#|Model |Sectn | Item |Name |
#|Space |Point | Time | Grid |LevelT|LevelF|LevelL|PseudT|PseudF|PseudL|LevCom|
#| Option Codes | Version Mask | halo |
#|DataT |DumpP | PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PCA |
#|Rotate| PPFC | USER | LBVC | BLEV | TLEV |RBLEVV| CFLL | CFFF |
#
#=================================================================
#
1| 1 | 16 | 245 |USER DIAGNOSTIC XXXX |
2| 0 | 0 | 1 | 1 | 3 | 10 | 11 | 0 | 0 | 0 | 1 |
3| 000000000000000000000000000000 | 00000000000000000001 | 0 |
4| 1 | 1 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
5| 0 | 528 | 0 | 8 | 0 | 0 | 0 | 0 | 0 |
#
1| 1 | 16 | 246 |USER DIAGNOSTIC YYYY |
2| 0 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 1 |
3| 000000000000000000000000000000 | 00000000000000000001 | 0 |
4| 1 | 2 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
5| 0 | 529 | 0 | 8 | 0 | 0 | 0 | 0 | 0 |
#
#=================================================================
#
1| 1 | 18 | 1 |USER DIAGNOSTIC ZZZZ |
2| 7 | 1 | 1 | 1 | 5 | -1 | -1 | 0 | 0 | 0 | 0 |
3| 000000000000000000000000000000 | 00000000000000000001 | 0 |
4| 1 | 2 | -3 -3 -3 -3 -3 -3 -99 -99 -99 -99 |
5| 0 | 8 | 0 | 129 | 0 | 0 | 0 | 9999 | 12 |
#

36 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

#=================================================================
#
1| -1 | -1 | -1 |END OF FILE MARK |
2| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
3| 000000000000000000000000000000 | 00000000000000000000 | 0 |
4| 0 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
5| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
#

37 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

E D1 Addressing Array Contents

The D1 ADDR array holds a list of information about all objects in the D1 array. A single or a multi-level field
counts as one object. Note that when running in MPP mode (now the default), each processing element (PE)
has its own copy of D1 and, therefore, its own D1 ADDR array. The number of objects in D1 for each submodel
is stored in a one-dimensional array called NO OBJ D1.
Note that the only submodel in the UM is now the Atmosphere one; coupling to other submodels, e.g. Ocean/Sea-
ice, is implemented using OASIS coupling routines.
Information in D1 ADDR is used primarily for gathering and scattering of fields between PE0 and all the other
PEs. These operations occur mainly in the climate meaning, dumping, and fieldsfile output routines.
D1 ADDR includes pointers to the equivalent objects in the STLIST and LOOKUP arrays, and similarly STLIST
information includes a pointer to D1 ADDR (see the D1 ADDR d1 stlist no and d1 lookup ptr elements, and the
STLIST st position in d1 element). Note that D1 ADDR is still dimensioned by submodel=1, whereas STLIST
is not. Therefore, when looping through the STASH list, check that the internal model identities compare. The
following code example shows how the cross-referencing between arrays can be used. It loops through the
STLIST items and selects only those in the atmosphere submodel :
#include "typd1.h" ! Contains header file d1_addr.h
! Get pointer to the partition of D1_ADDR relating to atmosphere
MODNUM=SUBMODEL_FOR_SM(atmos_im)
DO IE=1,TOTITEMS ! Loop over STLIST entries
! Get pointer to element in D1_ADDR array
PTD1=STLIST(st_d1pos,IE)
! Compare internal model ids - ocean items would not match.
IF(STLIST(s_modl,IE).eq.D1_ADDR(d1_imodl,PTD1,MODNUM))THEN
! This STASH item is part of the atmosphere submodel
Accessing information in D1 ADDR
The D1 ADDR array is held within the same super-array as D1 and is carried, with D1, in argd1.h and artd1.h.
The D1 ADDR array has three dimensions:
INTEGER D1 ADDR(D1 LIST LEN,NO OBJ D1 MAX,N SUBMODEL PARTITION)
D1 LIST LEN Number of items of information held about each object.
NO OBJ D1 MAX Number of objects in biggest submodel.
N SUBMODEL PARTITION Number of submodel partitions (the partition number and submodel ident are both
1 from vn7.0 onwards).
Some of the information from the D1 ADDR array is output as a table “Addressing of D1 array”. The
information held about each object in the d1 addr.h header file is as follows:
1. d1 object type: can be set to prognostic=0, diagnostic=1, secondary diagnostics=2 and other=3.
“other” means space code 9 items (such as exner theta levels or dual time ocean diagnostics).
2. d1 imodl: internal model identity number. e.g. 1 for Atmosphere.
3. d1 section: section number.
4. d1 item: item number.
5. d1 address: address in D1. For MPP this refers to the addressing of the local D1.
6. d1 length: length of the local record.
7. d1 grid type: grid type; from STASHmaster file.
8. d1 no levels: number of levels including pseudolevels.
9. d1 stlist no: a pointer to the STASHlist array. Set to −1 for prognostics.
10. d1 lookup ptr: a pointer to the dump header lookup table.
11. d1 north code: address for the northern row; from STASHlist record.

38 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

12. d1 south code: address for the southern row; from STASHlist record.
13. d1 east code: address for the eastern column; from STASHlist record.
14. d1 west code: address for the western column; from STASHlist record.
15. d1 gridpoint code: from STASHmaster file.
16. d1 proc no code: from STASHmaster file.
17. d1 halo type: from STASHmaster file.
Unused elements of the array are initialised to −1. These unused elements would include STASH related
information for prognostic items (prognostic items have no STASH entries).

39 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

F Choosing an appropriate WGDOS packing accuracy

Author: Harry Shepherd, Last Updated: 15th January 2015

F.1 Background

This chapter makes use of the following notation in the worked examples.

D(min) Minimum value of data in a field

D(max) Maximum value of data in a field
∆ = D(max) − D(min) Range of data in a field
S Packing accuracy code (PC1-PC5)
A = 2S Absolute packing accuracy
n Number of bits to pack
In = 2n−1 − 1 Maximum size of an n bit signed integer

When choosing a packing accuracy there are several competing concerns

• The size of the output file. Packing with as few bits as possible produces the smallest packed file, however
this leads to limitations with the accuracy of the data.
• Data Accuracy The more bits used to pack, the larger the packed file but the more accurate the packed
data will be. WGDOS packing is an example of a lossy algorithm.
• Word size WGDOS packing will only pack a maximum of a 32 bit signed integer (31 bits to represent
the data), providing a lower bound on the the value for A. If you need higher accuracy then do not use
WGDOS packing.
To determine a packing code, we can start from the description of WGDOS packing described in appendix C.

∆ = In 2S (1)

and then solve for S to give

log (∆/In )
S= (2)
log(2)

To determine the number of bits required to pack a field, we can write an expression for the accuracy
∆
A= (3)
In

and recalling that In = 2n−1 − 1

∆+A
2n−1 = (4)
A
and solve for n
log (A + ∆) − log (A)
n= +1 (5)
log (2)

F.2 Worked Examples

F.2.1 Example 1: Determine range of suitable packing codes

Problem: A data field has a minimum value of -10 and a maximum of 40. Determine the range of packing codes
that can be used to represent this data in a WGDOS packed fields file.

40 c Crown Copyright 2015

 UMDP: C04
Storage Handling and Diagnostic System (STASH)

Solution. To determine the most negative packing code (greatest accuracy) we pack with the full 32 bits avail-
able. Therefore, starting from equation 2 we can say

log (∆/I32 )
S = (6)
log (2)
 
1 50
= log (7)
log (2) 232−1 − 1
= −25.31. (8)

As the packing code must be an integer, and the above expression provides a lower limit, we round to the
nearest larger integer to give a minimum value for S of -25.
To determine the upper bound for a packing code, we require at least one data bit, which corresponds to a 2 bit
signed integer. In this case however all values will be set to either the maximum or minimum value in the field.

log (∆/I2 )
S = (9)
log (2)
 
1 50
= log (10)
log (2) 22−1 − 1
= 5.6 (11)

As this is an upper bound, we round to the nearest smaller integer to give a upper bound of 5. It is unusual
however to see positive packing codes.

F.2.2 Example 2: Determine number of bits required to pack with a given accuracy

Problem: A data field has a range of values from 5 to 25. We wish to pack with an accuracy of 2.4 × 10−7 (a
packing code of -22). How many bits are required to pack with this accuracy?
Solution: Starting from equation 5 we can say

log (∆ + A) − log (A)

n = +1 (12)
log (2)



log 20 + 2.4 × 10−7 − log 2.4 × 10−7
= +1 (13)
log (2)
= 27.3 (14)

Round this value up as the number of bits must be an integer, so we require a 28 bit signed integer to store the
data.

F.2.3 Example 3: Is it possible to pack a given row of data?

Problem: A data field has a range of values from 10 to 100, and we wish to pack with an accuracy of 5 × 10−10
(a packing code of -31). Is this possible?
Solution: As in the above example, we start from equation 5, and substituting the values for range and accuracy
we solve to give
n = 38.4 (15)
and rounding up we would require 39 bits to pack this data. This is greater than the 32 bit limit imposed by the
WGDOS algorithm, so this data can not be packed at this accuracy.

41 c Crown Copyright 2015