.. _history: ============== 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. 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 :ref:`running-a-case`). 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_inst`` and ``..._comp_avg`` do 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. 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 ``.cpl[.].h*..nc``. 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: ``.cpl.hx.lnd2glc.