Unified Model Documentation Paper C05

Control of Means Calculations

UM Version : 10.1
Last Updated : 2015-04-22 (for vn10.1)
Owner : Harry Shepherd

Contributors:
S. Mullerworth, P. Selwood, H. Shepherd

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: C05
Control of Means Calculations

Contents
1 Introduction 2

2 Overview 2

3 Programming aspects 4

4 Logical Structure 5
4.1 Normal procedure in MEANCTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.2 Abnormal end in MEANCTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3 Additional notes about Gregorian calendar climate meaning . . . . . . . . . . . . . . . . . . . . 5

1 c Crown Copyright 2015

 UMDP: C05
Control of Means Calculations

1 Introduction

This document describes the purpose and structure of the system designed for long period (such as annual or
decadal) time-meaned calculations in the Unified Model, and is referred to in the following text by its task code,
C5. The subroutines written to execute this task are designated as ‘control’ rather than ‘meteorological’ and
adhere to the standards set down in UMDP-003 .
The climate means system provides the ability to calculate means of data over very long periods; calculation
of decadal means is quite normal. Conventional STASH meaning cannot provide such a facility because the
accumulation of data over a long periods results in loss of precision and uneven sampling because as the period
goes on, the partial sums become much larger than the data resulting in inaccurate addition. The climate means
overcomes this problem by calculating, say, a series of monthly means, then calculating a seasonal mean from
3 monthly means and an annual mean from 3 seasonal means. In this way, the numbers in the partial sums
always remain manageable.
Climate means calculations can be summarised as follows. Data from one or more diagnostic fields are sampled
once every restart period (also known as dumping period as this is the point at when a restart dump is written).
The means of these data are calculated and output at the end of a defined ”period 1” meaning period. Period
2 meaning periods can also be defined which are a multiple of the period 1 meaning period. Up to 4 levels of
meaning can be defined.
As an example, a typical climate job which produces restart dumps every 10 days might have a period 1 mean
period of 3 restart dumps which thus provides a monthly mean. Three period 1 mean periods provide a seasonal
mean. Four period 2 mean periods define an annual mean and ten period 3 mean periods define a decadal
(period 4) mean.
A nominal reference point for all period means can be specified and is known as the mean reference time. In
the example above, it is normal to specify the 1st of December of some year so that no matter what the starting
point for the model run (the model basis time), the seasonal means will align themselves with the seasons,
grouping December, January and February for winter, March, April and May for spring, and so on.
Mean data are calculated from accumulated data stored in partial sum files. There are four levels of partial
sum files to store the sums for the four levels of meaning period. All data fields selected for climate meaning is
accumulated in all levels of partial sum files but not all data fields have to be output to the climate mean PP files
for every period level.
Production of time-meaned data can occur in integrations using either a 360-day year (i.e. climate runs) or a
Gregorian year (used by forecasts and some climate runs), and are of limited use in operational forecast mode.
When used with the Gregorian calendar the meaning periods are restricted to monthly, seasonal and annual.

2 Overview

gth of the different levels of meaning period, the mean reference time and the climate mean diagnostics requests
are generally set up using the gui. After starting a model run, none of these settings should be changed without
restarting the run as a new run (NRUN).
If the 360-day calendar is used, the period 1 period is expressed as an integral multiple of the restart dump
period; the latter being the fundamental unit for means calculations. The period of the next order of means is
expressed as a multiple of the preceding period. C5 will deal with a maximum number of 4 meaning periods
provided the above criteria are satisfied. As an example, periods of 10/3/3/4 would represent 10-day, 30-day,
90-day and 360-day means being requested if the restart dump frequency were daily. If less than 4 period
means are required, the redundant figures should be set to zero. The system allows one to create seasonal
means without creating monthly means, e.g by setting the frequencies as 90/4/10/0, or to create annual means
without producing seasonal means.
If the Gregorian calendar is used, only three possible meaning periods are available; period 1 corresponding to
a calendar month, period 2 to a season1 , and period 3 to a year. It is not possible to produce Gregorian seasonal
or annual means without producing monthly and seasonal means respectively, but one can choose not to output
1 Winter (December, January, February), Spring (March, April, May), Summer (June, July, August), and Autumn (September, October,

November)

