roms cmeps.yaml

ROMS ESMF/NUOPC Configuration File For CMEPS: roms_cmeps.yaml

The roms_cmeps.yaml file specifies the ROMS Community Mediator for Earth Prediction Systems (CMEPS) Iconfiguration and Import/Export Metadata Dictionary. Starting svn revision -r 1902 released on March 1, 2022, the ROMS coupling metadata is managed with a YAML file. The YAML files are simple, easy to follow, elegant, portable, and expandable. ROMS can now process YAML files with its parser module, yaml_parser.F. Therefore, there is no need to use third-party YAML parsers. Basically, roms_cmeps.yaml has the following structure:

convention: CF

project: FV3-ROMS CMEPS couping in the WATL Application

title: Hurricane Isaias Test

date: 2020-07-31T00:00:00Z # Starting date, Hurricane Isaias
forecast_length: &ForecastLength PT96H # 6 hours (ISO 8601)

coupling_step: &dt 180.0d0 # 3 minutes (PT180S)

linked_grid: 1 # linked ROMS nested grid number

ATM_component: &ATM FV3
DATA_component: data.nc
OCN_component: &OCN ROMS

CoupledSet: ESM_01
ExportState: Export_ESM_01
ImportState: Import_ESM_01

PETlayoutOption: 0

CouplingType: 2 # semi-implicit

DebugLevel: 1 # reports informative messages
TraceLevel: 0

standard_input:
OCN_component: roms_watl.in
ATM_component: namelist

state variables: [sea_surface_height_above_geoid,
barotropic_sea_water_x_velocity,
barotropic_sea_water_y_velocity,
sea_water_x_velocity,
sea_water_y_velocity,
sea_water_potential_temperature,
sea_water_practical_salinity]

export: # OCN to ATM

- standard_name: sea_surface_temperature
long_name: sea surface temperature
short_name: SST
data_variables: [temperature, time]
source_units: C
destination_units: K
source_grid: cell_center
destination_grid: cell_center
add_offset: 273.15d0
scale: 1.0d0
debug_write: false
connected_to: *OCN
map_type: mapnstod
map_norm: none

# And so on. It is an expandable blocking list ...

import: # ATM to OCN

- standard_name: net_downward_shortwave_flux_at_sea_water_surface
long_name: surface net shortwave radiation flux
short_name: SWrad
data_variables: [swrad, time]
source_units: W m-2
destination_units: W m-2
source_grid: cell_center
destination_grid: cell_center
add_offset: 0.0d0
scale: 1.0d0
debug_write: false
connected_to: *ATM
map_type: mapbilnr
map_norm: none

# And so on. It is an expandable blocking list ...

bulk_fluxes import: # ATM to OCN if BULK_FLUXES is activated

- standard_name: net_downward_shortwave_flux_at_sea_water_surface
long_name: surface shortwave radiation flux
short_name: SWrad
data_variables: [swrad, time]
source_units: W m-2
destination_units: W m-2
source_grid: cell_center
destination_grid: cell_center
add_offset: 0.0d0
scale: 1.0d0
debug_write: false
connected_to: *ATM
map_type: mapbilnr
map_norm: none

# And so on. It is an expandable blocking list ...

The description key for each pair member of the YAML blocking list is as follows:

Key	Description
standard_name	The field's standard name. A list of all exchanged standard_name field are shown below.
long_name	The field's long descriptive name.
short_name	The field's short name private to the ESMF/NUOPC cap module
data_variables	The DATA component NetCDF field and associated time variable names.
source_units	The field's source units.
destination_units	The field's destination units.
source_grid	The field's source grid-cell location.
destination_grid	The field's destination grid-cell location.
add_offset	The value to add to the exchanged field.
scale	The scale to use to convert data from source to destination units.
debug_write	A switch indicating whether or not to write out exchanged field, if DebugLevel>2.
connected_to	The source component to which the field is connected.
map_type	CMEPS regridding flag from source to destination: Value Description mapbilnr bilinear mapping mapconsf first order conservative mapping with normalization type of conservative fraction mapconsd first order conservative mapping with normalization type of conservative destination mapfcopy redist mapping mapnstod nearest source to destination mapping mapnstod_consd nearest source to destination followed by conservative destination mapnstod_consf nearest source to destination followed by conservative fraction
map_norm	CMEPS mapping normalization flag: Value Description unset no normalization is set, should only be used if map_type is mapfcopy none no normalization is done, should only be used if map_type is not mapfcopy one normalize by 1 lfrin normalize by the lfrin field in FBFrac(compLND). Used to map LND->ATM. ifrac normalize by the ifrac field in FBFrac(compICE). Used to map ICE->ATM. ofrac normalize by the ofrac field in FBFrac(compOCN). Used to map ICE->ATM. custom custom mapping and normalization (used to map GLC->LND)

The ESM imported fields are processed as:

field (destination_units) = field (source_units) * scale + add_offset

YAML allows Anchors and Aliases to avoid repetition. In YAML, single or multiple line comments start with a hash #. Also, comment after a key/value pair is allowed. All comments are skipped during processing.

Exchanged Fields Metadata: short_name and standard_name

The following table shows the coupling metadata short_name and standard_name for the ESMF/NUOPC Export and Import states. They follow CF conventions closely. However, we needed to create lots of them because are not available in the CF tables but followed their established syntax. The list of exchanged fields is application dependent and YAML files are expandable and easy to modify.

short_name	standard_name
dLWrad	surface_net_downward_longwave_flux
Pair	surface_air_pressure
Qair	surface_relative_humidity
rain	precipitation_flux
shflux	surface_downward_heat_flux_in_sea_water
SST	sea_surface_temperature
sustr	surface_downward_x_stress
svstr	surface_downward_y_stress
swflux	surface_upward_water_flux
SWrad	net_downward_shortwave_flux_at_sea_water_surface
Tair	surface_air_temperature
Uwind	surface_eastward_wind
Vwind	surface_northward_wind