coupling.in

From WikiROMS
Jump to navigationJump to search
Model Coupling Input Script - coupling.in

File coupling.in is the ROMS standard input file for multi-model coupling via ESMF. This file defines the coupling parameters and sets the input files for the coupled models. This standard input ASCII file is organized in several sections as shown below, with links to more detailed explanation where required.

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

Note Notice: A default coupling.in input script is provided in the User/External subdirectory. Also there are several standard input scripts in the ROMS/External subdirectory which are used in the distributed test cases. They are usually named coupling_app.in where app is the lowercase of the test case cpp option.

Input Filenames

  • Coupling import/export variables metadata filename.
    CPLname = coupling_esmf_wrf.dat
  • Coupling free-format run sequence configuration filename.
    CONFname = wrf_implicit.runconfig

Coupled Model Parameters

  • Logical switch (TRUE/FALSE) 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. ESMF/NUOPC does not provide an elegant and straight forward way to couple nested grids. The current design is to treat each each nested grid as an independent ESM component. If nesting, provide as many values to IsActive(xxxx) as needed for each nested grid. The order of the values is important. If only one value is set, only the application's main grid is coupled. The first grid of active ESM components always needs to be coupled.
    IsActive(roms) = T  ! Activate coupling to ROMS
    IsActive(atmos) = T  ! Activate coupling to atmosphere model
    IsActive(seaice) = F  ! Activate coupling to seaice model
    IsActive(waves) = F  ! Activate coupling to wave model
    IsActive(data) = T  ! Activate coupling to DATA model
    The DATA model provides data to ESM components uncoupled fields or values at locations not covered by other coupled components because of non-coincident grids. For Example, If just coupling ROMS-CICE, the DATA model provides all the atmosphere forcing fields required by CICE; If atmosphere and ocean models grids are not coincident, the DATA model provides SST for locations not covered by the usually smaller ocean grid.


  • Logical switches (TRUE/FALSE) indicating which ESM components are connected to the ocean component (ROMS) during coupling. If ROMS has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsR] values expected.
    Coupled(ATM2OCN) == T  ! atmosphere -> ROMS connected
    Coupled(ICE2OCN) == F  ! seaice -> ROMS connected
    Coupled(WAV2OCN) == F  ! wave -> ROMS connected
    Coupled(DAT2OCN) == F  ! DATA -> ROMS connected
  • Logical switches (TRUE/FALSE) indicating which ESM components are connected to the atmosphere component during coupling. If the atmosphere component has nested grids, indicate which grids are connected to the other ESM components, [1:NgridsA] expected.
    Coupled(OCN2ATM) == T  ! ROMS -> atmosphere connected
    Coupled(ICE2ATM) == F  ! seaice -> atmosphere connected
    Coupled(WAV2ATM) == F  ! wave -> atmosphere connected
    Coupled(DAT2ATM) == T  ! DATA -> atmosphere connected
  • Logical switches (TRUE/FALSE) indicating which ESM components are connected to the seaice component during coupling. 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
  • Logical switches (TRUE/FALSE) indicating which ESM components are connected to the wave component during coupling. 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
  • Choose explicit or semi-implicit model coupling. 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 (not used), 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 more expensive. In semi-implicit coupling, the exchange in one direction is explicit and in the reverse direction is implicit. For Example, ROMS to the atmospheric model would be explicit but atmosphere to ROMS would be implicit.
    ! 1: Explicit
    ! 2: Semi-Implicit.

    CouplingType = 2
  • Persistent Execution Thread (PET) layout option:
    ! 0: Sequential, coupled models executed on all the specified PETs
    ! 1: Concurrent, coupled models executed on non-overlapping set of PETs

    PETlayoutOption = 0
  • Data Model parallel distributed-memory domain decomposition. Both values must be at least one.
    ItileD = 3  ! I-direction partition
    JtileD = 4  ! J-direction partition

Time Managing

  • 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. Check glossary below for more information.
    ! YYYY year of the century (integer)
    ! MM month of the year: 01 - 12 (integer)
    ! DD day of the month (integer)
    ! hh hour of the day: 01 - 23 (integer)
    ! mm minutes of the hour: 01 - 59 (integer)
    ! ss secound of the minute: 01 - 59 (integer)
    !
    ! YYYY MM DD hh mm ss

    ReferenceTime = 2006 01 01 00 00 00  ! Simulation reference time
    StartTime = 2011 08 27 06 00 00  ! Simulation start time
    RestartTime = 2011 08 27 06 00 00  ! Simulation restart time
    StopTime = 2011 08 29 00 00 00  ! Simulation stop time
    TimeStep = 0000 00 00 00 01 00  ! Coupler driver interval (60 sec ROMS DT)

    Calendar = gregorian

ESMF Library Internal Parameters

  • Internal ESMF parameter setting 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 Wighting Coefficients

  • Weighted coefficients for the merging of DATA component fields with the same field from other ESM components. Melding coefficients are positive and MUST add to unity. They are read from an input NetCDF file (WeightsFile). 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.

    The user needs to specify the NetCDF variable names for the weights for the DATA (VnameDATA) and ESM (VnameESM) components. Also, specify which grid (NestedGrid) needs a merged field from DATA and ESM components. Currently, the weight values are only needed by the atmosphere component.
    WeightsFile(atmos) = ../Data/WRF/irene_wrf_meld_weights.nc
    VnameDATA(atmos) = data_weight_smooth
    VnameESM(atmos) = ocean_weight_smooth
    NestedGrid(atmos) = 1
    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

Debugging and Tracing Options

  • 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 = 2
  • Execution trace flag:
    ! [0] no tracing
    ! [1] reports the sequence of coupling subroutine calls
    ! [2] <1> writes voluminous ESMF library tracing information

    TraceLevel = 0

Export/Import Fields Name Codes to Process

  • Use the following string codes to set the fields to export/import for each coupled model. An * in the field description indicates a field that is computed from an exchanged field and is 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 atmospheric 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.

  • 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 information about multi-files below.

Currently, the DATA model only EXPORTS fields. It is improbable that the DATA needs 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) == 0  ! number of fields to export

nDataFiles(roms) == 0  ! number of NetCDF files to process

DataExport(roms) == NONE

DataFiles(roms) == data2roms.nc

DATA model export to the Atmosphere Model

nDataExport(atmos) == 1  ! number of fields to export

nDataFiles(atmos) == 1  ! number of NetCDF files to process

DataExport(atmos) == dSST

DataFiles(atmos) == ../Data/HyCOM/hycom_mab3hours_sst_25aug2011_31aug2011.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.in&oldid=6014"