roms.in

From WikiROMS
Jump to navigationJump to search
Standard Input Script - roms.in

Note Notice: In SVN revision 933 (January 26, 2019), all "ocean_*.in" files were renamed to roms_*.in and all ocean* ROMS executables were renamed to roms* in order to facilitate and clarify model coupling efforts. More information can be found in the ROMS repository Trac ticket #794.


File roms.in is the ROMS standard input file to any model run. This file sets the application spatial dimensions and many of the parameters that are not specified at compile time, including parallel tile decomposition, timestepping, physical coefficients and constants, vertical coordinate set-up, logical switches and flags to control the frequency of output, the names of input and output NetCDF files, and additional input scripts names for data assimilation, stations, floats trajectories, ecosystem models, and sediment model.

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 roms.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 roms_app.in where app is the lowercase of the test case cpp option.

Configuration Parameters

  • Application title. This string will be saved in the output NetCDF files.
    TITLE = Wind-Driven Upwelling/Downwelling over a Periodic Channel
  • C-preprocessing Flag to define the specific configuration.
    MyAppCPP = UPWELLING
    Though this is set by ROMS_APPLICATION in the makefile or build Script, ROMS is also compiled with -D$(ROMS_APPLICATION), which allows the use of
    #ifdef UPWELLING
    for instance. The net result of both
    -D$(ROMS_APPLICATION)=UPWELLING -DUPWELLING
    is that ROMS_APPLICATION becomes 1 in the source code. ROMS therefore needs to be told the application name here as well in order to report it to the output file.
  • Input variable information file name. This file needs to be processed first so all information arrays can be initialized properly. Notice that we need an absolute or relative path for input metadata file varinfo.dat. There are many posts in the ROMS Forum of new users that fail to specify the correct location of this file. Expert users usually have the own modified copy of this file for a particular application.
    VARNAME = ROMS/External/varinfo.dat
NoteNOTE: Starting with revision 460 file names can be up to 256 characters long. Previously only 80 characters were allowed.
  • Number of nested grids.
    Ngrids = 1
  • Number of grid nesting layers. This parameter is used to allow refinement and composite grid combinations.
  • Grid dimension parameters. These are used to dynamically allocate all model state variables upon execution.
    Lm == 41  ! Number of I-direction INTERIOR RHO-points
    Mm == 80  ! Number of J-direction INTERIOR RHO-points
    N == 16  ! Number of vertical levels

    Nbed = 0  ! Number of sediment bed layers

    NAT = 2  ! Number of active tracers (usually, 2)
    NPT = 0  ! Number of inactive passive tracers
    NCS = 0  ! Number of cohesive (mud) sediment tracers
    NNS = 0  ! Number of non-cohesive (sand) sediment tracers
  • Domain decomposition parameters for serial, distributed-memory or shared-memory configurations used to determine tile horizontal range indices (Istr,Iend) and (Jstr,Jend), [1:Ngrids] values are expected.
    NtileI == 1  ! I-direction partition
    NtileJ == 1  ! J-direction partition

Tracer Advection Schemes

Set horizontal and vertical advection schemes for active and inert tracers. A different advection scheme is allowed for each tracer. For example, a positive-definite (monotonic) algorithm can be activated for salinity and inert tracers, while a different one is set for temperature.

It is more advantageous to set the horizontal and vertical advection schemes for each tracer with switches instead of a single CPP flag for all of them. Positive-definite and monotonic algorithms (i.e., MPDATA and HSIMT) are appropriate and useful for positive fields like salinity, inert, biological, and sediment tracers. However, since the temperature has a dynamic range with negative and positive values in the ocean, other advection schemes are more appropriate.

Currently, the following tracer advection schemes are available and are activated using the associated Keyword:

Keyword Advection Algorithm

A4 4th-order Akima (horizontal/vertical)
C2 2nd-order centered differences (horizontal/vertical)
C4 4th-order centered differences (horizontal/vertical)
HSIMT 3th-order HSIMT with TVD limiter (horizontal/vertical)
MPDATA recursive flux corrected MPDATA (horizontal/vertical)
SPLINES parabolic splines reconstruction (only vertical)
SU3 split third-order upstream (horizontal/vertical)
U3 3rd-order upstresm-bias (only horizontal)

The user has the option of specifying the full Keyword or the first two letters, regardless if using uppercase or lowercase.

