• View
• Edit
• History
• Print

New Ancillary Files

Notes on how to add new ancillary fields to the UM.

Acknowledgement:- Much of this is based on modsets abx2f404 & abx1f404 written by Richard Betts and reviewed by Dave Robinson. [Generated by Richard Barnes for vn4.4, minor additions only by Rick Rawlins 27 Apr 98 and 23 June 98.]

Introduction.

Extensions or additions to the physical parametrisations used in the UM often require new ancillary fields to be made available within the model. Although this is technically relatively straightforward, it requires quite a large number of simple changes, so this document takes the form of a checklist of things that need to be considered. Areas likely to require code changes are listed by deckname.

It is important to be clear about the difference between ancillary files and fields. A file is likely to contain ancillary data for several fields. Each field will need a separate pointer to its place in the D1 array of prognostic variables.

Note that the following checklist only deals with how to get ancillary data and addressing information into the UM. Creating ancillary files containing suitable data, adding code to use the ancillary fields within the model, and adding suitable questions to the user interface also need to be considered and are not dealt with here.

Decknames checklist

CENVIRDT - this lists the environment variable names associated with every UM file. If new ancillary FILES are required they need to be assigned a new environment variable name corresponding to particular unit numbers, and the length of the name defined. Currently all unit numbers up to and including 138, CACHED, of length 6, are in use.

CLFHIST - similarly to CENVIRDT, declare a new environment variable name for each new ancillary file, put it in the namelist, and equivalence it to the element of MODEL_FT_UNIT corresponding to its unit number.

CONANC - increment the values of NANCIL_DATASETSA/O by the number of new atmosphere/ocean ancillary files.

CANCFTNA - enter the unit number of any new atmosphere ancillary file; there is a similar comdeck CANCFTNO for ocean ancillary files.

CANCTITA - add a suitable title for each new ancillary file (atmos only).

RECONF1 - add a call to FILE_OPEN for each new ancillary file.

CANCMAXA - increase hard-wired parameter values NANCIL_FIELDS to include any new atmosphere ancillary fields; there is a NO similar comdeck CANCMAXO for ocean ancillary fields?

CANCFLDA - add STAS Hcodes?, submodel codes and ancillary file numbers for any new atmosphere ancillary fields; there is a similar comdeck CANCFLDO for ocean ancillary fields.

CANCLSTA - add information on new ancillary fields to the comments list.

INANCA1A - add any levels information for the new ancillary fields.

CNTLATM - any associated logical control variables need to be declared and put into namelist and common block.

TSTMSK1 - any new or changed option codes to control new ancillary fields need to be coded here.

STATMPT1 - initialise pointers for new ancillaries using appropriate STAS Hindex? (SI array) values.

RPANCA1A - extend “IF (FIELD…” code to ensure new ancillaries are updated correctly for full fields or land points only.

INITDUM1 - any new data on multi-level land fields will need repositioned like other similar fields.

DUMPCTL1 - repositioning of data, to reverse that done in INITDUM1, is needed for any new multi-level land fields.

TYPPTRA - add J-pointers for new ancillary fields; this applies for both single and multi-level fields. For multi-level fields also need to alter:-

ARGPTRA - add array for each multi-level pointer.

ARTPTRA - add an element to pointers super-array for each multi-level pointer.

SPINDEX - increase size of A_IXPTR_LEN if new multi-level pointers.

UMINDEX1 - extend list of pointers super-array addresses A_IXPTR for each new multi-level pointer, and update super-array length A_SPPTR_LEN.

---

CHSUNITS - Increase max. no. of I/O units if this is exceeded by introduction of new units for ancillary files (note that this has sometimes been declared larger than needed in order to provide some spare capacity). If so, this needs a corresponding change to comdeck:
VERSION for STASH.

UMUI

Inform UMUI owner (Mick Carter) that a new envar needs to be added to namelist &NLCFILES in UMUI control file INITHIS. This identifies the chosen ancillary file with the envvar and will need a change to a UMUI window to allow the filename to be entered by a user. Accompanying help information and context of the ancillary file will also be required.

The STAS Hmaster? file will need to be updated for the next version to describe attributes of the variable within the model, ie STAS Hcode?, etc.

Testing at current version

Note that, in order to test changes in INITHIS, etc, within a reconfiguration/model run, this will require a rebuild of the qxsetup small executable. Also,

New ancillary fields will require a user STAS Hmaster? to be attached to the umui job to allow these fields to be placed in the dump. See also TSTMSK1 above.

There is also an explicit export of the envvar for file i/o in script qsprelim, but it is not clear why this is needed, except possibly for portable model users. qsmain deals with the same issue implicitly, and no specific reference is needed. At 4.5 a change is planned to make qsprelim consistent with qsmain so that no explicit updates of qsprelim are needed. There are also comments in both scripts but these are incomplete.

---

 Rick Rawlins / frawlins@meto.gov.uk / x6482 / Room 416