2 c Crown Copyright 2015

 UMDP: C05
Control of Means Calculations

unwanted means. Period 4 means (conventionally 10 years) are not currently available with Gregorian climate-
meaning, but could be available if the meaning code was modified so that it could calculate the number of days
in any 10 year meaning period. Restart dumps can be produced either at a user specified frequency, at the
end of a calendar month, at the end of a cycle in a cycling suite, or some combination of the above. The user
defined frequency can either be a day or greater, or a period smaller than a day, provided that period divides
evenly within a day. Note that for dumping periods shorter than a day, partial sum files will be produced at this
dump frequency, however for longer dumping periods the partial sums will be produced daily.
Prior to UM vn5.1 the format of a partial sum dump was identical to the format of a restart dump. In fact all fields
in the dump were averaged whether or not they were required as climate meaned diagnostics. An optimisation
introduced at UM vn5.1 sums only those fields required by the climate means system and stores the sums in
a basic format with a simple header. The filenames of partial sum dumps relate to the period number of the
partial sum they contain. The user is able to input a “base” filename via the psum_filename_base input to the
nlstcgen namelist, and the additional information is appended by the code as follows:
• Name provided in psum_filename_base: “/path/to/directory/psum_file_”
• Periods 1-4 partial sums: “/path/to/directory/psum_file_(p)(i)” where “(p)” stands for the mean
period number and “(i)” is an indicator that toggles between “a” and “b” for the two files in the partial sum
pair.
Note each of the periods has two files which are used alternately so that a partial sum is not overwritten by the
next sum in the same period. In this way, if the run were to fail during the writing of a partial sum, the previous
sum is still available.
Prior to UM vn5.1 it was possible to create time-meaned dump containing a mean of all the fields in the dump.
This facility was never used and has been removed.
Once the main job is executing, partial sum data will be read in, processed and written to the appropriate dump
when necessary. The instantaneous dump will be written out to disk whenever means need to be evaluated
from partial sum data, in order to release space in memory, and restored when all means processing has been
completed. It suffices to say that C5 will deal with all data transfers when necessary in a way which should be
transparent to the user.
The procedure for creating time-meaned dumps is straightforward and general, and can be summarised as
follows:
Accumulating data in a period n partial sum dump is normalised at the period n period. The normalised data is
then used to update a period n+1 partial sum dump. The normalised data itself is never written to disk (except,
of course, when the first sum of the period n+1 partial sum is written).
In the event of a normal restart, the initialisation job will ensure that the partial sum data is set up correctly to
continue the accumulation process. In the event of a failure within the means program itself, a flag will be set in
the history file, and any outstanding calculations involving partial sums and/or means will be completed before
the run continues.
The climate means system is invoked once the integration is started if any mean dump frequency is non-zero.
Actual means production is, however, invoked only once the difference between the model date the mean
reference time is an integer number of period 1 mean periods. For example, if a model integration with monthly
means starts from an initial data of the 15th April, then rather than producing a 30-day means that straddles
the period from the 15th April to 14th May, reference is made to the mean reference time. Typically the mean
reference time might be set to be the 1st of December, and the monthly mean calculation will then start from
the 1st of May.
Furthermore, in the above example date of 1st December the seasonal mean calculation will not start until 1st
of June to ensure that the 3 month seasons align with the 1st of December. If meaning is required from the
outset the reference time could be set to a default value of zero. But it is recommended that it be set to the
same date as the start time of the run so that bit comparison can be achieved in continued runs.

3 c Crown Copyright 2015

 UMDP: C05
Control of Means Calculations

3 Programming aspects

