UKCA & UMUI Tutorial 9

Adding New Diagnostics

If you are using one of the chemistry schemes that uses ASAD (e.g. CheT/TropIsop, CheS/Strat, CheST/StratTrop) then you can make use of the ASAD Reaction Flux Diagnostics module (held in asad_chem_flux_diags.F90). These allow you to straight-forwardly out new reaction and deposition fluxes.

To output new diagnostics you will first need to define them in the asad_flux_dat.F90 module, and then create a new STASHmaster file for them.

Flux Definitions in asad_flux_dat.F90

Within the asad_flux_dat.F90 module the diagnostics are defined in blocks with the format

      asad_flux_defn('Diagnostic type',STASH code,'Diagnostic specification',Mask,Reaction number,Number of species, &
      (/'Species/Reactant 1','Reactant 2'/),                                                                         &
      (/'Product 1','Product 2','Product 3','Product 4'/)),                                                          &

Which have the following meaning:

Diagnostic Type

This is a three character string which defines what type of diagnostic is being requested. This can take the values

RXN to output the flux through a reaction (in moles/gridcell/s)
DEP to output the deposition flux of a species (in moles/gridcell/s)
EMS to output the emission flux into a species (in moles/gridcell/s)
NET to output the net chemical tendency of a species (in moles/gridcell/s)
STE to output the net dynamical tendency of a species (in moles/gridcell/s)
MAS to output the mass of the atmosphere (in kg/gridcell)
PSC to output polar stratospheric cloud diagnostics (1 when the gridcell contains a PSC, 0 otherwise - monthly mean field will be a fraction in range 0 → 1)
TPM to output the tropospheric mask (1 for troposphere, 0 otherwise - monthly mean field will be a fraction in range 0 → 1)
OUT to output a tracer in mmr. Only really useful if the field is masked to give the tropospheric concentration only (see the discussion of the Mask option)
RTE to output the rate of a reaction (in gridcell/s)

STASH Code

This is a 5 digit integer defining the STASH code that the diagnostic will be outputted to. Currently this must be in section 34.

Diagnostic Specification

This is a one character string which is needed to further define what diagnostic is required. If it isn't needed then it should just be set to X or left blank.

RXN
- B to output the flux through a bimolecular reaction
- T to output the flux through a termolecular reaction
- H to output the flux through a heterogeneous reaction
- J to output the flux through a photolysis reaction
DEP
- D to output the dry deposition flux
- W to output the wet deposition flux
EMS
- S to output a surface emission (2D)
- A to output aircraft emissions (3D)
- L to output lightning emissions (3D)
- V to output volcanic SO2 emissions (3D)
- T to output SO2 emissions (3D)
PSC
- 1 to output the fraction of Type 1 PSCs
- 2 to output the fraction of Type 2 PSCs
RTE
- B to output the rate of a bimolecular reaction
- T to output the rate of a termolecular reaction
- H to output the rate of a heterogeneous reaction
- J to output the rate of a photolysis reaction

Mask

This is a logical which defines whether only the tropospheric values of the diagnostic are outputted (.TRUE.) or not (.FALSE.). It is calculated every timestep.

For the STE diagnostic this is required if you wish to output the diagnosed stratosphere-troposphere exchange of a species. For the OUT diagnostic this can be used to output only the tropospheric concentration of a tracer. This is also used in the calculation of the of the TPM diagnostic.

Reaction number

This is an integer, and should only be used in the special case of there being two (or more) reactions with the exactly the same reactants and products, but with different rate coefficients. In this case the first reaction in the list would be given number 1 and the second 2 etc. If this is not needed then it should be set to 0 (which will be usual for most reactions).

Number of Species

This is an integer, and should give the total number of species, so this will be 1 for diagnostics such as DEP, STE, NET etc., which only consider a single species, and the total number of reactants and products for diagnostics RXN and RTE.

Species

