coupling esmf.in

From WikiROMS
Jump to navigationJump to search
ESMF/NUOPC Coupling Input Script - 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.

Note Notice: Detailed information about ROMS input script file syntax can be found here.

Note 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.
INPname(roms) = roms.in
INPname(atmos) = atmos.in
INPname(seaice) = seaice.in
INPname(waves) = waves.in

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.
IsActive(roms) = T  ! ROMS
IsActive(atmos) = F  ! atmosphere model
IsActive(seaice) = F  ! seaice model
IsActive(waves) = F  ! wave model
IsActive(data) = T  ! DATA model
  • 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.
Coupled(ATM2OCN) == F  ! atmosphere -> ROMS connected
Coupled(ICE2OCN) == F  ! seaice -> ROMS connected
Coupled(WAV2OCN) == F  ! wave -> ROMS connected
Coupled(DAT2OCN) == T  ! DATA -> ROMS connected
  • 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.
Coupled(OCN2ATM) == F  ! ROMS -> atmosphere connected
Coupled(ICE2ATM) == F  ! seaice -> atmosphere connected
Coupled(WAV2ATM) == F  ! wave -> atmosphere connected
Coupled(DAT2ATM) == F  ! DATA -> atmosphere connected
  • 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.
Coupled(ATM2ICE) == F  ! atmosphere -> seaice connected
Coupled(OCN2ICE) == F  ! ROMS -> seaice connected
Coupled(WAV2ICE) == F  ! wave -> seaice connected
Coupled(DAT2ICE) == F  ! DATA -> seaice connected
  • 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.
Coupled(ATM2WAV) == F  ! atmosphere -> wave connected
Coupled(ICE2WAV) == F  ! seaice -> wave connected
Coupled(OCN2WAV) == F  ! ROMS -> wave connected
Coupled(DAT2WAV) == F  ! DATA -> wave connected
  • 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.
ItileD = 2  ! I-direction partition
JtileD = 2  ! J-direction partition
  • 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.
Nthreads(roms) = 4  ! ocean model PETs
Nthreads(atmos) = 1  ! atmosphere model PETs
Nthreads(seaice) = 1  ! seaice model PETs
Nthreads(waves) = 1  ! wave model PETs
  • 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.
    TimeFrac(ATM2WAV) == 1  ! atmosphere -> wave coupling, NgridsW
    TimeFrac(ICE2WAV) == 1  ! seaice -> wave coupling, NgridsW
    TimeFrac(OCN2WAV) == 1  ! ROMS -> wave coupling, NgridsW
    TimeFrac(DAT2WAV) == 1  ! DATA -> wave coupling, NgridsW

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(:,:)
    where
    Cesm(:,:) + 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.

(*) Computed from an exchanged field, not regridded.
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
  • Ocean model (ROMS) Import and Export fields: Import(1:Nimport) and Export(1:Nexport).
    Nimport(roms) = 8
    Nexport(roms) = 0

    Import(roms) = dLWrad \
    SWrad \
    Pair \
    Tair \
    Qair \
    rain \
    Uwind \
    Vwind

    Export(roms) = NONE

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.

NoteNote: 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.

nDataExport(roms) = 8  ! number of fields to export

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
Retrieved from "https://www.myroms.org/wiki/index.php?title=coupling_esmf.in&oldid=5746"