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.

1. The following method should not be used for the coupled model with slow and fast coupling timesteps. Use method 2 below.

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

2. Component specific mediator history files

Component specific mediator history files (ESCOMP/CMEPS#228) are the preferred method for coupled configurations with slow/fast loops. 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.

In ESCOMP/CMEPS#436, the capability was added to write the mediator history files on the 6-tiled ATM grid for global configurations and on the single tile for regional configurations (eg, HAFS). OCN and ICE will be on the native tripole resolution. If the WAV component is using an unstructured grid then it will be written on the mesh, and additional steps are required to visualize the fields.

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.