If using either HSIMT (Wu and Zhu, 2010) or MPDATA (Smolarkiewicz and Margolin, 1998) options, the user needs to set the same scheme for both horizontal and vertical advection to preserve monotonicity.

  • Horizontal and vertical advection for each active (temperature and salinity) and inert tracer, [1:NAT+NPT,Ngrids] values are expected.
    Hadvection == U3 \  ! temperature
    U3 \  ! salinity
    HSIMT \  ! dye_01, inert(1)
    HSIMT  ! dy2_02, inert(2)

    Vadvection == C4 \  ! temperature
    C4 \  ! salinity
    HSIMT \  ! dye_01, inert(1)
    HSIMT  ! dy2_02, inert(2)
  • Horizontal and vertical advection for each active (temperature and salinity) and inert tracer for adjoint-based algorithms can have different horizontal schemes, [1:NAT+NPT,Ngrids] values are expected.
    ad_Hadvection == U3 \  ! temperature
    U3 \  ! salinity
    HSIMT \  ! dye_01, inert(1)
    HSIMT  ! dy2_02, inert(2)

    ad_Vadvection == C4 \  ! temperature
    C4 \  ! salinity
    HSIMT \  ! dye_01, inert(1)
    HSIMT  ! dy2_02, inert(2)


Lateral Open Boundary Conditions Parameters

  • The lateral boundary conditions are now specified with logical switches instead of CPP flags to allow nested grid configurations. Their values are loaded into the structured array:
    LBC(1:4, nLBCvar, Ngrids)
    where 1:4 are the numbered boundary edges, nLBCvar are the number LBC state variables, and Ngrids is the number of nested grids. For example, to apply gradient boundary conditions for free-surface we use:
    LBC(iwest, isFsur, ng) % gradient
    LBC(ieast, ... , ng) % gradient
    LBC(isouth, ... , ng) % gradient
    LBC(inorth, ... , ng) % gradient
    The lateral boundary conditions are entered with a keyword. A value is expected for each boundary segment per nested grid for each state variable. Each tracer variable requires [1:4,1:NAT+NPT,Ngrids] values. [1:4,1:Ngrids] values are expected for other variables. The boundary order is: 1=west, 2=south, 3=east, and 4=north. That is, anticlockwise starting at the western boundary.

    The keyword is case insensitive and usually has three characters. However, it is possible to have compound keywords, if applicable. For example, the keyword RadNud implies radiation boundary condition with nudging. This combination is usually used in active/passive radiation conditions.
    ! Keyword Lateral Boundary Condition Type
    !
    ! Cha Chapman
    ! Cla Clamped
    ! Clo Closed
    ! Fla Flather _____N_____ j=Mm
    ! Gra Gradient | 4 |
    ! Nes Nested | |
    ! Nud Nudging 1 W E 3
    ! Per Periodic | |
    ! Rad Radiation |_____S_____|
    ! Red Reduced Physics 2 j=1
    ! i=1 i=Lm
    ! W S E N
    ! e o a o
    ! s u s r
    ! t t t t
    ! h h
    !
    ! 1 2 3 4


    LBC(isFsur) == Per Clo Per Clo  ! free-surface
    LBC(isUbar) == Per Clo Per Clo  ! 2D U-momentum
    LBC(isVbar) == Per Clo Per Clo  ! 2D V-momentum
    LBC(isUvel) == Per Clo Per Clo  ! 3D U-momentum
    LBC(isVvel) == Per Clo Per Clo  ! 3D V-momentum
    LBC(isMtke) == Per Clo Per Clo  ! mixing TKE

    LBC(isTvar) == Per Clo Per Clo \  ! temperature
    Per Clo Per Clo  ! salinity
  • Lateral open boundary edge volume conservation switch for nonlinear model and adjoint-based algorithm. This is usually activated with radiation boundary conditions to enforce global mass conservation. Notice that these switches should not be activated if tidal forcing, [1:Ngrids] values are expected.
    VolCons(west) == F  ! western boundary
    VolCons(east) == F  ! eastern boundary
    VolCons(south) == F  ! southern boundary
    VolCons(north) == F  ! northern boundary

    ad_VolCons(west) == F  ! western boundary
    ad_VolCons(east) == F  ! eastern boundary
    ad_VolCons(south) == F  ! southern boundary
    ad_VolCons(north) == F  ! northern boundary

Timestepping and Iterations Parameters

  • Timestepping parameters.
    NTIMES = 1440  ! Number of timesteps
    DT == 300.0d0  ! Timestep size (seconds)
    NDTFAST == 30  ! Number of barotropic steps
  • Total number of timesteps for computing observations impacts interval during the analysis (NTIMES_ANA) or forecast (NTIMES_FCT) cycle.
    NTIMES_ANA = 1440  ! analysis interval
    NTIMES_FCT = 1440  ! forecast interval
  • Model iteration loops parameters.
    ERstr = 1  ! Starting perturbation or iteration
    ERend = 1  ! Ending perturbation or iteration
    Nouter = 1  ! Maximum number of 4DVar outer loop iterations
    Ninner = 1  ! Maximum number of 4DVar inner loop iterations
    Nintervals = 1  ! Number of stochastic optimals interval divisions
  • Number of eigenvalues (NEV) and eigenvectors (NCV) to compute for the Lanczos/Arnoldi problem in the Generalized Stability Theory (GST) analysis. NCV must be greater than NEV.
    NEV = 2  ! Number of eigenvalues
    NCV = 10  ! Number of eigenvectors
    Note Notice: At present, there is no apriori analysis to guide the selection of NCV relative to NEV. The only formal requirement is that NCV > NEV. However in optimal perturbations, it is recommended to have NCV ≥ 2*NEV. In Finite Time Eigenmodes (FTE) and Adjoint Finite Time Eigenmodes (AFTE) the requirement is to have NCV ≥ 2*NEV+1. The efficiency of calculations depends critically on the combination of NEV and NCV. If NEV is large (greater than 10 say), you can use NCV=2*NEV+1 but for NEV small (less than 6) it will be inefficient to use NCV=2*NEV+1. In complicated applications, you can start with NEV=2 and NCV=10. Otherwise, it will iterate for very long time.

