3.11. History output
med_phases_history_mod.F90 writes the mediator’s history files — snapshots of
the coupled fields, on their grids, at a requested frequency. It is the coupler’s
own diagnostic output, separate from each component’s history.
3.11.1. Instantaneous and time-averaged streams
History output comes in two kinds, maintained as separate streams:
instantaneous — the field values at the output time; and
time-averaged — the fields averaged over the output interval (the mediator accumulates them between writes and divides at write time).
Each stream has its own output frequency, set by a freq_option / freq_n
pair (for example “every nmonths”, “every nsteps”). These come from the
history_option_* / history_n_* settings (see Configuring and running a case (CESM/NorESM)).
3.11.2. The write phases
The run sequence calls the appropriate write phase:
med_phases_history_write— instantaneous output of all variables;med_phases_history_write_comp— instantaneous, averaged and auxiliary output for a component (..._comp_instand..._comp_avgdo the actual writes);med_phases_history_write_med— the mediator-computed fields (the atmosphere/ocean fluxes and ocean albedos);med_phases_history_write_data2glc— the (normally yearly) average of the fields sent to the land-ice component.
med_phases_history_init sets up the streams and their alarms.
3.11.3. File names
The mediator history files are named after the case with a coupler (.cpl)
tag and the output timestamp, ending in .nc — for example
<case>.cpl[.<inst_tag>].h*.<yyyy-mm-dd-sssss>.nc.
3.11.4. Auxiliary history (histaux) files
A histaux stream records, at the frequency they are exchanged, the fields
that a source component sends into the mediator. For example,
histaux_atm2med_* saves the atmosphere-to-mediator fields each coupling
period.
Because these files capture the exact forcing a component provided, they can be replayed later: a CDEPS data model reads them back as an input stream and uses them to drive a target component, without rerunning the original source component. This is a cheap way to spin up a slow component.
A common example is the CESM/CTSM land biogeochemistry, which needs many years of
atmospheric forcing to equilibrate. Rather than rerunning CAM each time, one run
with an active CAM saves the atmosphere-to-mediator fields as histaux files.
CDEPS/DATM (a data atmosphere) then repeatedly cycles over those saved years — for
instance a 20-year block — reading the histaux files as its forcing to drive
CTSM on its own.
Auxiliary history files carry an .hx. tag in their name. For example, the
land-ice files written by med_phases_history_write_data2glc name the source
of the mapping: <case>.cpl.hx.lnd2glc.<time>.nc and
<case>.cpl.hx.ocn2glc.<time>.nc.
3.11.4.1. Per-slot settings
Each histaux stream is defined by one or more numbered file slots
(histaux_<stream>_file<N>_*). Each slot has these settings:
enabled— whether the slot is written.flds— the:-separated list of fields to write (orall).history_option/history_n— the output frequency.doavg— instantaneous (.false.) or time-averaged (.true.).auxname— a tag placed in the auxiliary file name.ntperfile— the number of time samples per file.
3.11.4.2. Default histaux streams
These settings are available as NUOPC attributes, obtained during
initialization in med_phases_history_mod.F90. The default file slots are
summarized below; all can be overridden in user_nl_cpl.
Import type |
|
Frequency |
Type |
Samples / file |
Default fields written out for NorESM/CESM |
|---|---|---|---|---|---|
|
|
1 h |
inst |
24 |
|
|
|
1 h |
avg |
24 |
|
|
|
3 h |
avg |
8 |
|
|
|
3 h |
avg |
8 |
|
|
|
1 day |
avg |
1 |
|
|
|
coupling step |
inst |
1 |
|
|
|
1 day |
avg |
365 |
|
|
|
1 day |
avg |
30 |
|
|
|
3 h |
avg |
2 |
|
|
|
1 day |
inst |
30 |
(none set) |
The histaux_* streams are configured through user_nl_cpl (see
Configuring and running a case (CESM/NorESM)).