Subroutine MEANCTL acts as the interface to the master control routine. It is called shortly before the restart
dump is written. The four main arguments to MEANCTL are:
• IND IM - Integer - Indicator for atmosphere or ocean submodel (climate means only work if it is 1 or 2).
• MEANLEV - Integer - 1-4 to indicate the mean period.
• ICODE - Integer - Return code
• CMESSAGE - Character - Error message (if appropriate).
If MEANCTL completes successfully, ICODE will be passed as zero, otherwise a non-zero value will be returned
with an appropriate message.
MEANCTL calls the subroutines listed below directly. The key routines are ACUMPS which accumulates the
partial sums; MEANPS which normalises the data and MEANDIAG which outputs the mean diagnostics to
climate mean PP files.
• ACUMPS: ACcumulates UM Partial Sums. If dump packing is selected partial sum data will be packed
before writing to disk.
For each field to be meaned:
– Read in field data from a partial sum dump on disk into a work array. If this is the first partial sum of
the period then initialise array to zero.
– Arithmetically add in data stored in main data block.
– Write out updated field data to the alternative partial sum dump on disk.
– Checksums are included in the header of the file to look out for file corruption. Timestep is also
recorded to provide a basic check that the correct partial sum is being used.
NB: To further reduce IO requirements it is possible to change the code to avoid writing out the last partial
sum for the given period since MEANPS takes the data straight from memory.
• MEANPS: MEAN Partial Sums.
– Called with partial sum data still in main data block D1.
– Normalise data appropriately.
– Leave normalised data in D1 for passing to MEANDIAG
• MEANDIAG - extract mean diagnostics and output to climate mean PP file. Appropriate information such
as the mean level is passed in so that the PP file name can be computed. The size of the largest field is
passed in so that an appropriately sized IO buffer can be dynamically allocated.
• SETPERLEN - calculate length of current mean period given MEANLEV and current model date. Only
called if Gregorian calendar climate meaning is being used.
• CHANGE DECOMPOSITION: MPP service routine to ensure that the details of the domain decomposition
are appropriate for the submodel.
• FILE OPEN and FILE CLOSE: Standard file open and close routines.
• SET DUMPFILE LENGTH: Used to preallocate space on disk. Helps to ensure that data is held in a
contiguous area of memory and thus improve access time.
• SET DUMPFILE ADDRESS: Don’t know! Acts on the fixed length header of ocean dumps. Possibly not
required.
• SETPOS: Set IO pointer to start of file. Probably not necessary.

4 c Crown Copyright 2015

 UMDP: C05
Control of Means Calculations

4 Logical Structure

4.1 Normal procedure in MEANCTL

• Determines which period means need to be calculated if any.

• Scan the list of STASH requests for the appropriate submodel to find items tagged for climate meaning.
For each item calculate the memory storage required to hold the field and create a header record for the
header that will be written to the partial sum dumps. Round up memory requirements to the nearest sector
size to ensure well-formed IO. Check that the output frequency is consistent with the meaning period.
• Count the number of items to mean. Calculate the total storage required (which includes the space for the
header as well as space for the data); this value is used to preallocate space on disk. Find the size of the
largest field being meaned. Header size and largest field size are used to dynamically allocate memory in
MEANPS, ACUMPS and MEANDIAG.
The logical sub-process, C51, is then invoked. C51 controls the fundamental process of accumulating instanta-
neous data in a period 1 partial sum dump, and can be thought of as a default process which is executed each
time the subroutine MEANCTL is called.
C51 comprises a single step:
• Call subroutine ACUMPS to create or update period 1 partial sum data on disk with the data stored in the
main data block.
If C5 indicates that mean PP files need to be produced the second logical sub-process, C52 (Means Processing
and Updating of Subsequent Partial Sum Dump), is invoked.
C52 comprises of the following steps: Firstly, the contents of the main data array is copied to a temporary array
and is allowed to be used as workspace. Then the following steps are followed for period 1 means. If also at the
end of higher order means, the steps are repeated for periods 2, 3 and 4 in that order.
• Call subroutine MEANPS to create time-meaned data for the particular period. Save the data in the main
data block.
• Call MEANDIAG to output mean diagnostics to PP files as required.
• Call subroutine PRINCTL to perform zonal mean diagnostics on time-meaned data.
• If period 2 frequency is non-zero, call subroutine ACUMPS to update or create period 2 partial sum dump
using the period 1 time-meaned data (stored in the main data block).
Finally, the saved contents of the main data array are copied back from temporary space and we conclude by
setting a suitable ‘completion code’ in the history file i.e. RUN MEANCTL RESTART=0 if completed without
errors. Return the same code using ICODE.

