Unified Model Documentation Paper 304

Adding a New Input Variable to the UKCA Interface

UM Version : 10.1
Last Updated : 2014-12-05 (for vn10.0)
Owner : Luke Abraham

Contributors:
N. Savage and L. Abraham

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: 304
Adding a New Input Variable to the UKCA Interface

Contents
1 Introduction 2

2 UkcaD1codes array 2

3 Key subroutines and procedure 2

4 Tracers and Emission 3

5 Adding a new item 3

5.1 Declare a new variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.2 Match the variable name to a STASHcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.3 Set the new variable as required and set dimensions . . . . . . . . . . . . . . . . . . . . . . . . 4
5.4 Turn on the new diagnostic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

6 Gotchas 5

7 Debugging 6

1 c Crown Copyright 2015

 UMDP: 304
Adding a New Input Variable to the UKCA Interface

1 Introduction

The interface to the UKCA chemistry and aerosols sub-model is different from that for other sections. UKCA
uses prognostic and diagnostic fields stored in the D1 array as inputs. The purpose of the interface is to define
the fields required by the chemistry/aerosol scheme, check that these exist in the D1 array, and to extract and
reshape the data into a named array in UKCA. The interface also writes prognostics back into the D1 array either
for use elsewhere in the UK (e.g. tracer transport or radiative exchange) or for use in a subsequent timestep
(e.g. aerosol area for use in the tropospheric heterogeneous chemistry).
Adding a new variable to the interface is not difficult but does involve making several different modifications to
the code. This guide explains all the steps needed to carry this out and some pitfalls to avoid.
The UKCA inteface can take prognostic fields as input or diagnostics fields from other sections. This means that
any diagnostic which can be output by a MetUM parametrization can potentially be used as input to the UKCA
sub model. However, you should be careful to consider whether the diagnostic is an appropriate one. It may be
useful to talk to an expert in that parametrization scheme before using it as input.
This note does not deal with the UKCA diagnostics, nor does it deal with the trace gas and aerosol fields used
in radiative exchange.

2 UkcaD1codes array

This array defines the fields required from the D1 array, and is organised as a structure with the following
elements:
• section: section of UM (integer)
• item: item number of required field (integer)
• n levels: number of levels (integer)
• address: address in D1 (integer)
• length: length of array in D1 (integer)
• halo type: halo type (integer)
• grid type: grid type (integer)
• field type: field type (integer)
• len dim1: length of array dimension 1 (integer)
• len dim2: length of array dimension 2 (integer)
• len dim3: length of array dimension 3 (integer)
• prognostic: True if prognostic (logical)
• required: True if required (logical)
• name: Field name (optional) (character,len=10)
This array and the associated type are defined in the ukca d1 defs module. It is allocated and populated by
subroutine ukca setd1defs. Only section, item, len dim1, len dim2, len dim3, prognostic, and required are filled
at this stage. The other integer items are filled from the D1 addressing array (d1 addr) in ukca main1.

3 Key subroutines and procedure

The following subroutines and module are the key ones which may need to be altered:
• ukca d1 defs. This module defines the arrays used by the interface to specify the list of items required.

2 c Crown Copyright 2015

 UMDP: 304
Adding a New Input Variable to the UKCA Interface

• ukca main1 - in file ukca main1-ukca main1.F90. This is the top level subroutine for UKCA and contains
allocatable arrays which are a key part of the interface.
• ukca setd1defs. The main purpose of this routine is to allocate and populate the UkcaD1codes array
which defines the prognostics and diagnostics needed by UKCA. Using logical switches, it is possible to
turn off some of the items from the interface. In order to define the tracers and emissions used by each
scheme, the number of tracers and emission are associated with the schemes (defined by logicals), and
this in turn helps defines the length of the UkcaD1codes array.
• getd1flds - also in file ukca main1-ukca main1.F90. This is where stash codes are matched to variable
names, and the arrays for each variable allocated and populated with data. If a STASHcode exists in this
subroutine it is possible to set up an array for the data. However, this does not control whether this input
is expected by the UKCA code.
• ukca extract d1 data. This is a generic subroutine call made from getd1flds to point to subroutines (e.g.
ukca extract d1 data3d) via an interface block in getd1flds. Each item calls one of these subroutines to
read the data in D1, reshape the one-dimensional array and fill the named array in ukca main1.
• putd1flds - also in file ukca main1-ukca main1.F90. This routine writes the tracers and other prognostics
back into the D1 array.
The general procedure is controlled from ukca main1 which: 1) calls ukca setd1defs; 2) loops through all the
items in D1 and matches these with those requested in the UkcaD1codes array; 3) when a match is found
fills the remaining parts of the UkcaD1codes array; 4) calls getd1flds to which allocates and fills the named
arrays from the D1 array; 5) calls putd1flds to write tracers and non-transported prognostics back to D1; and
6) deallocates the arrays. This procedure relies on the relevant diagnostics being placed in the D1 array via
STASH using a usage profile which places the item in ”secondary store with user specified tag”, and with a
time profile of ”No time processing. Field valid at output timesteps.” Prognostic items do not need processing in
STASH, but note that some section zero items are not prognostics. Error checking of the number of tracers, the
availability of the items in D1, and the size of the anticipated field in D1 is carried out.

