1.2. Core concepts

This page defines the vocabulary that the User and Developer guides assume. Read it once; later pages link back to these terms.

1.2.1. Components and caps

A component is a model of one part of the Earth system — atmosphere (atm), ocean (ocn), sea ice (ice), land (lnd), river runoff (rof), waves (wav) or land-ice (glc). Each component is presented to the mediator by a NUOPC cap, a small software layer that translates between the component’s native data and the ESMF states the mediator understands.

Although CMEPS can be considered to be an ESMF component shared among host models - it does not have a NUOPC cap. All data structures in CMEPS are ESMF/NUOPC compliant.

1.2.2. The driver

The driver is the top-level NUOPC application component that harnesses the mediator and all of the component models. It creates them and the connectors between them, and it runs the coupled time loop — invoking each component’s run phase, each mediator phase, and each field transfer in the order given by the run sequence.

Whenever this documentation refers to “the driver,” it means this host-specific harness that assembles and steps a particular application — not the mediator. The distinction between the shared mediator and the host-specific driver is spelled out under The run sequence below.

1.2.2.1. The run sequence

The run sequence is the ordered recipe that drives a coupled run. It lists, in order, which component runs, which mediator phase executes, and which fields are transferred between components — together with the coupling intervals at which each of these happens. The driver (described above) ingests the run sequence at start-up and uses it to step the coupled system through time.

The run sequence — not the mediator — determines the order of operations and the coupling frequencies; changing which components are coupled, and how often, is done by changing the run sequence.

Important

Several things around the run sequence are host-specific, and confusing them with the mediator is a common source of error.

The driver — host-specific:

  • The driver that ingests the run sequence is host-specific. The driver under cesm/ in this repository is used only by CESM and NorESM; UFS uses its own driver.

  • How the run sequence is generated is host-specific. For CESM/NorESM it is produced by the CIME case-control system from the coupling intervals you configure (the generator lives in cime_config/runseq/ and is CIME-only); UFS assembles its run sequence by other means.

  • The run configuration the driver ingests is host-specific: nuopc.runconfig for CESM/NorESM, ufs.configure for UFS.

The mediator (CMEPS) — shared across applications:

  • The mediator is shared across applications such as NorESM and UFS; the same mediator code serves them all.

  • The mediator does not parse the run sequence; it simply registers the MED phases that the run sequence names.

  • The mediator obtains only the attributes the driver sets from the run configuration, not the host-specific configuration file itself.

  • The mediator is designed to be host-agnostic to the greatest extent possible — a small number of host-specific #ifdef blocks remain that could not be avoided, but the goal is to keep the mediator common across applications.

The run sequence itself is written in a common NUOPC format that is the same whichever application’s driver ingests it. For how it is generated and stored on CESM/NorESM, see the User Guide.

1.2.2.2. The run configuration

The run configuration is the second key input the driver ingests at start-up (the run sequence being the first). Whereas the run sequence says what runs, in what order, and how often, the run configuration supplies the attributes that the driver and each component, including the mediator, can query at run time in order to configure their target behavior. For the driver this includes what the list such attributes as the list of active components and the processor layout.

The relationship to the mediator mirrors that of the run sequence:

  • The mediator does not read the run-configuration file directly. The driver ingests the file and sets attributes on the components; the mediator then queries the attributes it needs (for example the coupling mode, the grid on which atmosphere/ocean fluxes are computed, or whether budget diagnostics are enabled, etc.).

  • The run-configuration file is host-specific: nuopc.runconfig for CESM/NorESM, ufs.configure for UFS. Because the mediator depends only on the attributes, not on the file that supplied them, the same mediator code works for every host.

For the CESM/NorESM run configuration and the specific attributes the mediator reads, see the User Guide.

1.2.3. The mediator

The mediator supplies the coupling machinery. The remaining concepts below — how components exchange fields with it, what it does with those fields, and how it keeps the coupling conservative — describe that machinery.

1.2.3.1. Import and export states

Components and the mediator communicate through two ESMF states:

  • an import state, holding fields flowing into the owner, and

  • an export state, holding fields flowing out of the owner.

A state wraps native model data as ESMF fields and carries metadata: the standard field names, the grid or mesh and its coordinates, and the parallel decomposition.

Important

States are named from the owner’s point of view, so the mediator sees them reversed relative to a component. A field a component sends out lives in that component’s export state — but the mediator receives it, so from the mediator’s point of view it arrives in the mediator’s import state. Likewise, a field the mediator sends to a component lives in the mediator’s export state, and the component receives it into its import state.

In short:

  • component export state → mediator import state

  • mediator export state → component import state

Whenever “import” or “export” appears in this documentation, check whose state is meant: the direction is opposite for the mediator and the component exchanging the field.

1.2.3.2. Fields and the field dictionary

Connections between components are made by matching standard field names rather than by position or order. The full set of names, together with their long names, units and metadata, is the field dictionary. CMEPS ships a field dictionary per host application. Adding a new coupled field therefore starts with the dictionary; this is covered in the Developer Guide.

1.2.3.3. Three mediator operations

Nearly everything the mediator does is built from three operations:

Mapping (interpolation)

Moving a field from a source grid to a destination grid using precomputed ESMF routehandles (sparse-matrix weights). Weights can be conservative, bilinear, nearest-neighbor and so on. Mapping is the subject of the Developer Guide’s mapping page.

Merging

Combining several mapped source fields into one destination field — for example forming the field the atmosphere sees over a grid cell that is part land, part ocean and part sea ice. Merges are weighted by surface fractions.

