2.6. Fields and the field dictionary

Components are connected by matching standard field names, not by position or order (see Core concepts). This page describes the field dictionary that defines those names, the naming convention they follow, and where field names show up when you configure or debug a run.

2.6.1. The field dictionary

For CESM/NorESM the field dictionary is the YAML file mediator/fd_cesm.yaml. It is a community-based dictionary of the shared coupling fields: every field that can be exchanged has an entry giving its standard name, canonical units, and (optionally) a longer alias and a description. For example:

- standard_name: Faox_evap
  alias: mean_evap_rate_atm_into_ocn
  canonical_units: kg m-2 s-1
  description: med export - atm/ocn evaporation water flux computed in mediator

Each entry has:

  • standard_name — the short name used throughout CMEPS to make connections (for example Faox_evap).

  • alias — an optional longer, self-describing NUOPC-style name (mean_evap_rate_atm_into_ocn).

  • canonical_units — the units the field is expected in.

  • description — an optional human-readable description.

A connection between two components is made only when a field’s standard name appears in the export of one component and the import of another; the dictionary is what guarantees both sides agree on the name and the units.

Note

Each host application has its own field dictionary, and they are not provided the same way:

  • For CESM/NorESM, the dictionary is fd_cesm.yaml and it ships with the CMEPS code (mediator/fd_cesm.yaml).

  • For UFS, the dictionary is fd_ufs.yaml and it is not part of the CMEPS code — it is provided by the UFS application.

2.6.2. The naming convention

The CMEPS field-name convention is independent of the specific model components. It distinguishes state fields from flux fields, and encodes which components are involved using a one-letter designation:

a => atmosphere      o => ocean
i => sea ice         r => river
l => land            w => wave
g => land-ice        x => mediator (merged, after mapping and merging)

2.6.2.1. State variables

A state variable has a three-character prefix S<c>_ — where <c> is one of the component letters above — followed by the field name. For example:

  • Sa_t — temperature as a state from the atmosphere.

  • Sx_t — the merged surface temperature (from land, sea ice and ocean) that the mediator sends to the atmosphere.

2.6.2.2. Flux variables

A flux variable has a five-character prefix F<c1><c2><n>_ followed by the flux name. Here <c1> and <c2> are the two components the flux is between, and <n> is the component that computed it. For example:

Imported to the mediator:

Faxa_   atm flux computed by the atmosphere
Fall_   lnd-atm flux computed by the land
Fioi_   ice-ocn flux computed by the sea ice
Faii_   ice-atm flux computed by the sea ice
Flrr_   lnd-rof flux computed by the river
Firr_   rof-ice flux computed by the river

Exported from the mediator (merged):

Faxx_   merged fluxes sent to the atmosphere
Foxx_   merged fluxes sent to the ocean
Fixx_   merged fluxes sent to the sea ice

So a name like Faxa_rainc tells you it is a flux (F) between the atmosphere and the mediator, computed by the atmosphere (Faxa_) — here a convective rain flux the atmosphere provides.

2.6.3. Where you encounter field names

Field names from the dictionary appear in several places you touch when configuring or debugging a CESM/NorESM run:

  • Auxiliary history streams — the histaux_*_flds settings in user_nl_cpl list fields by standard name (see Configuring and running a case (CESM/NorESM)).

  • Mediator history and diagnostics output — field names identify the coupled fields the mediator writes.

  • Debugging — when a connection fails or a field is missing, the message refers to the standard name; matching it against fd_cesm.yaml is the first thing to check.

2.6.4. Adding a new field

Adding a new coupled field starts with the field dictionary (a new entry in fd_cesm.yaml) and then wiring it into the exchange logic that advertises, maps and merges it. That process is a developer task, covered in the Developer Guide.