4 Tracers and Emission

The chemical scheme in use defines the tracers in the chch defs array, and the number of tracers is also defined
according to the schemes in use in ukca setd1defs. For the strattrop chemistry with aerosol chemistry and the
GLOMAP-mode aerosol scheme, n chem tracers=71, n aero tracers=12, and n mode tracers=31. The nm -
spec (tracer names array) is used to check if the entry in the tr ukca a array is true for the particular tracer. For
Newton-Raphson schemes H2O is added to the tracers from the specific humidity. There is a check to ensure
that the number of identified tracers is equal to the number of tracers expected. For Newton-Raphson schemes,
the tracers may be reordered if the tracer order in the chemical scheme is different from the tracer order in the
STASHmaster file defined by the nm spec array in UKCA.
The number and species of the emissions required by the combines aerosol/chemistry scheme in use are
defined by the integers n chem emissions and n 3d emissions together with the character array em chem -
spec. This array is generated and used in the ukca setd1defs subroutine to define the emission diagnostics
required and to set the size of the UkcaD1codes array.

5 Adding a new item

5.1 Declare a new variable

First in subroutine ukca main1 declare the new variable you want to add to the interface as an allocatable array.
For example the declaration for theta is:
REAL, DIMENSION(:,:,:), ALLOCATABLE :: theta
Be sure to declare the variable with the correct number of dimensions.
At the end of ukca main1, add a deallocate to prevent memory leaks e.g.

3 c Crown Copyright 2015

 UMDP: 304
Adding a New Input Variable to the UKCA Interface

IF (ALLOCATED(theta)) DEALLOCATE(theta)

5.2 Match the variable name to a STASHcode

Now edit the subroutine getd1flds to create the variable. Find the appropriate UM section for the variable you
wish to add (e.g. prognostics are in section 0, boundary layer in section 3). Then add a call to ukca set array -
bounds to get the correct array size, allocate the array and then call ukca extract d1 data to copy the data from
the D1 array to your new variable. For example for theta we have:
! Prognostics: fill appropriate array

ELSE IF (UkcaD1codes(N)%section == 0 .AND. &

UkcaD1codes(N)%prognostic) THEN
SELECT CASE(UkcaD1codes(N)%item)
CASE(4)
! DEPENDS ON: ukca_set_array_bounds
CALL UKCA_SET_ARRAY_BOUNDS(N,I1,I2,J1,J2)
ALLOCATE(theta(I1:I2,J1:J2, &
ukcaD1codes(N)%len_dim3))
CALL UKCA_EXTRACT_D1_DATA( &
#include "argd1.h"
first,N,theta)
The item number for theta is 4 so that is the value we have in the CASE clause.

5.3 Set the new variable as required and set dimensions

In ukca setd1def first increase the number of items for the section you are adding the diagnostic from in the
following code block.
n_in_progs = 41 ! max no of progs reqd other than tracers/ems
n_in_diags0 = 4 ! max no of diags (sect 0) reqd
n_in_diags1 = 2 ! max no of diags (sect 1) reqd
n_in_diags2 = 1 ! max no of diags (sect 2) reqd
n_in_diags3 = 19 ! max no of diags (sect 3) reqd
n_in_diags4 = 5 ! max no of diags (sect 4) reqd
n_in_diags5 = 4 ! max no of diags (sect 5) reqd
n_in_diags8 = 1 ! max no of diags (sect 8) reqd
n_in_diags15 = 1 ! max no of diags (sect 15) reqd
n_in_diags30 = 1 ! max no of diags (sect 30) reqd
So if you wanted one extra item from section 1 (SW radiation) you would increase n in diags1 from 2 to 3.
Then find the appropriate section and add the new item. For example for section 1 (SW radiation) we currently
have
! Diagnostic items from section 1 (SW radiation)
J = J + n_in_diags0

UkcaD1Codes(J+1:J+n_in_diags1)%section = 1
UkcaD1Codes(J+1:J+n_in_diags1)%prognostic = .false. ! always needed
UkcaD1Codes(J+1:J+n_in_diags1)%required = .true.
UkcaD1Codes(J+1)%item=201 ! Net downward surface SW flux
UkcaD1Codes(J+1)%len_dim1=row_length
UkcaD1Codes(J+1)%len_dim2=rows
UkcaD1Codes(J+2)%item=235 ! Total downward surface SW flux
UkcaD1Codes(J+2)%len_dim1=row_length
UkcaD1Codes(J+2)%len_dim2=rows
If you were adding item Section 1, Item 294 - slope angle, you would add the following lines:

4 c Crown Copyright 2015

 UMDP: 304
Adding a New Input Variable to the UKCA Interface

UkcaD1Codes(J+3)%item=294 ! Slope angle

