ROMS 3.3 Released

ROMS Code Release Announcements

Moderators: arango, robertson

Post Reply
Message
Author
User avatar
arango
Site Admin
Posts: 1347
Joined: Wed Feb 26, 2003 4:41 pm
Location: DMCS, Rutgers University
Contact:

ROMS 3.3 Released

#1 Unread post by arango »

ROMS/TOMS 3.3 Released

The latest version of the :arrow: ROMS/TOMS svn repository, revision 432, was frozen and tagged as ROMS 3.3. This version is quite stable and includes a major overhaul of all 4D-Var data assimilation algorithms. The major developments and improvements are summarized below. Additional detailed information can be found in the ROMS repository :arrow: trac ticket system. Please check the upgrade type tickets.

Many thanks to Andy Moore for his great help in development and testing of all the 4D-Var data assimilation algorithms. Also many thanks to Gregoire Broquet and Brian Powell for their help in testing the countless modifications to these algorithms. We started the overhaul of these algorithms about a year ago and we are very happy with the results. To our knowledge, ROMS is the only open-source, ocean community modeling framework supporting both strong and weak constraint variational data assimilation and other sophisticated adjoint-based algorithms.

What is New:
  • A major overhaul of the 4-Dimensional Variational (4D-Var) data assimilation algorithms. ROMS uniquely supports three different 4D-Var methodologies: incremental strong constraint 4D-Var (I4D-Var), a physical-space statistical analysis system (4D-PSAS), and a representer-based 4D-VAR (R4D-Var). The 4D-PSAS and R4D-Var algorithms can be configured as strong constraint (dynamical model is error free) or weak constraint (errors are admitted in dynamical model). All these algorithms are fully working, parallel and affordable.

    Code: Select all

    Driver              CPP Option           Description
    ------              ----------           -----------
    
    is4dvar_ocean.h     IS4DVAR              Incremental, strong constraint I4D-Var assimilation
    w4dpsas_ocean.h     W4DPSAS              Weak constraint 4D-PSAS assimilation
    w4dvar_ocean.h      W4DVAR               Weak constraint, representer-based R4D-Var assimilation
    
  • The best estimate of the ocean circulation between model and observations from the 4D-Var algorithms takes into account the errors in the initial conditions (default), boundary conditions (ADJUST_BOUNDARY, :arrow: check details), surface forcing (ADJUST_WSTRESS, ADJUST_STFLUX), and in some cases the model itself (W4DPSAS, W4DVAR).
  • All critical components common to each 4D-Var approach including the conjugate gradient, preconditioning, and error covariance modeling were greatly improved. The conjugate gradient was completely rewritten for all three 4D-Var algorithms. It is now based on the Lanczos method, as described in Fisher (1998). Two versions of Limited Memory Preconditioners (LMP) are available. These are the spectral preconditioner as described in Fisher (1998), and the Ritz preconditioner as described in Tshimanga et al. (2008). The technical description of these algorithms and how to use them is documented in the :arrow: ROMS wiki.
  • The error covariance modeling was enhanced by imposing a multivariate constraint via the balance operator (BALANCE_OPERATOR, :arrow: check details), as reported in Weaver et al. (2005). The state vector is split between balanced and unbalanced components, except for temperature, which is used to establish the balanced part of the other state variables. This allows extracting information about the unobserved variables from the observed data. Please check following :arrow: trac ticket for information about the level of no motion when computing the balanced free-surface contribution.
  • New algorithms were developed to estimate the posterior error or confidence (POSTERIOR_ERROR_I, POSTERIOR_ERROR_F, POSTERIOR_EOFS) in the resulting circulation estimates. Plase check the following :arrow: trac ticket for more details.
  • The adjoint of the 4D-PSAS and R4D-Var data assimilation systems where developed to quantify the observations sensitivity (W4DPSAS_SENSITIVITY, W4DVAR_SENSITIVITY, :arrow: check details) and the observations impact (OBS_IMPACT, :arrow: check details). The observation impact operator can be split further (OBS_IMPACT_SPLIT, :arrow: check details) to compute the contributions due to initial conditions, surface forcing, and boundary conditions. By measuring the sensitivity of the data assimilation to each observation, and quantifying the impact of each observation on the forecast analysis increment, we can determine the degree to which observations contribute to the uncertainty in the circulation estimate. These analyses can be used in adaptive sampling, quality control, and observation system design to determine the type of measurements that need to be made, where to observe, and when.

    Code: Select all

    Driver              CPP Option           Description
    ------              ----------           -----------
    
    obs_sen_is4dvar.h   IS4DVAR_SENSITIVITY  I4D-Var observation sensitivity
    obs_sen_w4dpsas.h   W4DPSAS_SENSITIVITY  4D-PSAS observation sensitivity
    obs_sen_w4dvar.h    W4DVAR_SENSITIVITY   R4D-Var observation sensitivity
  • Re-designed the biology/ecosystem model interface to allow flexibility and customization. For more details check the following :arrow: ticket and :arrow: here. Note that all the include files (*.h) below are located in ROMS/Nonlinear/Biology and included within <...> to allow the user to customize any of them in the project directory while keeping the distributed code intact (check the build script for details). Each ecosystem model is composed of seven files:
    1. Model source and sink discretized equations which are included in ROMS/Nonlinear/Biology/biology.F:
      • ecosim.h, (ECOSIM)
      • fennel.h, (BIO_FENNEL)
      • nemuro.h, (NEMURO)
      • npzd_Franks.h, (NPZD_FRANKS)
      • npzd_iron.h, (NPZD_IRON)
      • npzd_Powell.h, (NPZD_POWELL)
    2. Internal model parameters declaration which is included in ROMS/Modules/mod_biology.F:
      • ecosim_mod.h
      • fennel_mod.h
      • nemuro_mod.h
      • npzd_Franks_mod.h
      • npzd_iron_mod.h
      • npzd_Powell_mod.h
    3. Model parameters standard input script which can be found in ROMS/External or User/External sub-directories:
      • ecosim.in
      • bio_Fennel.in
      • nemuro.in
      • npzd_Franks.in
      • npzd_iron.in
      • npzd_Powell.in
    4. Code to read input model parameters which is included in ROMS/Utility/inp_par.F:
      • ecosim_inp.h
      • fennel_inp.h
      • nemuro_inp.h
      • npzd_Franks_inp.h
      • npzd_iron_inp.h
      • npzd_Powell_inp.h
    5. Code to assign indices to model variables during the reading of metadata information from varinfo.dat and included in ROMS/Modules/mod_ncparm.F:
      • ecosim_var.h
      • fennel_var.h
      • nemuro_var.h
      • npzd_Franks_var.h
      • npzd_iron_var.h
      • npzd_Powell_var.h
    6. Code to define input model parameters in all output NetCDF files which is included in ROMS/Utility/def_info.F:
      • ecosim_def.h
      • fennel_def.h
      • nemuro_def.h
      • npzd_Franks_def.h
      • npzd_iron_def.h
      • npzd_Powell_def.h
    7. Code to write out input model parameters in all output NetCDF files which is included in ROMS/Utility/wrt_info:
      • ecosim_wrt.h
      • fennel_wrt.h
      • nemuro_wrt.h
      • npzd_Franks_wrt.h
      • npzd_iron_wrt.h
      • npzd_Powell_wrt.h
  • Similarly, the sediment model was re-designed to isolate all the required routines and include files in the ROMS/Nonlinear/Sediment directory. All the sediment model kernel variable declarations were moved from mod_average.F, mod_grid.F, and mod_ocean.F to a new module mod_sedbed.F. This new module includes the file sedbed_mod.h to facilitate customization. As in the ecosystem models above, you will find the following included files: sediment_mod.h, sediment_inp.h, sediment_var.h, sediment_def.h, and sediment_wrt.h. For more details check the following :arrow: ticket and :arrow: here.
  • The light attenuation formulation for photosynthesis (PAR) in a couple of the biology models in ROMS were revisited. We are now using the averaged (finite volume) value of PAR at the center of the grid cell instead of the median value. It turns out that the old formulation underestimates primary productivity. See the following forum :arrow: post and trac :arrow: ticket for details.
  • Added new NPZD model with iron limitation (Fiechter et al., 2009). This model is similar to the Powell et al. (2006) formulation but it includes iron limitation on phytoplankton growth (:arrow: check details). This new model is activated with the NPZD_IRON option. To activate the iron limitation on phytoplankton growth, also use the IRON_LIMIT option. In addition, use IRON_RELAX to simulate the sources of dissolved iron in coastal areas where the bathymetry h(i,j) <= FeHmin (See input script npzd_iron.in for details). This new NPZD model (npzd_iron.h) also has a tangent linear, representer, and adjoint model version. Many thanks to Jerome Fiechter and Andy Moore for their help developing and testing this new model.
  • Implemented a new option, CLIMA_TS_MIX, to diffuse tracer perturbation (t-tclm) instead of the tracer (t) field alone (See :arrow: ticket). This option can be used in some applications to reduce the numerical diapycnal mixing of tracer in deep waters. This strategy has been used extensively in other models. For example, see Mellor and Blumberg, 1985.
  • The makefile was :arrow: updated so the COMPILERS definition may be specified in either the build.sh or build.bash scripts. This allows the user to specify a customized version (different path) of the configuration files (*.mk) that are distributed in Compilers subdirectory. The makefile now has the following statement to facilitate such an operation:

    Code: Select all

      COMPILERS ?= $(CURDIR)/Compilers
    
    MAKE_MACROS := $(shell echo ${HOME} | sed 's| |\\ |g')/make_macros.mk
    so we can set the COMPILERS definition with an environment variable in build.sh:

    Code: Select all

     setenv COMPILERS            ${MY_ROMS_SRC}/Compilers
    or you may use a copy of Linux-ifort.mk, for example, in your project directory:

    Code: Select all

     setenv COMPILERS            ${MY_PROJECT_DIR}
    If you are using this strategy, make sure that you keep the make configuration scripts up-to-date. Notice that the temporary make_macros.mk file is now created in the users HOME directory to allow compiling a source code owned by a different user on the same computer system.
  • Added new horizontal mixing parameters for adjoint-based applications: ad_TNU2, ad_TNU4, ad_VISC2, and ad_VISC4. These parameters can be set to a different values than those used in the nonlinear model. In some applications, other values are needed for stability of the tangent linear, representer, and adjoint models. Also this can be used when the advection scheme in the adjoint-based algorithms is different than the nonlinear model basic state trajectory.

    Code: Select all

    ! Harmonic/biharmonic horizontal diffusion of tracer for nonlinear model
    ! and adjoint-based algorithms: [1:NAT+NPT,Ngrids].
    
            TNU2 ==  0.0d0   0.0d0                  ! m2/s
            TNU4 ==  0.0d0   0.0d0                  ! m4/s
    
         ad_TNU2 == 50.0d0  50.0d0                  ! m2/s
         ad_TNU4 == 2.0d+10 2.00d+10                ! m4/s
    
    ! Harmononic/biharmonic, horizontal viscosity coefficient for nonlinear model
    ! and adjoint-based algorithms: [Ngrids].
    
           VISC2 == 0.0d0                           ! m2/s
           VISC4 == 0.0d0                           ! m4/s
    
        ad_VISC2 == 50.0d0                          ! m2/s
        ad_VISC4 == 2.0d+10                         ! m4/s
  • A new routine ini_hmixing.F is introduced to initialize the horizontal mixing array (diff2, diff4, visc2_p, visc2_r, visc4_p, visc4_r) for the nonlinear, tangent linear, representer and adjoint models. This change is backward compatible and you do not have to modify your horizontal mixing strategies, like sponges and so on. This routine also sets the current value of horizontal mixing constants tnu2, tnu4, visc2, and visc4 from provided input values (nl_tnu2, ad_tnu2, or tl_tnu2, etc).
  • Added new parameters ad_AKT_fac and ad_AKV_fac to scale (if so desired, default value is 1.0) the basic state vertical mixing coefficients (Akt and Akv arrays) in adjoint-based applications when the C-preprocessing option FORWARD_MIXING is activated. In some applications, smaller/larger values of vertical mixing are necessary for stability. The same scale value is used in the tangent linear, representer and adjoint model for symmetry considerations.
  • Added new logical switch LtracerSrc to specify which tracer variables to consider when the C-preprocessing option TS_PSOURCE is activated.

    Code: Select all

    ! Logical switches (TRUE/FALSE) to specify which variables to consider on
    ! tracers point Sources/Sinks (like river runoff): [1:NAT+NPT,Ngrids].
    ! See glossary below for details.
    
      LtracerSrc == T T                        ! temperature, salinity, inert
    This changes affects all ROMS input scripts: ocean.in, bio_Fennel.in, ecosim.in, nemuro.in, npzd_Franks.in, npzd_Powell.in, npzd_iron.in, and sediment.in. The changes are simple and backward compatible. :idea: WARNING: the point sources (TS_PSOURCE) of tracers are modified as follows in ocean.in:

    Code: Select all

    !  LtracerSrc  Logical switches (T/F) to specify which tracer variables
    !              to consider when the option TS_PSOURCE is activated. Only
    !              NAT active tracers (temperature, salinity) and NPT inert
    !              tracers need to be specified here:
    !
    !                LtracerSrc(itemp,ng)     for temperature (itemp=1)
    !                LtracerSrc(isalt,ng)     for salinity    (isalt=2)
    !                LtracerSrc(NAT+1,ng)     for inert tracer 1
    !                ...                      ...
    !                LtracerSrc(:,NAT+NPT)    for inert tracer NPT
    !
    !              Other biological and sediment tracers switches are specified in
    !              their respective input scrips.
    !
    !              Recall that TS_PSOURCE is usually activated to add river runoff
    !              as a point source. At minimum, it is necessary to specify both
    !              temperature and salinity for all rivers.  The other tracers are
    !              optional.
    !
    !              This logical switch REPLACES and ELIMINATES the need to have
    !              or read the variable "river_flag(river)" in the input rivers
    !              forcing NetCDF file:
    !
    !                double river_flag(river)
    !                        river_flag:long_name = "river runoff tracer flag"
    !                        river_flag:option_0 = "all tracers are off"
    !                        river_flag:option_1 = "only temperature"
    !                        river_flag:option_2 = "only salinity"
    !                        river_flag:option_3 = "both temperature and salinity"
    !                        river_flag:units = "nondimensional"
    !
    !              This logic was too cumbersome and complicated when additional
    !              tracers are considered. However, this change is backward
    !              compatible.
    !
    !              The LtracerSrc switch will be used to activate the reading of
    !              respective tracer variable from input river forcing NetCDF
    !              file. If you want to add other tracer variables (other than
    !              temperature and salinity) as a source for a particular river(s),
    !              you just need to specify such values on those river(s). Then,
    !              set the values to ZERO on the other river(s) that do NOT
    !              require such river forcing for that tracer. Recall that you
    !              need to specify the tracer values for all rivers, even if
    !              their values are zero.
    Please check any of the biological and sediment model input scripts for more details. The old logic was too cumbersome and complicated :shock: Notice that a lot of files were changed. Notice that ana_psource.h was updated and no longer has the Lsrc argument.
  • Removed the override of barotropic, time filtering arrays DU_avg1 and DV_avg1 in routine step2d, when the point sources (river runoff) option UV_PSOURCE is activated. This was completely unnecessary and redundant. The algorithm takes care of this when computing the local transports DUon and DVom. At the point sources locations, the value of DU_avg1 or DV_avg1 is exactly the same as Qbar.
  • Added code in the NetCDF input routines to process the add_offset attribute, if present in an input NetCDF variable. This implies that users need to be careful when including such an attribute in a NetCDF variable. If the add_offset attribute is present for a variable, its numeric value is added to the data after is read by ROMS I/O interface. In some applications, the add_offset is used to provide simple data compression. Also, it can be used to change units. For example, we can convert temperature from Kelvin to Celsius:

    Code: Select all

            float Tair(time, eta_rho, xi_rho) ;
                    Tair:long_name = "surface air temperature" ;
                    Tair:units = "Celsius" ;
                    Tair:add_offset = -273.16;
                    Tair:time = "time" ;
    Here the original data is actually in Kelvin, so a value of -273.16 is added to the data to convert it to Celsius.
  • Also, the scale_factor attribute in NetCDF files is processed. In summary, all the NetCDF data input routines will check if any of the following attributes: scale_factor, add_offset, or _FillValue are present in the input NetCDF variable:
    • If the scale_value attribute is present, the data is multiplied by this factor after reading.
    • If the add_offset attribute is present, this value is added to the data after reading.
    • If both scale_factor and add_offset attributes are present, the data are first scaled before the offset is added. They are usually used for simple data compression.
    • If the _FillValue attribute is present, the data having this value is treated as missing and it is replaced with zero. This feature it is usually related with the land/sea masking.
    Notice that the NetCDF attribute convention stipulates:
    When scale_factor and add_offset are used for packing, the associated variable (containing the packed data) is typically of type byte or short, whereas the unpacked values are intended to be of type float or double. The attributes scale_factor and add_offset should both be of the type intended for the unpacked data, e.g. float or double
    On the other hand, the _FillValue must be of the same type as the NetCDF variable.
  • Updated the Model Coupling Toolkit (MCT) library to its latest version 2.6.0 which was :arrow: released on April 30, 2009.
  • Several bugs and typos were corrected. I highly recommend that users keep their ROMS version up to date. I am always surprised when users are still using deprecated version of the code :?
Good luck with the new version ...
Happy Holidays 8)

Post Reply