3.13. Adding a coupled field

Adding a new field for the mediator to exchange between two components is one of the most common CMEPS tasks, and it can be done on its own without touching the rest of the mediator. This page is a practical recipe. It assumes the Field exchange concepts (advertise/realize, addfld / addmap / addmrg) and the Fields and the field dictionary naming convention.

3.13.1. What you will touch

A new coupled field involves a handful of well-defined edits:

  1. the field dictionary — declare the field’s standard name and units;

  2. the host exchange module — advertise, map and merge it in esmFldsExchange_<host>_mod.F90;

  3. the component caps — make sure each component actually advertises the field so NUOPC connects it.

The first two are inside CMEPS; the third is on the component side (and outside CMEPS), but the connection will not form without it.

3.13.2. Step 1 — add the field to the dictionary

Add an entry for the field to the host field dictionary (fd_cesm.yaml for CESM/NorESM). Give it a standard name that follows the naming convention, its canonical units, and optionally an alias and description:

- standard_name: Sa_foo
  canonical_units: K
  description: my new near-surface atmosphere state

3.13.3. Step 2 — advertise, map and merge it

All of this goes in the host exchange module, esmFldsExchange_<host>_mod.F90.

Advertise the field on both sides, in the phase == 'advertise' block — from the source component and to the destination component:

call addfld_from(compatm, 'Sa_foo')   ! atmosphere can send it
call addfld_to(complnd, 'Sa_foo')     ! land can receive it

Map the field from the source grid to the destination grid, in the phase == 'initialize' block. Choose the map type and normalization appropriate to the field (see Mapping):

call addmap_from(compatm, 'Sa_foo', complnd, mapbilnr, 'none', 'unset')

Merge the mapped field into the destination’s export, also in the initialize block. For a field that comes from a single source, a plain copy is enough; a field built from several surfaces uses one addmrg_to call per source with a fraction weight (see Merging):

call addmrg_to(complnd, 'Sa_foo', mrg_from=compatm, mrg_fld='Sa_foo', &
               mrg_type='copy')

3.13.4. Step 3 — advertise the field in the component caps

The mediator advertises a superset of possible fields, but a connection is only made where the component on the other side advertises the field too (Field exchange). So the field must also be advertised by the component caps — the atmosphere cap must advertise Sa_foo as an export and fill it, and the land cap must advertise it as an import and use it. This is component code, outside CMEPS, but the coupling will silently not form without it.

3.13.5. Checklist

  • Field added to fd_<host>.yaml with correct name and units.

  • addfld_from / addfld_to in the advertise phase.

  • addmap_from with an appropriate map type and normalization.

  • addmrg_to with the appropriate merge type (and fraction, for weighted merges).

  • The source and destination component caps advertise the field.

If the field does not appear in the destination component, the first things to check are that both caps advertised it (so NUOPC connected it) and that the name matches the dictionary exactly.