Adding New Fields to STASH

Template:Needs Update This page needs updating

Adding a new output field to STASH

It is possible to add new fields to STASH by modifying the UM source code. There are two output types that you can use - prognostic and diagnostic. Prognostic variables are passed around internally by the UM, so that you can use the field internally in different sections, while diagnostic outputs are only generated when requested.

Outputting data

To create a new diagnostic output you have to call the function COPYDIAG (or in the case of 3d fields COPYDIAG_3D), passing in your field and some STASH variables. An example function to output a field in section 8 with item id 500 is presented below:

SUBROUTINE test_field(row_length,rows,&
                      stashwork,si,sf,at_extremety,&
                      nitems,nsects)
implicit none

! Provides:
!   internal_model_index
!   atmos_im
#include "csubmodl.h"

! Field size
integer,intent(in)   :: row_length
integer,intent(in)   :: rows

! Output for STASH
real,dimension(*),intent(inout) :: stashwork

! Stash utility arrays & sizes
integer,intent(in)   :: nitems
integer,intent(in)   :: nsects
logical,intent(in),&
        dimension(0:nitems,0:nsects) :: sf
integer,intent(in),&
        dimension(nitems,0:nsects,n_internal_model) :: si
logical,intent(in),&
        dimension(4) :: at_extremety

! Error codes
integer :: icode
character(len=1024) :: cmessage

! STASH code for this field
integer,parameter    :: item = 500
integer,parameter    :: section = 8
integer,parameter    :: model = atmos_im
integer              :: model_index

real,dimension(row_length,rows) :: field

model_index = internal_model_index(model)

! Initialise the field
field = 0

! Check if enabled in the interface
if (sf(item,section)) then
        ! Set the field values
        field = 1

        ! Copy to STASH
        call copydiag(stashwork(si(item,section,model_index)),field,&
                        row_length,rows,&
                        0,0,0,0,at_extremety,&
                        model,section,item,&
                        icode,cmessage)
end if

END SUBROUTINE test_field

The arguments row_length, rows, si, sf, at_extremity, nitems and nsects are passed into most functions through header files, so you can just put in their names when you call the function. The stashwork array on the other hand needs to be traced from ATM_STEP, where arrays for each section are created. You'll need to add your data into the stashwork array before the call to STASH on that array or else the field won't actually be output.

Section numbers can be anything from 0-99, with values of 0, 33 and 34 are reserved for prognostic variables. The item numbers can be any number 1-512 inclusive.

Calling the output function

Each section has its own stashwork array in ATM_STEP, eg. section 8 uses the array STASHwork8. To call the above function you should can add the below just after the call to ATMOS_PHYSICS2 in ATM_STEP:

! DEPENDS ON: test_field
        CALL test_field(row_length,rows,STASHwork8,si,sf,at_extremity, &
                        nitems,nsects)

User STASHmaster files

You'll also have to tell the UMUI that there's a new output field, which you can do using a user STASHmaster file. The format of the file is described in detail in the | STASH documentation, for the single level field used in this example the user STASHmaster file is shown below.

H1| SUBMODEL_NUMBER=1
H2| SUBMODEL_NAME=ATMOS
H3| UM_VERSION=7.3
#
#|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 |    8 |  500 |TEST FIELD                          |
2|    0 |    0 |    1 |    1 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 11111111111111111111 |    3 |
4|    1 |    2 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |    0 |    0 |    0 |    0 |    0 |    0 | 9999 |  000 |
#
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  -30  -99  -99  -99  -99  -99 |
5|    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |

Setting up the run

To run a job which outputs your field add the source to FCM Configuration->FCM Options for Atmosphere and the user STASHmaster file to Atmosphere->STASH->User-STASHmaster files. Once you've done this you can add the new diagnostic in Atmosphere->STASH->STASH Specification of Diagnostic requirements. A run that uses the example given in this document is located in the job uaevb.

Resources

| STASH documentation | UM Branch with example output