4.2 Abnormal end in MEANCTL

In the event of a data transfer failure in partial sum accumulation, the file receiving the data will be deleted and
the process of updating will need to start from scratch. Any failure within MEANCTL (whether creating/updating
partial sum dumps or producing mean dumps) will generate appropriate flag settings in the history file, including
an abnormal completion code which will terminate the model run. On restart, C5 will attempt to complete all
outstanding processing for the timestep on which the failure occurred before proceeding. MEANCTL has been
written such that the duplication of work after an abnormal failure is kept to a minimum.
If a run fails part way through and cannot be restarted it is normal to revert to an earlier point in the run by
restarting from one of the archived restart dumps. Since partial sums are not archived, the means that were to
be created from partial sums being gathered at the chosen restart time will not be generated.

4.3 Additional notes about Gregorian calendar climate meaning

The changes (introduced at UM4.4) allow climate meaning as follows:

5 c Crown Copyright 2015

 UMDP: C05
Control of Means Calculations

• Period 1 - Monthly mean over real months taking account of the number of days in the month (which is
usually 28, 30 or 31) and whether in the case of February the year is a leap year.
• Period 2 - Seasonal means. The mean will be calculated weighting the months according to the number
of days in each month. Number of days in any 3-month period can be 89, 90, 91 or 92.
• Period 3 - Annual means. Calculated according to whether the February included has 28 or 29 days.
• Period 4 - it was not intended to provide period 4 means with this option, because the effort of calculating
the possible number of days in any 10 year period is considerable (but not completely prohibitive, should
anyone wish to alter the UM code to provide multi-year means with the Gregorian calendar in the future).
With the 360-day calendar, seasonal means are conventionally (but by no means always) calculated using the
formula (e.g. for SON) (M(sep)+M(oct)+M(nov))/3 where M=monthly mean, but with Gregorian calendar climate
meaning (the 360-day calendar system being unchanged) the following is used:
(30*M(sep)+(31*M(oct))+(30*M(nov)))/(30+31+30)
and with the 360-day calendar, annual means are conventionally calculated using (S1+S2+S3+S4)/4 where
S=seasonal mean, but with the Gregorian system annual means are calculated using (e.g. for a leap year
where the model year commenced on 1st December)
((91*S(djf))+(92*S(mam))+(92*S(jja))+(91*S(son)))/366
The meaning is actually done in MEANPS, where values in an array of field data are multiplied by RFACTOR
(derived from a variable which is passed in from MEANCTL), where typically RFACTOR=1/30, 1/3, 1/4 or 1/10
in turn for a normal climate run, so the call to MEANPS from MEANCTL is altered so that for Gregorian means
RFACTOR=1/28, 1/29, 1/30 or 1/31 for period 1, depending on the length of the month that has just been
completed, and if the restart dump period is less than 24 hours then RFACTOR is further divided by the number
of restart dumps in period 1 (because in MEANPS the meaning period is defined in terms of multiples of the
restart frequency). For periods 2 and 3, only the number of days is used.
To weight the period 2 and 3 means by the length of the period, in subroutine ACUMPS the data going into
the partial sum is multiplied by a factor of the length of the period in days. Without Gregorian calendar climate
meaning, no multiplication takes place. A new subroutine SETPERLEN is included to provide the length of a
period given the current model time and the type of mean being produced.
The change also provides the option of reinitialising PP files on real month boundaries. It is still allowable to
create 30-day ”monthly” means with the Gregorian calendar, as it was previously, although obviously the means
would quickly go out of step with the real months.
If a run fails in a messy way, and needs to be continued, there are more restrictions on restartability with
Gregorian means than the conventional system, and the run is more likely to need to be continued as an NRUN,
rather than a CRUN, than with the 360day calendar meaning system. Regardless of whether continuing as
an NRUN or CRUN, remember that the mean reference time must be set to the 1st of a month. It may aid
restartability to restart the run itself (the basis time) from the 1st of a month.

6 c Crown Copyright 2015