Output Frequency Parameters

  • Flags controlling the frequency of output.
    NRREC = 0  ! Model restart flag
    LcycleRST == T  ! Switch to recycle restart time records
    NRST == 288  ! Number of timesteps between writing restart records
    NSTA == 1  ! Number of timesteps between stations records
    NFLT == 1  ! Number of timesteps between floats records
    NINFO == 1  ! Number of timesteps between printing information diagnostics
  • Output history, average, diagnostic files parameters.
    LDEFOUT == T  ! File creation/append switch
    NHIS == 72  ! Number of timesteps between writing history records
    NDEFHIS == 0  ! Number of timesteps between creation of new history file
    NQCK == 0  ! Number of timesteps between writing quicksave records
    NDEFQCK == 0  ! Number of timesteps between creation of new quicksave file
    NTSAVG == 1  ! Starting averages timestep
    NAVG == 72  ! Number of timesteps between writing averages records
    NDEFAVG == 0  ! Number of timesteps between creation of new averages file
    NTSDIA == 1  ! Starting diagnostics timestep
    NDIA == 72  ! Number of timesteps between writing diagnostics records
    NDEFDIA == 0  ! Number of timesteps between creation of new diagnostics file
  • Output tangent linear and adjoint models parameters.
    LcycleTLM == F  ! Switch to recycle TLM time records
    NTLM == 72  ! Number of timesteps writing between TLM records
    NDEFTLM == 0  ! Number of timesteps between creation of new TLM file
    LcycleADJ == F  ! Switch to recycle ADM time records
    NADJ == 72  ! Number of timesteps between writing ADM records
    NDEFADJ == 0  ! Number of timesteps between creation of new ADM file
    NSFF == 72  ! Number of timesteps between 4DVAR adjustment of
     ! surface forcing fluxes
    NOBC == 72  ! Number of timesteps between 4DVAR adjustment of
     ! open boundary fields
  • Output check pointing GST restart parameters.
    LmultiGST = F  ! one eigenvector per history file
    LrstGST = F  ! GST restart switch
    MaxIterGST = 500  ! maximum number of iterations
    NGST = 10  ! check pointing interval

