• View
• Edit
• History
• Print

New Diagnostic

Adding a new diagnostic to the atmosphere model

15 Jun 01

Based on adding new diagnostics to vn5.1

UM Doc paper C4: STASH: (pdf) gives more details of the diagnostic system.

Changes required:

• Choose the STASH section.
  Obvious if the diagnostic is associated with a physics section, such as boundary layer =3. Diagnostics derived from primary field quantities have their own sections:
  • 15: ‘dynamics’ related; ie fields calculated predominantly from winds.
  • 16: ‘physics’ related; ie fields calculated predominantly from temperature, moisture.
  • 30: energy budget cross-product fields. In particular, these sections are used to derive diagnostics on pressure levels. [Note that STASH deals with horizontal fields and is only capable of very simple vertical averaging. If vertical interpolation is required, then this is done outside STASH, and a new diagnostic needs to be defined.]
• Choose a new STASH item number.
  If the diagnostic is new, any untaken number between 1–512 can be selected. [Early UM versions had restrictions here, with 1–200 reserved for copies of primary variables, which is why most diagnostics have numbers 201 upwards.] There is no connection between STASH diagnostics in different sections but with the same item number. However, there is currently (June 01) a restriction with Metview that only allows a single superset definition of STAS Hcodes? covering more than 1 version, in particular including UM4.5. Hence, for post-processing purposes, it is preferable to use an item number which is new in both UM4.5 and UM5.2 STAS Hmaster? files.
• Create a workstation file containing a user-STAS Hmaster? record of the new diagnostic.
  This is best copied from the record for a similar diagnostic held in the STAS Hmaster?_A file [held on the t3e at $UMDIR/vn5.2/ctldata/STAS Hmaster?_A with a copy also available via the UM doc. pages at http://www-hc/~umui/link_to_dev/vn5.2/variables/STASHmaster_A]. Changing item and title may be all that is required for a similar diagnostic in the same STASH section. If it is expected that the diagnostic will be consolidated into the next build of the UM, contact the UM librarian to reserve the item number.
• Source code modset.
  Most diagnostics are generated through diagnostic_ routines that follow physics calculations for a section, ie routines diagnostics_bl, diagnostics_conv. If a new_field is required for output it should be either calculable within diagnostics_, or be calculated earlier and passed into diagnostics_. Then code is required to copy it into the relevant position of the transient array STAS Hwork?. See paragraph 5.1 of UM Doc paper C4 for pseudo-code. Protect new calculations and copies with STAS Hflags? so that processing is only performed when diagnostics are requested.

Testing:

• Set up a standard job without changes for the null case. Confirm normal completion and note the ‘Final Error Norm : 14066343401.694809′ number after say 1 day’s integration - this is effectively unique to that integration and any changes in model evolution will alter this result.
• Include your user-STAS Hmaster? file in the UMUI job, which will make the new diagnostic available through the UMUI.
• Select the new diagnostic. If careful inspection of actual values is performed, this is best achieved as at a specified time (snapshot). However most testing would benefit from also selecting the diagnostic as a daily time mean - which ensures arithmetic processing of every value and exposes Na Ns?.
• Check that the introduction of new code, with and without the new diagnostic selected, has no effect on model evolution.
• Re-run the case with new diagnostic selected with a different configuration of pes (eg 1×16 v 4×4 at climate resolution). Compare - using $UMDIR/vn5.1/normal/utils/cumf - fieldsfiles created at the 2 configurations, and these should be identical. This sometimes exposes errors in treatment of polar rows.
• Browse - using $UMDIR/vn5.1/normal/utils/pumf - the fieldsfile, just to check order of magnitude of new field values are sensible.
• Optionally, for a more careful check, display the field graphically through PV-wave or similar, to test that horizontal patterns are as expected.

After testing

• Review and lodge the source code change
• Email the user-STAS Hmaster? file to the UMUI team to be included in the STAS Hmaster? file for the next version.
• Supply a text help message with additional information on the particular diagnostic to the UMUI team, which will then be available for access via the UMUI STASH panel as help (or via on-line access http://www-hc/~support/stash_help/SD_version.html).

Pitfalls

• Not using STAS Hflags? correctly: tests with diagnostics complete normally but fails when diagnostics not requested.
• Diagnostic not made available to STASH by STAS Hmaster?. The ‘Version Mask’ field in the record activates diagnostics dependent upon the section-version, ie for boundary layer scheme 3_6A, this is 6, and 0100000 activates. Hence, if a new entry for the bl is copied from another section, say 8_3B with 0000100, the diagnostic is not activated.
• There needs to be a STASH call for the section, with array STAS Hwork? as input, following code for the new diagnostic. This is already in place for existing diagnostic_ routines. However, for new code outside a section, or a new section, this may not be the case: then the code would complete normally, and would appear to have correct STASH requests and addresses, but the diagnostic would be missing from the output fieldsfile.
• If WGDOS packing is switched on for the output stream, values will be packed according to the precision given in the STAS Hmaster? entry. If too low a precision is given, eg PC=−2 (ie 2**−2 = .025) for a humidity field with max values .01, then the field will contain only zeros. This will not appear as a problem if all the testing has been performed with an unpacked output stream. [Specifying too high a pecision is also a problem, but this will cause a failure in the WGDOS packing routines (COEX) - since too many bits are required to store the packed field.]

 Rick Rawlins