This is a 10-character string giving the exact name of the species that the diagnostic should be considered for (including capitalisation). This is only used for the DEP, EMS, NET, STE, and OUT. For the RXN and RTE diagnostics the full list of reactants and products should be given (see below). For the MAS, PSC, and TPM diagnostics this isn't needed and could either be set to XXX or left blank. If it is needed the other reactant/product slots should be left blank.

Reactants and Products

These are 10-character strings, and should be as the reaction is defined in the ukca_chem_scheme.F90 modules.

Addition of Diagnostics

If you define more than one diagnostic to be output to the same STASH code, then the diagnostic routines will sum these diagnostics together. This can be useful (e.g., if you wanted to output the sum of all NO+RO2 reactions to one STASH item), but can be problematic if you accidentally output two fields to the same STASH code, as this will give strange results!

STASHmaster file

While the diagnostics are defined in asad_flux_dat.F90 they are turned on by requesting the item through STASH. To do this you will need to make a new STASHmaster file for diagnostics that you have defined yourself. The easiest option is to copy an existing diagnostic specification from the STASHmaster_A file, which is located at

/work/n02/n02/hum/vn8.2/ctldata/STASHmaster/STASHmaster_A

on HECToR, and at

/projects/um1/vn8.2/ctldata/STASHmaster/STASHmaster_A

on MONSooN.

2D Diagnostic Fields

If you are outputting a 2D field such as a surface emission or a dry deposition field if you are using the old 2D dry deposition scheme then the fact that this is a 2D surface field is defined in the STASHmaster entry, which looks like this e.g.

#
1|    1 |   34 |  321 |Ox BUDGET: O3 DRY DEPOSITION (2D)   |
2|    0 |    0 |    1 |    1 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 1871 |    1 |  129 |    0 |    0 |    0 |    0 |    0 |
#

However, you can always output a surface diagnostic using 3D STASHmaster file, it is just that only the surface values will be non-zero.

You will need to edit the two elements in red to match your new diagnostic.

3D Diagnostic Fields

A 3D diagnostic field has slightly different values for some of the elements of the STASHmaster definition. These can been seen by comparing the specification above with the one below

#
1|    1 |   34 |  321 |Ox BUDGET: O3 DRY DEPOSITION (3D)   |
2|    0 |    0 |    1 |    1 |    2 |   10 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 1871 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

You will need to edit the two elements in red to match your new diagnostic.

STASHmaster file format

As well as defining the the STASH items in your new user STASHmaster file, you will also need to include the correct preamble and an end of file specifier. These are

Preamble:

H1| SUBMODEL_NUMBER=1
H2| SUBMODEL_NAME=ATMOS
H3| UM_VERSION=8.2
#
#|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| PPF  | USER | LBVC | BLEV | TLEV |RBLEVV| CFLL | CFFF |
#

which is also helpful is describing what the elements in the STASH specification are.

End of file specifier:

#
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 |
#

Time Validity

When outputting UKCA reaction and deposition fluxes, you need to consider what time-points these diagnostics are valid at. Tracer fields are valid at all timesteps, but for reaction fluxes this is not the case. All the chemistry schemes which use ASAD/Newton-Raphson (CheT/TropIsop, CheS/Strat, and CheST/StratTrop), the UKCA chemical timestep is every hour.

This means that when you output this diagnostic through STASH you need to change the sampling frequency. To do this, go to the STASH panel in the UMUI (Model Selection → Atmosphere → STASH → STASH. Specification of Diagnostic requirements) and copy the time profile you would like to use for the diagnostic to a new profile (giving it a similar, but slightly different name) and then change the sampling frequency to be

Frequency (every) to be 3
Offset to be 2

This will then sample the diagnostic on the UKCA timesteps. If you don't sample the diagnostic using this sampling frequency, then the output may be incorrect.

The following diagnostics are valid on all timesteps:

MAS
OUT
TPM
STE
EMS

The following diagnostics are only valid on chemical timesteps:

RXN
DEP
RTE
PSC

Written by Luke Abraham 2013