Physical and Numerical Parameters

  • Relative accuracy of the Ritz values computed in the GST analysis.
    Ritz_tol = 1.0d-15
  • Harmonic/biharmonic horizontal diffusion of all active and passive (dye) tracers for the nonlinear model and adjoint-based algorithms: [1:NAT+NPT,Ngrids] values are expected. Diffusion coefficients for biology and sediment tracers are set in their respective input scripts.
    TNU2 == 0.0d0 0.0d0  ! m2/s
    TNU4 == 2*0.0d0  ! m4/s

    ad_TNU2 == 0.0d0 0.0d0  ! m2/s
    ad_TNU4 == 0.0d0 0.0d0  ! m4/s
  • Harmonic/biharmonic, horizontal viscosity coefficient for the nonlinear model and adjoint-based algorithms: [1:Ngrids values are expected. Only used if the appropriate CPP options are defined.
    VISC2 == 0.0d0  ! m2/s
    VISC4 == 0.0d0  ! m4/s

    ad_VISC2 == 0.0d0  ! m2/s
    ad_VISC4 == 0.0d0  ! m4/s
  • Logical switches (TRUE/FALSE) to increase/decrease horizontal viscosity and/or diffusivity in specific areas of the application domain (like sponge areas) for the desired application grid.
    LuvSponge == F  ! horizontal momentum
    LtracerSponge == F F  ! temperature, salinity, inert
  • Background vertical mixing coefficients for active (NAT) and inert (NPT) tracers for the nonlinear model and basic state scale factor in adjoint-based algorithms: [1:NAT+NPT,Ngrids] values are expected.
    AKT_BAK == 1.0d-6 1.0d-6  ! m2/s

    ad_AKT_fac == 1.0d0 1.0d0 !nondimensional
  • Background vertical mixing coefficient for momentum for the nonlinear model and basic state scale factor in the adjoint-based algorithms: [1:Ngrids] values are expected.
    AKV_BAK == 1.0d-5  ! m2/s

    ad_AKV_fac == 1.0d0 !nondimensional
  • Upper threshold values to limit vertical mixing coefficients computed from vertical mixing parameterizations. Although this is an engineering fix, the vertical mixing values inferred from ocean observations are rarely higher than this upper limit value.
    AKT_LIMIT == 1.0d-3 1.0d-3  ! m2/s

    AKV_LIMIT == 1.0d-3  ! m2/s
  • Turbulent closures parameters.
    AKK_BAK == 5.0d-6  ! m2/s
    AKP_BAK == 5.0d-6  ! m2/s
    TKENU2 == 0.0d0  ! m2/s
    TKENU4 == 0.0d0  ! m4/s
  • Generic length-scale turbulence closure parameters. These parameters are used when GLS_MIXING is activated.
    GLS_P == 3.0d0  ! K-epsilon
    GLS_M == 1.5d0  ! Turbulent kinetic energy exponent
    GLS_N == -1.0d0  ! Turbulent length scale exponent
    GLS_Kmin == 7.6d-6  ! Minimum value of specific turbulent energy
    GLS_Pmin == 1.0d-12  ! Minimum Value of dissipation

    ! Closure independent constraint parameters:

    GLS_CMU0 == 0.5477d0  ! Stability coefficient
    GLS_C1 == 1.44d0  ! Shear production coefficient
    GLS_C2 == 1.92d0  ! Dissipation coefficient
    GLS_C3M == -0.4d0  ! Buoyancy production coefficient (minus)
    GLS_C3P == 1.0d0  ! Buoyancy production coefficient (plus)
    GLS_SIGK == 1.0d0  ! Constant Schmidt number for turbulent
     ! kinetic energy diffusivity
    GLS_SIGP == 1.30d0  ! Constant Schmidt number for turbulent
     ! generic statistical field, "psi"
  • Constants used in surface turbulent kinetic energy flux computation.
    CHARNOK_ALPHA == 1400.0d0  ! Charnok surface roughness
    ZOS_HSIG_ALPHA == 0.5d0  ! Roughness from wave amplitude
    SZ_ALPHA == 0.25d0  ! roughness from wave dissipation
    CRGBAN_CW == 100.0d0  ! Craig and Banner wave breaking
  • Constants used in momentum stress computation.
    RDRG == 3.0d-04  ! m/s
    RDRG2 == 3.0d-03  ! nondimensional
    Zob == 0.02d0  ! m
    Zos == 0.02d0  ! m
  • Height (m) of atmospheric measurements for Bulk fluxes parameterization.
    BLK_ZQ == 10.0d0  ! air humidity
    BLK_ZT == 10.0d0  ! air temperature
    BLK_ZW == 10.0d0  ! winds
  • Minimum depth for wetting and drying.
    DCRIT == 0.10d0  ! m
  • Jerlov water type used to set vertical depth scale for shortwave radiation absorption.
    WTYPE == 1
  • Mean Density and Brunt-Vaisala frequency.
    RHO0 = 1025.0d0  ! kg/m3
    BVF_BAK = 1.0d-4  ! 1/s2
  • Timestamp assigned for model initialization, reference time origin for tidal forcing, and model reference time for output NetCDF units attribute.
    DSTART = 0.0d0  ! days
    TIDE_START = 0.0d0  ! days
    TIME_REF = 0.0d0  ! yyyymmdd.dd
  • Nudging/relaxation time scales, inverse scales will be computed internally, [1:Ngrids] values are expected. These values are used for two purposes.
  1. When climatology nudging is active throughout the domain because the logical flags LtracerCLM, Lm3CLM, Lm2CLM etc. are TRUE, these values are the default nudging time scales set in Functionals/ana_nudgcoef.h. Since the user can choose to customize ana_nudgcoef.h, or provide 3-D climatology nudging time scales in an external file, these parameters might not be used
  2. When nudging is applied in the lateral open boundary conditions because the LBC logical flags are set to "RadNud" the values here set the nudging time scale when the Orlanski radiation scheme detects outflow conditions. When the Orlanski scheme detects inflow conditions, the nudging time scale is TNUDG/OBCFAC (see OBCFAC below).
TNUDG == 2*0.0d0  ! days
ZNUDG == 0.0d0  ! days
M2NUDG == 0.0d0  ! days
M3NUDG == 0.0d0  ! days
  • Factor between passive (outflow) and active (inflow) (in the Orlanksi radiation sense) open boundary condition nudging time scales, [1:Ngrids]. If OBCFAC > 1, nudging on inflow is stronger than on outflow (recommended) because the inflow time scale TNUDG/OBCFAC is less than the outflow timescale TNUDG (see above). The passive/active radiation conditions in ROMS follow the method proposed by Marchesiello et al. (2001):
    with
    where represents the external boundary data and is the nudging time scale with for outflow, for inflow, and . At outflow, a weak nudging is used to prevent a numerical drift in the solution while avoiding over-specification of the boundary data. During inflow, a strong nudging is applied to avoid data-shock in the solution. The nudging time scales provided above are for the outflow (passive) conditions, , in days. The inflow nudging factor in the above equation is .
    OBCFAC == 10.0d0  ! nondimensional
  • Linear equation of State parameters, [1:Ngrids] values are expected.
    R0 == 1027.0d0  ! kg/m3
    T0 == 10.0d0  ! Celsius
    S0 == 35.0d0  ! nondimensional
    TCOEF == 1.7d-4  ! 1/Celsius
    SCOEF == 7.6d-4  ! 1/nondimensional
  • Slipperiness parameter: 1.0 (free slip) or -1.0 (no slip).
    GAMMA2 = 1.0d0
  • Logical switches (TRUE/FALSE) to activate horizontal momentum transport point Sources/Sinks (like river runoff) and mass point Sources/Sinks (like volume vertical influx): [1:Ngrids] values are expected. These switches replace obsolete CPP options UV_PSOURCE and Q_PSOURCE, respectively. In nesting, a particular grid may or may not have Sources/Sinks forcing.
    LuvSrc == F  ! horizontal momentum transport
    LwSrc == F  ! volume vertical influx
  • Logical switches (TRUE/FALSE) to activate tracers point Sources/Sinks (like river runoff) and to specify which tracer variables to consider: [1:NAT+NPT,Ngrids] values are expected. Other biological and sediment tracer switches are activated in their respective input scripts. This switch replaces obsolete CPP option TS_PSOURCE. In nesting, a particular grid may or may not have tracers Sources/Sinks forcing.
    LtracerSrc == F F  ! temperature, salinity, inert
  • Logical switches (TRUE/FALSE) to read and process climatology fields.
    LsshCLM == F  ! sea-surface height
    Lm2CLM == F  ! 2D momentum
    Lm3CLM == F  ! 3D momentum

    LtracerCLM == F F  ! temperature, salinity, inert
  • Logical switches (TRUE/FALSE) to nudge the desired climatology field(s). If not analytical climatology fields, users need to turn ON the logical switches above to process the fields from the climatology NetCDF file that are needed for nudging.
    LnudgeM2CLM == F  ! 2D momentum
    LnudgeM3CLM == F  ! 3D momentum

    LnudgeTCLM == F F  ! temperature, salinity, inert

Vertical Coordinates Parameters

  • Set vertical, terrain-following coordinates transformation equation and stretching function (see Vertical S-coordinate for more details).
    Vtransform == 2  ! transformation equation
    Vstretching == 4  ! stretching function
  • S-coordinate surface control parameter, [1:Ngrids] values are expected. The range of optimal values depends on the vertical stretching function.
    THETA_S == 3.0d0  ! surface stretching parameter
  • S-coordinate bottom control parameter, [1:Ngrids] values are expected. The range of optimal values depends on the vertical stretching function.
    THETA_B == 0.0d0  ! bottom stretching parameter
  • Critical depth (hc) in meters (positive) controlling the stretching. It can be interpreted as the width of surface or bottom boundary layer in which higher vertical resolution (levels) is required during stretching.
    TCLINE == 25.0d0  ! critical depth (m)

Adjoint Sensitivity Parameters

  • Starting (DstrS) and ending (DendS) day for adjoint sensitivity forcing. DstrS must be less or equal to DendS. If both values are zero, their values are reset internally to the full range of the adjoint integration.
    DstrS == 0.0d0  ! starting day
    DendS == 0.0d0  ! ending day
  • Starting and ending vertical levels of the 3D adjoint state variables whose sensitivity is required.
    KstrS == 1  ! starting level
    KendS == 1  ! ending level
  • Logical switches (TRUE/FALSE) to specify the adjoint state tracer variables whose sensitivity is required, [1:NT,1:Ngrids] values are expected.
    Lstate(isTvar) == F F  ! NT tracers

Stochastic Optimals Parameters

  • Stochastic optimals time decorrelation scale (days) assumed for red noise processes.
    SO_decay == 2.0d0  ! days

History Output Variables Switches

  • Logical switches (TRUE/FALSE) to activate writing of extra inert passive tracers other than biological and sediment tracers. An inert passive tracer is one that it is only advected and diffused. Other processes are ignored. These tracers include, for example, dyes, pollutants, oil spills, etc. [1:NPT] values are expected. However, these switches can be activated using compact parameter specification.
    Hout(inert) == T  ! dye_01, ... inert passive tracers


Quicksave Output Variables Switches

  • Logical switches (TRUE/FALSE) to activate writing of extra inert passive tracers other than biological and sediment tracers into the quicksave output file. An inert passive tracer is one that it is only advected and diffused. Other processes are ignored. These tracers include, for example, dyes, pollutants, oil spills, etc. [1:NPT] values are expected. However, these switches can be activated using compact parameter specification.
    Qout(inert) == F  ! dye_01, ... inert passive tracers
    Qout(Snert) == F  ! dye_01, ... surface inert passive tracers


Time-averaged Output Variables Switches

  • Logical switches (TRUE/FALSE) to activate writing of extra inert passive tracers other than biological and sediment tracers into the time-averaged output file. An inert passive tracer is one that it is only advected and diffused. Other processes are ignored. These tracers include, for example, dyes, pollutants, oil spills, etc. [1:NPT,1:Ngrids] values are expected. However, these switches can be activated using compact parameter specification.
    Aout(inert) == T  ! dye_01, ... inert passive tracers

Time-averaged Diagnostic Output Variables Switches

  • Logical switches (TRUE/FALSE) to activate writing time-averaged. 2D momentum (ubar, vbar) diagnostic terms into the diagnostics output file.
    Dout(M2rate) == T  ! ubar_accel, ... acceleration
    Dout(M2pgrd) == T  ! ubar_prsgrd, ... pressure gradient
    Dout(M2fcor) == T  ! ubar_cor, ... Coriolis force
    Dout(M2hadv) == T  ! ubar_hadv, ... horizontal total advection
    Dout(M2xadv) == T  ! ubar_xadv, ... horizontal XI-advection
    Dout(M2yadv) == T  ! ubar_yadv, ... horizontal ETA-advection
    Dout(M2hrad) == T  ! ubar_hrad, ... horizontal total radiation stress
    Dout(M2hvis) == T  ! ubar_hvisc, ... horizontal total viscosity
    Dout(M2xvis) == T  ! ubar_xvisc, ... horizontal XI-viscosity
    Dout(M2yvis) == T  ! ubar_yvisc, ... horizontal ETA-viscosity
    Dout(M2sstr) == T  ! ubar_sstr, ... surface stress
    Dout(M2bstr) == T  ! ubar_bstr, ... bottom stress
  • Logical switches (TRUE/FALSE) to activate writing of time-averaged, 3D momentum (u,v) diagnostic terms into the diagnostics output file.
    Dout(M3rate) == T  ! u_accel, ... acceleration
    Dout(M3pgrd) == T  ! u_prsgrd, ... pressure gradient
    Dout(M3fcor) == T  ! u_cor, ... Coriolis force
    Dout(M3hadv) == T  ! u_hadv, ... horizontal total advection
    Dout(M3xadv) == T  ! u_xadv, ... horizontal XI-advection
    Dout(M3yadv) == T  ! u_yadv, ... horizontal ETA-advection
    Dout(M3vadv) == T  ! u_vadv, ... vertical advection
    Dout(M3hrad) == T  ! u_hrad, ... horizontal total radiation stress
    Dout(M3vrad) == T  ! u_vrad, ... vertical radiation stress
    Dout(M3hvis) == T  ! u_hvisc, ... horizontal total viscosity
    Dout(M3xvis) == T  ! u_xvisc, ... horizontal XI-viscosity
    Dout(M3yvis) == T  ! u_yvisc, ... horizontal ETA-viscosity
    Dout(M3vvis) == T  ! u_vvisc, ... vertical viscosity
  • Logical switches (TRUE/FALSE) to activate writing of time-averaged, active (temperature and salinity) and passive (inert) tracer diagnostic terms into the diagnostics output file. [1:NAT+NPT,1:Ngrids] values are expected.
    Dout(iTrate) == T T  ! temp_rate, ... time rate of change
    Dout(iThadv) == T T  ! temp_hadv, ... horizontal total advection
    Dout(iTxadv) == T T  ! temp_xadv, ... horizontal XI-advection
    Dout(iTyadv) == T T  ! temp_yadv, ... horizontal ETA-advection
    Dout(iTvadv) == T T  ! temp_vadv, ... vertical advection
    Dout(iThdif) == T T  ! temp_hdiff, ... horizontal total diffusion
    Dout(iTxdif) == T T  ! temp_xdiff, ... horizontal XI-diffusion
    Dout(iTydif) == T T  ! temp_ydiff, ... horizontal ETA-diffusion
    Dout(iTsdif) == T T  ! temp_sdiff, ... horizontal S-diffusion
    Dout(iTvdif) == T T  ! temp_vdiff, ... vertical diffusion

Generic User Parameters

  • NUSER is the number (integer) of user parameters to consider. USER is a vector containing NUSER user parameters (real array).
    NUSER = 0
    USER = 0.d0
    This array is primarily used with the SANITY_CHECK to test the correctness of the tangent linear adjoint models. It contains the model variable and grid point to perturb:
    ! INT(user(1)): tangent state variable to perturb
    ! INT(user(2)): adjoint state variable to perturb
    ! [ isFsur = 1 ] free-surface
    ! [ isUbar = 2 ] 2D U-momentum
    ! [ isVbar = 3 ] 2D V-momentum
    ! [ isUvel = 4 ] 3D U-momentum
    ! [ isVvel = 5 ] 3D V-momentum
    ! [ isTvar = 6 ] First tracer (temperature)
    ! [ ... ] ...
    ! [ isTvar = ? ] Last tracer
    !
    ! INT(user(3)): I-index of tangent variable to perturb
    ! INT(user(4)): I-index of adjoint variable to perturb
    ! INT(user(5)): J-index of tangent variable to perturb
    ! INT(user(6)): J-index of adjoint variable to perturb
    ! INT(user(7)): K-index of tangent variable to perturb, if 3D
    ! INT(user(8)): K-index of adjoint variable to perturb, if 3D
    Set tangent and adjoint parameters to the same values if perturbing and reporting the same variable.
  • This parameter could also be used to adjust constants in analytical functions at run time.


Parallel I/O (PIO and SCORPIO) Parameters

  • Choose the input and output NetCDF library to use. For example, the user could choose to use the PIO library for writing but still use the standard library for reading. To use this Parallel I/O strategy, the PIO or SCORPIO library must be linked to ROMS at compile time and the PIO_LIB CPP option needs to be activated. It is only available in distributed-memory applications since it uses MPI-IO.
    ! [1] Standard NetCDF-3 or NetCDF-4 library
    ! [2] Parallel-IO from PIO or SCORPIO library (MPI, MPI-IO applications)

    INP_LIB = 2
    OUT_LIB = 2
  • PIO and SCORPIO offer several methods for reading/writing NetCDF files. SCORPIO also offers ADIOS but that is not implemented in ROMS. Depending on the build of the PIO or SCORPIO libraries, not all the I/O types are available. If the NetCDF library does not support parallel I/O, methods 3 and 4 are not available. Currently, NetCDF4/HDF5 data compression is possible with method 3 during serial write.
    ! [0] parallel read and parallel write of PnetCDF (CDF-5 type files, not recommended because of post-processing)
    ! [1] parallel read and parallel write of NetCDF3 (64-bit offset)
    ! [2] serial read and serial write of NetCDF3 (64-bit offset)
    ! [3] parallel read and serial write of NetCDF4/HDF5
    ! [4] parallel read and parallel write of NETCDF4/HDF5

    PIO_METHOD = 2
  • Parallel-IO tasks control parameters. Typically, it is advantageous and highly recommended to define the I/O decomposition in smaller number of processes for efficiency and to avoid MPI communications bottlenecks.
    PIO_IOTASKS = 1  ! number of I/O processes to define
    PIO_STRIDE = 1  ! stride in the MPI-rank between I/O processes
    PIO_BASE = 0  ! offset for the first I/O process
    PIO_AGGREG = 1  ! number of MPI-aggregators to use
  • Parallel-IO (PIO or SCORPIO) rearranger methods for moving data between computational and I/O processes. It provides the ability to rearrange data between computational and parallel I/O decompositions. Usually the Box rearrangement is more efficient.
    ! [1] Box rearrangement
    ! [2] Subset rearrangement

    PIO_REARR = 1
    • In the box method, data is rearranged from computational to I/O processes in a continuous manner to the data ordering in the file. Since the ordering of data between computational and I/O partitions may be different, the rearrangement will require all-to-all MPI communications. Also, notice that each computing tile may transfer data to one or more I/O processes.
    • In the subset method, each I/O process is associated with a subset of computing processes. The computing tile sends its data to a unique I/O process. The data on I/O processes may be more fragmented to the ordering on disk, which may increase the communications to the storage medium. However, the rearrangement scales better since all-to-all MPI communications are not required.
  • Parallel-IO (PIO or SCORPIO) rearranger flag for MPI communication between computational and I/O processes. In some systems, the Point-to-Point communications is more efficient.
    ! [0] Point-to-Point communications
    ! [1] Collective communications

    PIO_REARRCOM = 0
  • Parallel-IO (PIO or SCORPIO) rearranger flow-control direction flag for MPI communications between computational and I/O processes. The flow algorithm controls the rate and volume of messages sent to any destination MPI process. Optimally, the MPI communications should be designed to send a modest number of messages evenly distributed across a number of processes. An excessive number of messages to a single MPI process can exhaust the buffer space which can affect efficiency or failure due to the slowdown in the retransmitting of dropped messages. It only sends messages (Isend) when the receiver is ready and has sufficient resources.
    ! [0] Enable computational to I/O processes, and vice versa
    ! [1] Enable computational to I/O processes only
    ! [2] Enable I/O to computational processes only
    ! [3] Disable flow control

    PIO_REARRDIR = 0
  • Parallel-IO (PIO or SCORPIO) rearranger options for MPI communications from computational to I/O processes (C2I).
    PIO_C2I_HS = T  ! Enable C2I handshake (T/F)
    PIO_C2I_Send = F  ! Enable C2I Isends (T/F)
    PIO_I2C_HS = 64  ! Maximum pending C2I requests
  • Parallel-IO (PIO or SCORPIO) rearranger options for MPI communications from I/O to computational processes (I2C).
    PIO_I2C_HS = F  ! Enable I2C handshake (T/F)
    PIO_I2C_Send = T  ! Enable I2C Isends (T/F)
    PIO_I2C_Preq = 65  ! Maximum pending I2C requests

NetCDF-4/HDF5 Compression Parameters

  • NetCDF-4/HDF5 compression parameters for output files. This capability is used when both HDF5 and DEFLATE C-preprocessing options are activated. The user needs to compile with the NetCDF-4/HDF5 and MPI libraries. File deflation cannot be used in parallel I/O for writing libraries. File deflation cannot be used in parallel I/O for writing to exactly map the data to the disk location. For more information, check NetCDF official website.
    NC_SHUFFLE = 1  ! if non-zero, turn on shuffle filter
    NC_DEFLATE = 1  ! if non-zero, turn on deflate filter
    NC_DLEVEL = 1  ! deflate level [0-9]

Input NetCDF Files

NoteNOTE: Starting with revision 460 file names can be up to 256 characters long. Previously only 80 characters were allowed.

  • Input NetCDF file names, [1:Ngrids] values are expected.
    GRDNAME == roms_grd.nc  ! Grid
    ININAME == roms_ini.nc  ! NLM initial conditions
    ITLNAME == roms_itl.nc  ! TLM initial conditions
    IRPNAME == roms_irp.nc  ! RPM initial conditions
    IADNAME == roms_iad.nc  ! ADM initial conditions
    FWDNAME == roms_fwd.nc  ! Forward trajectory
    ADSNAME == roms_ads.nc  ! Adjoint sensitivity functionals
  • Input adjoint forcing NetCDF filenames for computing observations impacts during the analysis-forecast cycle. If the forecast error metric is defined in state-space, then FOInameA and FOInameB should be regular adjoint forcing files just like ADSNAME. If the forecast error metric is defined in observation space (OBS_SPACE is activated) then the forecast is initialized OIFnameA and OIFnameB (specified in s4dvar.in input script) will have the structure of a 4D-Var observation file.
    FOInameA == roms_foi_a.nc
    FOInameB == roms_foi_b.nc
  • Input NetCDF filenames for the forecasts initialized from the analysis of the current 4D-Var cycle (FCTnameA) and initialized from the analysis of the previous 4D-Var cycle (FCTnameB).
    FCTnameA == roms_fct_a.nc
    FCTnameB == roms_fct_b.nc
  • Nesting grids connectivity data: contact points information. This NetCDF file is special and complex. It is currently generated using the script matlab/grid/contact.m from the Matlab repository.
    NGCNAME = roms_ngc.nc
  • Input lateral boundary conditions and climatology file names. The user has the option to split input data time records into several NetCDF files (see the File Syntax Notes). If so, use a single line per entry with a vertical bar (|) symbol after each entry, except the last one.
    BRYNAME == roms_bry.nc  ! Open boundary conditions
    CLMNAME == roms_clm.nc  ! Climatology
  • Input climatology nudging coefficients file name.
    NUDNAME == roms_nud.nc
  • Input Sources/Sinks forcing (like river runoff) file name. This file is separated from the regular forcing files to allow manipulations over nested grids. A particular nesting grid may or may not have Sources/Sinks forcing.
    SSFNAME == roms_rivers.nc
  • Input tidal forcing file name.
    TIDENAME == roms_tides.nc
  • Input forcing NetCDF file name(s). The user has the option to enter several files names for each nested grid. For example, the user may have a different files for wind products, heat fluxes, tides, etc. The model will scan the file list and will read the needed data from the first file in the list containing the forcing field. Therefore, the order of the file names is very important. If multiple forcing files per grid, enter first all the file names for grid 1, then grid 2, and so on. It is also possible to split input data time records into several NetCDF files (see the File Syntax Notes). Use a single line per entry with a continuation ( \ ) or vertical bar ( | ) symbol after each entry, except the last one.
    NFFILES == 1  ! number of unique forcing files

    FRCNAME == roms_frc.nc  ! forcing file 1, grid 1

Output NetCDF Files

NoteNOTE: Starting with revision 460 file names can be up to 256 characters long. Previously only 80 characters were allowed.

  • Output NetCDF file names, [1:Ngrids] files are expected.
    DAINAME == roms_dai.nc  ! Data assimilation next cycle initial conditions or restart file
    GSTNAME == roms_gst.nc  ! GST analysis restart
    RSTNAME == roms_rst.nc  ! Restart
    HISNAME == roms_his.nc  ! History
    QCKNAME == roms_qck.nc  ! Quicksave
    TLMNAME == roms_tlm.nc  ! TLM history
    TLFNAME == roms_tlf.nc  ! Impulse TLM forcing
    ADJNAME == roms_adj.nc  ! ADM history
    AVGNAME == roms_avg.nc  ! Averages
    HARNAME == roms_har.nc  ! least-squares detiding harmonics
    DIANAME == roms_dia.nc  ! Diagnostics
    STANAME == roms_sta.nc  ! Stations
    FLTNAME == roms_flt.nc  ! Floats

Additional Input Scripts

NoteNOTE: Starting with revision 460 file names can be up to 256 characters long. Previously only 80 characters were allowed.