Time averaging and accumulation

Reconciling components coupled at different frequencies by accumulating a field over the fast-coupling periods and averaging it before it is passed to a component running on a slower coupling period.

Beyond these three operations, the mediator also computes certain fields itself rather than merely transferring them between components. These are not simple map/merge/average steps; each is described in its own section below (atmosphere/ocean fluxes, ocean albedos, land-to-land-ice downscaling, and surface fractions) and developed further in the Developer Guide.

1.2.3.4. Atmosphere/ocean fluxes

The turbulent fluxes at the air-sea interface — wind stress, and the sensible heat, latent heat and evaporation (moisture) fluxes — are among the most important quantities in a coupled simulation, and computing them is a central responsibility of the mediator. Unlike most coupled fields, which are produced by a component and simply transferred, the atmosphere/ocean fluxes belong to neither the atmosphere nor the ocean: they describe the interaction between the two. In many configurations they are therefore computed inside the mediator, from the ocean state (for example sea-surface temperature and ocean currents) and the mapped atmosphere state (for example near-surface winds, temperature and humidity), using a bulk flux algorithm.

The calculation produces the turbulent air-sea fluxes:

  • zonal surface wind stress

  • meridional surface wind stress

  • sensible heat flux

  • latent heat flux

  • evaporation (surface water flux)

  • upward longwave radiation

Alongside these fluxes it also produces near-surface diagnostic states used by other components — for example the 2 m reference temperature and humidity, the 10 m wind speed, and the friction velocity.

Computing the fluxes in one place, from a consistent set of states, keeps the atmosphere and ocean seeing the same interface and makes conservation tractable: the resulting fluxes are fraction-weighted, mapped conservatively between grids, and merged with the ice/ocean fluxes so that each component receives a consistent flux (see the discussion of Conservation below).

The fluxes are delivered to the two components on their own grids and at their own coupling intervals: to the atmosphere on the atmosphere grid at the atmosphere coupling interval, and to the ocean on the ocean grid at the ocean coupling interval. Because the ocean coupling interval is often longer than the atmosphere coupling interval, the atmosphere/ocean fluxes are accumulated and averaged over the ocean coupling interval before being sent to the ocean — the accumulate-then-average pattern visible in the run sequence.

Two aspects are configurable:

  • The grid on which the fluxes are computed. The calculation may be done on the atmosphere grid, the ocean grid, or a dedicated exchange grid formed from the overlap of the atmosphere and ocean grids. The states needed are mapped to the chosen grid, and the resulting fluxes are mapped to the grids of the components that use them. This choice affects accuracy and cost.

  • The flux algorithm. Different bulk-flux formulations are supported.

Note

Although it is conceptually a mediator computation, the atmosphere/ocean flux calculation code currently lives outside the shared mediator tree, in a host-specific location: under cesm/ (cesm/flux_atmocn) for CESM/NorESM and under ufs/ (ufs/flux_atmocn_mod.F90, with a CCPP variant) for UFS. The mediator phase that drives it, med_phases_aofluxes, is common; the full treatment is in the Developer Guide.

1.2.3.5. Ocean albedos

The mediator computes the ocean surface albedos as a function of the solar zenith angle. Four different ocean albedos are produced, spanning the two shortwave bands and the two illumination types:

  • direct-beam albedo, visible radiation

  • diffuse albedo, visible radiation

  • direct-beam albedo, near-infrared radiation

  • diffuse albedo, near-infrared radiation

These ocean albedos are then merged with the corresponding albedos obtained from the land and from the sea ice, and the merged albedos are sent to the atmosphere for its shortwave radiation calculation.

1.2.3.6. Land to land-ice downscaling

The land component sends its fields to the mediator on a set of elevation classes, but the land-ice (glc) component does not accept fields on elevation classes. The mediator therefore downscales these fields — mapping them from the land’s elevation-class representation onto the land-ice grid, using each land-ice cell’s actual elevation to select and interpolate the appropriate value. This is a vertical remapping driven by elevation, not a plain horizontal interpolation.

1.2.3.7. Surface fractions

Because a single atmosphere/land grid cell can overlap land, ocean and sea ice, the mediator tracks the fraction of each surface type in every cell. For a given atmosphere cell the land, ocean and ice fractions sum to one:

\[f_{al} + f_{ao} + f_{ai} = 1\]

Fractions are dynamic (the ice fraction changes as sea ice grows and melts) and are themselves mapped between grids. They appear as weights in essentially every merge, which is why a dedicated module maintains them. See the Developer Guide’s fractions page for details.

1.2.3.8. Conservation

A guiding requirement of the mediator is conservation of mass and energy: a flux leaving one component must deposit the same integrated quantity in the component that receives it, even after mapping and merging across mismatched grids. Achieving this ties together several details that must be considered together — mapping weights, masks, normalization, fraction weighting, and model-vs-ESMF area corrections. CMEPS uses unmasked, unnormalized conservative weights and then maps with a fraction-weighted, normalized approach, with merges carried out using fraction weights.

The full derivation — including why fraction-weighted normalized mapping conserves, how area corrections are applied to fluxes, and how accumulation interacts with mapping — is developed in the Developer Guide. It is important background for anyone changing how fields are coupled, but not required to run a coupled case.

Note

Two rules of thumb that recur in the conservation discussion:

  • Accumulate the fraction-weighted flux (f*F), never the fraction and flux separately — sum(f*F) is not sum(f)*sum(F).

  • Area corrections apply to fluxes only, are computed once at initialization, and do not vary in time.