CMEPS history files

[DeniseWorthen]

CMEPS allows the writing of mediator history files during the run sequence. These files can be used to examine coupling fields visually and determine whether changes made to component code has the expected impact (if any) on coupling fields. Examining differences in mediator history files is also a primary method for investigating a failure in restart reproducibility for the coupled model . See related Discussion 797.

Mediator history files can be produced in one of two ways. A special med_phases_history_write can be added at any point in the run sequence. This will create a file containing the instantaneous values of all import and export fields between all components at that point in the run sequence. Two configuration parameters must be available in MED_attributes to control the frequency of the files, for example:

      history_n = 1
      history_option = nsteps

This setting will write files each time through the run sequence. Other options would be, for example, history_n=1 and history_option=nhours, which would produce the file on one hour increments through the run sequence.

Note this method of creating mediator history files is subject to inconsistent frequency, as explained in Issue #259

In UWM PR #831, CMEPS was updated to include a second method of creating mediator history files (via ESCOMP/CMEPS#228). No additional run phase is required in the run sequence. Instead, history files can be written for a given component according to a set of configuration variables in the MED_attributes. These files can be written as either instantaneous fields or average fields. For example,

history_n_xxx_avg=6
history_option_xxx_avg=nhours

where xxx = (atm,ocn,ice), will produce averaged mediator history files every 6 hours and

history_n_xxx_inst=6
history_option_xxx_inst=nhours

will produce instantaneous mediator history files for component xxx every 6 hours. The files produced in the two cases will be of the form

ufs.cpld.cpl.ha.xxx.TIMESTAMP.nc
ufs.cpld.cpl.hi.xxx.TIMESTAMP.nc

The available values for history_option are: none, never, nsteps, nseconds, nminutes,nhours, ndays, nmonths, nyears, monthly, yearly.

Currently, ATM fields in mediator history files are on the mesh whereas OCN and ICE are on the native tripole grids. With the merge of UWM PR #932, an additional option will allow the ATM files to be written on the 6 tiles. All tiles are in a single file. Writing the ATM files on the tiles is controlled by the configuration variable

history_tile_atm = tilesize (eg. 96, 192, 384)

If this attribute is not present, then ATM fields will be written on the mesh by default.

When examining mediator history files, all fields are marked as Imp (import) or Exp (export) from the perspective of the mediator. For example, the field atmExp_Si_ifrac is the ice fraction from the ICE model which will be exported to the ATM by CMEPS. In an ICE history file, the corresponding field would be iceImp_Si_ifrac (ice fraction imported from the ICE). The field atmImp_Sa_tbot is the bottom-most temperature imported from the ATM for export to the ICE. The corresponding field in an ICE history file would be iceExp_Sa_tbot.

Fields in the history files with names starting with S are state fields (ie, temperature, velocity). Fluxes are indicated by names starting with F (e.g, Faxa_sen, the flux of sensible heat). The yaml field dictionary (fd_nems.yaml) can be examined for more descriptive aliases for individual fields.