coupling esmf.in
The coupling_esmf.in file sets the parameters for the multiple model coupling ESMF/NUOPC Library. The name of this file is set by the BLANK keyword in the blank.in file. This standard input ASCII file is organized in several sections as shown below, with links to more detailed explanation where required.
Notice: Detailed information about ROMS input script file syntax can be found here.
Notice: A default coupling_esmf.in input script is provided in the ESM subdirectory.
Input Filenames
- Coupling import/export variables metadata filename.
- CPLname = coupling_esmf.dat
- Coupling free-format run sequence configuration filename.
- CONFname = esmApp.runconfig
- Coupled models standard input script or namelist filename.
Coupled Model Parameters
- Logical switch (T/F) indicating if an Earth System Model (ESM) component is active or not. It is also used to process some coupling parameters specified in this input script.
- Set which ESM components are connected to the ocean component (ROMS) during coupling (T/F). If ROMS has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsR] expected.
- Set which ESM components are connected to the atmosphere component during coupling (T/F). If the atmosphere component has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsA] expected.
- Set which ESM components are connected to the seaice component during coupling (T/F). If the seaice component has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsI] expected.
- Set which ESM components are connected to the wave component during coupling (T/F). If the wave component has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsW] expected.
- Model coupling type: 1 for explicit, 2 for Semi-Implicit.CouplingType = 1
In explicit coupling, the exchange fields at the next time-step (n+1) are defined using known values from the time-step (n) before it. Explicit methods require less computational effort and are accurate for small coupling time-steps.
In implicit coupling, the exchange fields at the next time-step (n+1) are defined by including values at the next time-step (n+1). Implicit methods are stable and allow longer coupling time-steps but are expensier.
In semi-implicit coupling, the exchange in one direction is explicit and in the reverse direction is implicit. For example:ROMS -> ATM Explicit exchange
ATM -> ROMS Implicit exchange
- Persistent Execution Thread (PET) layout option: 0 for sequential, coupled models executed on all the specified PETs, 1 for concurrent, coupled models executed on non-overlapping set of PETs.
- PETlayoutOption = 0
- DATA Model parallel distributed-memory domain decomposition.
- Number of PETs assigned to each model in the coupled system. If sequential layout (PETlayoutOption = 0), assign the same number of PETs to all coupled models. If concurrent layout (PETlayoutOption = 1), the number of PETs needed is the sum of all coupled model components. Only the PET values for IsActive(...)=T are processed and considered.
- Coupling debug flag:! [0] no debugging
! [1] reports informative messages
! [2] <1> and coupled components RunSequence
! [3] <2> and writes exchange fields into NetCDF files
! [4] <3> and writes grid information in VTK format
DebugLevel = 1
- Execution trace flag:! [0] no tracing
! [1] reports the sequence of coupling subroutine calls
! [2] <1> writes voluminous ESMF library tracing information
TraceLevel = 0
Time Management
- Set ESM coupling driver clock. If not re-starting, set StartTime and RestartTime to the same values. Set coupling time interval (TimeStep) to the largest value for the field exchange between activated ESM components. The parameters below are specified in terms of six integers vector as: [YYYY MM DD hh mm ss], where: YYYY is the 4 digit year, MM is the two digit month, hh is the two digit hour (0-23), mm is the two digit minutes (0-59) after the hour, and ss is the two digit seconds (0-59) after the minute.
- ReferenceTime = 2006 01 01 00 00 00 ! Simulation reference time
StartTime = 2014 01 01 00 00 00 ! Simulation start time
RestartTime = 2014 01 01 00 00 00 ! Simulation restart time
StopTime = 2014 01 06 00 00 00 ! Simulation stop time
TimeStep = 0000 00 00 03 00 00 ! Coupler driver interval
- ESM drive calendar. Current valid values are gregorian and year_360_day.
- Calendar = gregorian
- Coupling time interval fraction (INTEGER) from driver TimeStep indicating how often the exchange of information between ESM components occurs. That is, the coupling interval between ESM components is TimeStep/TimeFrac. If coupling nested grids, specify the respective number of values. Only active model components are processed and considered.
Components connected to ROMS, [1:NgridsR] expected.TimeFrac(ATM2OCN) == 1 ! atmosphere -> ROMS coupling, NgridsR
TimeFrac(ICE2OCN) == 1 ! seaice -> ROMS coupling, NgridsR
TimeFrac(WAV2OCN) == 1 ! wave -> ROMS coupling, NgridsR
TimeFrac(DAT2OCN) == 1 ! DATA -> ROMS coupling, NgridsR
Components connected to ATMOSPHERE, [1:NgridsA] expected.TimeFrac(OCN2ATM) == 1 ! ROMS -> atmosphere coupling, NgridsA
TimeFrac(ICE2ATM) == 1 ! seaice -> atmosphere coupling, NgridsA
TimeFrac(WAV2ATM) == 1 ! wave -> atmosphere coupling, NgridsA
TimeFrac(DAT2ATM) == 1 ! DATA -> atmosphere coupling, NgridsA
Components connected to SEAICE, [1:NgridsI] expected.TimeFrac(ATM2ICE) == 1 ! atmosphere -> seaice coupling, NgridsI
TimeFrac(OCN2ICE) == 1 ! ROMS -> seaice coupling, NgridsI
TimeFrac(WAV2ICE) == 1 ! wave -> seaice coupling, NgridsI
TimeFrac(DAT2ICE) == 1 ! DATA -> seaice coupling, NgridsI
Components connected to WAVE, [1:NgridsW] expected.
ESMF Internal Parameters
- The number of levels for creep fill extrapolation of unmapped destination points during regridding. After regular regridding, the creep fill method of unmapped points repeatedly moves data from mapped locations to the neighboring unmapped locations by the specified extrapNumLevels amount. For each creeped point, the extrapolation value is the average of the immediate neighbors from regridding. See ESMF Reference Manual (version 8.0 or higher) for ESMF_EXTRAPMETHOD_CREEP flag to ESMF_FieldRegridStore.
- extrapNumLevels = 4 ! number of levels for creep fill extrapolation
Melding Weighting Coefficients
- Melding coefficients used to combine fields from DATA and ESM components. The weight factors are read from the input NetCDF specified in the WeightsFile(atmos) keyword. The user has full control of how the merging is done. It is recommended to provide a gradual transition between the two components. The weighting factors have the same dimension as the atmosphere grid.
Recall that the DATA component supplies needed data to a particular ESM component. For example, it may export data to the atmosphere model at locations not covered by the other ESM components because of smaller grid coverage. If the atmosphere and ocean model grids are incongruent, the atmosphere component needs to import sea surface temperature (SST) on those grid points not covered by the ocean component. Thus, the weighting coefficients are used to merge the SST data:SST_atm(:,:) = Cesm(:,:) * SST_esm(;,;) + Cdat(:,:) * SST_dat(:,:)whereCesm(:,:) + Cdat(:,:) = 1.
Currently, only the atmosphere component needs the weigth coefficients when DATA_COUPLING is activated.WeightsFile(atmos) == meld_weights_atm.nc
VnameDATA(atmos) = data_weight
VnameESM(atmos) = ocean_weight
Import/Export Fields
Export/Import fields names (abbreviated string codes). Use the following string codes to set the fields to export/import for each coupled model. Currently, the fields below are processed. However, the list can be expanded easily.
Field | Export | Import | Description |
---|---|---|---|
NONE | - | - | No field to import or export |
shflx | atmos | roms | surface net heat flux |
cloud | atmos | roms | cloud fraction |
Hair | atmos | roms, cice | surface specific humidity |
Tair | atmos | roms, cice | surface air temperature |
Pair | atmos | roms, cice | surface air pressure |
Pmsl | atmos | roms | mean sea level pressure |
Qair | atmos | roms | surface relative humidity |
SWrad | atmos | roms | shortwave radiation flux |
SWrad_daily | atmos | roms | daily averaged shortwave radiation flux |
LWrad | atmos | roms | surface net longwave radiation flux |
dLWrad | atmos | roms | surface downward longwave radiation flux |
rain | atmos | roms | rain fall rate |
Uwind | atmos | roms, cice, waves | surface U-wind component |
Vwind | atmos | roms, cice, waves | surface V-wind component |
Ustr | atmos | roms, cice | surface U-momentum stress |
Vstr | atmos | roms, cice | surface V-momentum stress |
zlvl | atmos | cice | atmspheric height lowest level |
rhoa | atmos | cice | surface air density |
potT | atmos | cice | * surface air potential temperature |
flw | atmos | cice | mean downwelling longwave flux |
swvdr | atmos | cice | visible direct downward shortwave flux |
swvdf | atmos | cice | visible diffusive downward shortwave flux |
swidr | atmos | cice | infrared direct downward shortwave flux |
swidf | atmos | cice | infrared diffusive downward shortwave flux |
frain | atmos | cice | mean liquid precipitation rate |
fsnow | atmos | cice | mean frozen/snow precipitation rate |
aero_atm | atmos | cice | meam aerosol deposition rate |
ifrac | cice | atmos | fractional ice area |
vice | cice | atmos | ice volume per unit area |
vsno | cice | atmos | snow volume per unit area |
sit | cice | atmos | surface ice/snow temperature |
alvdr | cice | atmos | fractional visible band direct albedo |
alvdf | cice | atmos | fractional visible band diffusive albedo |
alidr | cice | atmos | fractional near-infrared band direct albedo |
alidf | cice | atmos | fractional near-infrared band diffusive albedo |
strairxT | cice | atmos | zonal stress on ice by air |
strairyT | cice | atmos | meridional stress on ice by air |
fsens | cice | atmos | ice sensible heat flux |
flat | cice | atmos | ice latent heat flux |
evap | cice | atmos | mean evaporative water flux |
flwout | cice | atmos | mean outgoing upward longwave radiation |
fhocn | cice | roms | net heat flux to ocean |
fresh | cice | roms | fresh water flux to ocean |
fpond | cice | roms | fresh water flux to ice ponds |
fsalt | cice | roms | salt flux to ocean |
strocnxT | cice | roms | zonal stress on ice by ocean |
strocnyT | cice | roms | meridional stress on ice by ocean |
fswthru | cice | roms | shortwave flux, ice to ocean |
fswthruvdr | cice | roms | visible direct band net shortwave, ice to ocean |
fswthruvdf | cice | roms | visible diffusive band net shortwave, ice to ocean |
fswthruidr | cice | roms | infrared direct band net shortwave, ice to ocean |
fswthruidf | cice | roms | infrared diffusive band net shortwave, ice to ocean |
frzmlt | roms | cice | freezing/melting potential |
hmix | roms | cice | mixed layer depth |
SSH | roms | cice, waves | sea surface height |
SST | roms | atmos, cice | sea surface temperature |
SSS | roms | cice | sea surface salinity |
ss_tltx | roms | cice | * sea surface slope, x-direction |
ss_tlty | roms | cice | * sea surface slope, y-direction |
Tf | roms | cice | freezing temperature |
Ubar | roms | waves | vertically integrated U-momentum |
Vbar | roms | waves | vertically integrated V-momentum |
Usur | roms | cice | zonal surface ocean curent |
Vsur | roms | cice | meridional surface ocean curent |
ZO | roms | waves | bottom roughness |
Wdir | waves | roms | wave direction |
Wamp | waves | roms | significant wave height |
Wlen | waves | roms | average wave length |
Wptop | waves | roms | surface wave relative peak period |
Wpbot | waves | roms | bottom wave period |
Wdiss | waves | roms | wave energy dissipation |
Wbrk | waves | roms | percent wave breaking |
Wubot | waves | roms | wave bottom orbital velocity |
Data Model Parameters
The USER has the option to enter a filename for each export field and further split data by time records into multiple files. If nested grids, the USER may provide a different set of filenames for each grid. The DATA model will scan the file list and will read the needed data from the first file in the list containing the export field. Therefore, the order of the filenames is critical. Detailed information about ROMS input script file syntax can be found here.
For each ESM component, specify the following information:
- nDataExport(...)
- The number of fields to export from DATA Model to specified ESM component. If zero value, exporting of fields to ESM component do not take place and the values in DataExport and DataFiles are ignored.
- nDataFiles(...)
- The number of NetCDF files that the DATA Model needs to process and read exporting fields.
- DataExport(...)
- Field short name string (see above table) to read and export to the specified ESM component, nDataExport values are expected for activated ESM component.
- DataFiles(...)
- NetCDF filenames containing the field to export to specified ESM component, nDataFiles are expected. The order of files in the list is essential. See detailed information about multi-files here.
Note: Currently, the DATA model only EXPORTS fields. It is improbable that the DATA model would ever need to import fields to itself.
If applicable, the USER has the option to enter several sets of filenames for each nested grid. Alternatively, if all the export fields are the same for each nesting grid, and the data is in its native resolution, we could enter only one set of filenames, and the DATA model will replicate those files internally to the remaining grids using the plural KEYWORD protocol. The USER may have different filenames for each export field.
The DATA model will scan the files and will read the needed data from the first file in the list containing the export field. Therefore, the order of the filenames is critical. If using multiple files per nested grid, first enter all the filenames for grid one followed by two, and so on. It is also possible to split input data time records into several files (see Input Parameter Files). Use a single line per entry with a continuation (\) or a vertical bar (|) symbol after each entry, except the last one.
DATA model export to ROMS.
nDataFiles(roms) = 8 ! number of NetCDF files to process
DataExport(roms) = dLWrad \
SWrad \
Pair \
Tair \
Qair \
rain \
Uwind \
Vwind
DataFiles(roms) = ../om/lwrad_down_nam_3hourly_MAB_and_GoM_2014.nc |
../om/lwrad_down_nam_3hourly_MAB_and_GoM_2015.nc |
../om/lwrad_down_nam_3hourly_MAB_and_GoM_2016.nc \
../om/swrad_nam_3hourly_MAB_and_GoM_2014.nc |
../om/swrad_nam_3hourly_MAB_and_GoM_2015.nc |
../om/swrad_nam_3hourly_MAB_and_GoM_2016.nc \
../om/Pair_nam_3hourly_MAB_and_GoM_2014.nc |
../om/Pair_nam_3hourly_MAB_and_GoM_2015.nc |
../om/Pair_nam_3hourly_MAB_and_GoM_2016.nc \
../om/Tair_nam_3hourly_MAB_and_GoM_2014.nc |
../om/Tair_nam_3hourly_MAB_and_GoM_2015.nc |
../om/Tair_nam_3hourly_MAB_and_GoM_2016.nc \
../om/Qair_nam_3hourly_MAB_and_GoM_2014.nc |
../om/Qair_nam_3hourly_MAB_and_GoM_2015.nc |
../om/Qair_nam_3hourly_MAB_and_GoM_2016.nc \
../om/rain_nam_3hourly_MAB_and_GoM_2014.nc |
../om/rain_nam_3hourly_MAB_and_GoM_2015.nc |
../om/rain_nam_3hourly_MAB_and_GoM_2016.nc \
../om/Uwind_nam_3hourly_MAB_and_GoM_2014.nc |
../om/Uwind_nam_3hourly_MAB_and_GoM_2015.nc |
../om/Uwind_nam_3hourly_MAB_and_GoM_2016.nc \
../om/Vwind_nam_3hourly_MAB_and_GoM_2014.nc |
../om/Vwind_nam_3hourly_MAB_and_GoM_2015.nc |
../om/Vwind_nam_3hourly_MAB_and_GoM_2016.nc
- DATA model export to the Atmosphere Model.nDataExport(atmos) = 0 ! number of fields to export
nDataFiles(atmos) = 0 ! number of NetCDF files to process
DataExport(atmos) = NONE
DataFiles(atmos) = data2atm.nc
- DATA model export to the Sea Ice Model.nDataExport(seaice) = 0 ! number of fields to export
nDataFiles(seaice) = 0 ! number of NetCDF files to process
DataExport(seaice) = NONE
DataFiles(seaice) = data2ice.nc
- DATA model export to the Wave Model.nDataExport(waves) = 0 ! number of fields to export
nDataFiles(waves) = 0 ! number of NetCDF files to process
DataExport(waves) = NONE
DataFiles(waves) = data2wav.nc