coupling.in

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.

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

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 models components standard input script or namelist filenames.
  INPname(roms) = roms_irene.in  ! ROMS unnested application
  INPname(atmos) = namelist.input  ! hardwired WRF filename
  INPname(seaice) = seaice.in
  INPname(waves) = waves.in

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

• 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) == 12  ! ocean model PETs
  Nthreads(atmos) == 12  ! atmosphere model PETs
  Nthreads(seaice) = 1  ! sea-ice model PETs
  Nthreads(waves) = 1  ! wave model PETs

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

• 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.
  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
  
  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
  
  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
  
  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 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

• Ocean model (ROMS) Import and Export fields: Import(1:Nimport) and Export(1:Nexport).
  Nimport(roms) = 9
  Nexport(roms) = 1
  
  Import(roms) = Pair \
  SWrad \
  dLWrad \
  LHfx \
  SHfx \
  shflux \
  swflux \
  sustr \
  svstr
  
  Export(roms) = SST

• Atmospheric model Import and Export fields: Import(1:Nimport) and Export(1:Nexport).
  Nimport(atmos) = 2
  Nexport(atmos) = 9
  
  Import(atmos) = SST \
  dSST
  
  Export(atmos) = Pair \
  SWrad \
  dLWrad \
  LHfx \
  SHfx \
  shflux \
  swflux \
  sustr \
  svstr

• Sea-ice model Import and Export fields: Import(1:Nimport) and Export(1:Nexport).
  Nimport(seaice) = 0
  Nexport(seaice) = 0
  
  Import(seaice) = NONE
  
  Export(seaice) = NONE

• Sea-ice model Import and Export fields: Import(1:Nimport) and Export(1:Nexport).
  Nimport(waves) = 0
  Nexport(waves) = 0
  
  Import(waves) = NONE
  
  Export(waves) = 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.

• 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