UkcaD1Codes(J+3)%len_dim1=row_length
UkcaD1Codes(J+3)%len_dim2=rows
Only include the dimensions required and do not add any halo information here. The halos are automatically
included from the D1 addressing arrays.
The order of the items in each section does not have to be STASH code order. If you do insert an item you must
correctly renumber all following statements. As this is error prone it is recomended that at present, you just add
any new items at the end of the correct section. Note that by default all items added here have the logical flag
required set to true. This means that the UKCA interface will always expect this to be input from the model. It is
possible to control this using logic. For example, we do not need item 3.473 unless the activate scheme is on.
Therefore we have the code:
UkcaD1Codes(J+19)%item=473 ! Turbulent Kinetic Energy
UkcaD1Codes(J+19)%len_dim1=row_length
UkcaD1Codes(J+19)%len_dim2=rows
UkcaD1Codes(J+19)%len_dim3=bl_levels
IF (.NOT. L_UKCA_ARG_ACT) UkcaD1Codes(J+19)%required=.false.
Finally, be sure that you set the dimensions of the new variable correctly. Note that some input variables are
only defined on land points. For example soil moisture is on land points and also has a second dimension of
soil model levels:
UkcaD1Codes(J+2)%item=9 ! Soil Moisture
UkcaD1Codes(J+2)%len_dim1=land_pts
UkcaD1Codes(J+2)%len_dim2=sm_levels

5.4 Turn on the new diagnostic

Finally if you are using a diagnostic variable as input to UKCA, you need to ensure that it is available to UKCA.
This is done by setting up a STASH request for the new item via the STASH section of the rose GUI. Open the
STASH window (under namelist → Model input and output → Stash requests and profiles → Stash requests)
and output the diagnostic on all model timesteps, with the appropriate domain profile for that variable. and with
a tagged usage profile for UKCA. This should already be set up if the app you are using has UKCA on. The
usage profile has the following settings :
• locn - specify the destination of the diagnostic. Select the radio button marked ”Dump store with user
specified TAG”
• iunt - specify the output stream or TAG required for diagnostic output. Set this to 98.

6 Gotchas

• If the memory required by the model constantly increases, check that you have remembered to include
the deallocate of the array. If this is not included, then a new version of the array is created each timestep
causing a memory leak.
• If the model crashes, or behaves oddly you may have made a mistake in numbering the new item in
ukca setd1defs - check very carefully.
• Another reason for crashes might be that you have added a new input variable with the incorrect dimen-
sions in ukca setd1defs.
• If you forget to set up stash then UKCA will not be able to find the data and will stop with an error similar
to:
? Error in routine: UKCA_MAIN
? Error Code: 3074
? Error Message: Item address not found in D1 array
? Error generated from processor: 0

5 c Crown Copyright 2015

 UMDP: 304
Adding a New Input Variable to the UKCA Interface

The error code is the stash code of the item it cannot find.
• Not all diagnostics are available for all UM configurations. If this is the case, there will be a warning
message from the UM at run time: Warning Message: DIAGNOSTIC NOT AVAILABLE TO THIS VERSION
REQUEST DENIED (M,S,I) 1 3 74 and then UKCA will fail with a similar message to that above. You need
to find out why this diagnostic is not available for your model set up.
• If there is a difference between the size allocated in UKCA and the size in the D1 addressing array then
the model will stop with the following error messsage:
Array sizes in local variable and D1 do not agree
The relevant sizes are written to the output. In this case check that the dimensions of the array are correct
compared with those in the STASHmaster file.
• The routine called from GETD1FLDS to extract the array from D1 is UKCA EXTRACT D1 DATA. This is a
generic call which actually refers to an interface block in GETD1FLDS which selects the actual subroutine
to be used on the basis of the arguments. Currently there are routines which deal with 1-D, 2-D, and 3-D
real arrays and 2-D integer and logical arrays. If you need to import any other type of array, then a new
subroutine must be supplied and an entry made in the UKCA EXTRACT D1 DATA interface block.

7 Debugging

If you encounter difficulties, then debug checks of the UkcaD1Codes array can be made by setting PRINT -
STATUS to ”Extra diagnostic messages”.
Turning this on should trigger the following outputs:
1) From UKCA SETD1DEFS:
UKCA: UkcaD1Codes array items:
section, item, prognostic, required, dim1, dim2, dim3
2) From UKCA MAIN1:
UKCA Prognostics and Diagnostics from D1:
section,item,levels,length,address,halo_type,grid_type,field_type
With this you can check that the item has been requested (required is TRUE) and whether it has been identified
in the D1 addressing arrays (address will be non-zero).
A simple check on the contents of many UKCA input arrays is done by write statements added to UKCA MAIN1
to the section labelled ’ MAX and MIN of UKCA INPUTS from D1’, e.g.
WRITE(ummessage,*) ’p_rho_levels: ’,mype,k, &
MAXVAL(p_rho_levels(1:row_length,1:rows,k)), &
MINVAL(p_rho_levels(1:row_length,1:rows,k))
CALL umprint(ummessage,src=’ukca_main1-ukca_main1’)
These are printed to output when the print status has been set to ”operational” or ”extra diagnostic messages”.

6 c Crown Copyright 2015