ROMS/TOMS Developers

Algorithms Update Web Log
Next Page »

arango - March 22, 2007 @ 23:51
Redesigned User interface- Comments (0)

I merged my svn branch with the official distribution trunk. This merge includes many updates in preparation to the major release of ROMS 3.0. John Warner, Kate and I have been working on the new version for awhile. We are almost there.

We completely redesigned the user interface so the number of files to modify by the user are mainly the makefile and the application header file.

  • The user no longer needs to modify cppdefs.h. This file is still used during compilation. It will be modified only by the developers when adding documentation for a new CPP option. This is the only file that contains the list of all CPP options available in ROMS. The application CPP option to run is now specified in the makefile:
    #  The CPP option defining a particular application is specified below.
    #  See header file ROMS/Include/cppdefs.h for all available idealized
    #  and realistic applications CPP flags. For example, to activate the
    #  upwelling test case (UPWELLING) set:
    #  Notice that this makefile will include the associated application header
    #  file, which is located either in the ROMS/Include or MY_HEADER_DIR
    #  directory.  This makefile is designed to search in both directories.
    #  The only constrain is that the application CPP option must be unique
    #  and header file name is the lowercase value of ROMS_APPLICATION with
    #  the .h extension. For example, the upwelling application includes the
    #  upwelling.h header file.
  • Notice that cppdefs.h contains now the following directive to include the appropriate application header file:
    #if defined ROMS_HEADER
    # include ROMS_HEADER
      CPPDEFS - Choose an appropriate ROMS application.

    The macro ROMS_HEADER is assigned in the makefile as:

      HEADER := $(addsuffix .h,$(shell echo ${ROMS_APPLICATION} | tr [A-Z] [a-z]))
      CPPFLAGS += -DNestedGrids=$(NestedGrids)
  • The code structure was redesigned so regular users do not need to chance any of the files inside the ROMS sub-directories. A new User directory contains templates for standard input scripts (User/External), analytical expressions (User/Functionals), and application CPP options (User/Include). The user has the choice of putting his/her application in these new sub-directories or somewhere else. The user needs to provide the location of application header file and analytical header files, if any, in the makefile:
    #  If application header file is not located in ROMS/Include,
    #  provide an alternate directory.
    #  If your application requires analytical expressions and they are not
    #  located in ROMS/Functionals, provide an alternate directory.
    #  Notice that a set analytical expressions templates can be found in
    #  User/Functionals.

    Notice that the makefile includes both MY_ANALYTICAL_DIR (if not empty) and ROMS/Functionals in the CPP search path. For example, if the user activates ANA_INITIAL and ana_initial.h is not located in MY_ANALYTICAL_DIR it will use the default file located in ROMS/Functionals. This strategy allows the user to share his/her applicatication with other by just providing configuration and input files. There is not need to provide the internal ROMS source code.

  • Recall that all macros defined with ?= will use the value from the enviromental variable, if available. This is very convinient when writing running scripts.
  • As I mentioned above, the user no longer needs to modify mod_param.F to specify the grid dimension parameters for a particular application. These parameters are now specified in standard input file Pretty neat, right? This is all possible because the model uses dynamical allocation for all model variables. For example, the input script which is use in the UPWELLING application now includes the following parameters:
    ! Application title.
           TITLE = Wind-Driven Upwelling/Downwelling over a Periodic Channel
    ! C-preprocessing Flag.
        MyAppCPP = UPWELLING
    ! Input variable information file name.  This file needs to be processed
    ! first so all information arrays can be initialized properly.
         VARNAME = ROMS/External/varinfo.dat
    ! Grid dimension parameters. See notes below in the Glossary for how to set
    ! these parameters correctly.
              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

    Notice that in idealized applications with not input NetCDF files, the user can change the dimensions of the problem without a need to recompile. Of course, the analytical expressions need to be generic to support those changes.

    The Ngrids parameter is special and cannot be specified in the input script since it is used to allocate all the model pointer structures. This parameter is now specified in the makefile in macro NestedGrids and assigned in mod_param.F during c-preprocessing (see CPPFLAGS macro above):

    #  Set number of ROMS nested and/or composed grid.  Currently, only
    #  one grid is supported.  This option will be available in the near
    #  future.
     NestedGrids := 1
  • Notice that the input script has now the parameter MyAppCPP which is used in file checkdefs.F to report the application CPP option and title:
          IF (Master) THEN
            WRITE (stdout,20) TRIM(ADJUSTL(MyAppCPP)), TRIM(ADJUSTL(title))
          END IF

    Therefore, the user no longer needs to modify checkdefs.F. In the past, this was very important because it was the only mechanism that we had to check that only one application was activated.

  • The analytical.F file was moved to new directory ROMS/Functionals and splitted into several header files:
       arango % cd ROMS/Functionals/
       arango % ls
       ana_biology.h   ana_humid.h    ana_nudgcoef.h  ana_smflux.h    ana_tair.h
       ana_bmflux.h    ana_initial.h  ana_pair.h      ana_specir.h    ana_tclima.h
       ana_btflux.h    analytical.F   ana_passive.h   ana_spinning.h  ana_tobc.h
       ana_cloud.h     ana_m2clima.h  ana_perturb.h   ana_srflux.h    ana_vmix.h
       ana_diag.h      ana_m2obc.h    ana_psource.h   ana_ssh.h       ana_winds.h
       ana_fsobc.h     ana_m3clima.h  ana_rain.h      ana_sss.h       ana_wwave.h
       ana_grid.h      ana_m3obc.h    ana_scope.h     ana_sst.h
       ana_hmixcoef.h  ana_mask.h     ana_sediment.h  ana_stflux.h

    This file was too large and difficult to edit. This was long overdue. A template of all these files is provided in the User/Functionals directory for the user to adapt for his/her application, if appropriate.

arango - February 19, 2007 @ 21:43
Alternate Application CPP definition- Comments (0)

The CPP option defining a particular application can now be specified in either header file cppdefs.h or the makefile. If defined in the makefile, all the applications definition in cppdefs.h must be commented out with an ! (exclamation mark) in column 1. For example, to activate the upwelling application (UPWELLING) in the makefile, set:


Otherwise, leave the ROMS_APPLICATION macro blank


and uncomment the appropriate application in cppdefs.h.

!#define A4DVAR_TOY      /* for 4DVAR Data Assimilation Toy */
!#define BASIN           /* for Big Bad Basin Example */
!#define BENCHMARK1      /* for Small Benchmark Test */
!#define BENCHMARK2      /* for Medium Benchmark Test */
!#define BENCHMARK3      /* for Big Benchmark Test */
!#define BIO_TOY         /* for One-dimension (vertical) Biology Toy */
!#define BL_TEST         /* for Boundary Layers Test */
!#define CANYON_A        /* for Canyon_A Example */
!#define CANYON_B        /* for Canyon_B Example */
!#define CHANNEL_NECK    /* Channel with a Constriction */
!#define COUPLING_TEST   /* for two-way atmosphere-ocean coupling test */
!#define DOUBLE_GYRE     /* for idealized double-gyre Example */
!#define ESTUARY_TEST    /* test estuary for sediment*/
!#define FLT_TEST        /* for Float Tracking Example */
!#define GRAV_ADJ        /* for Graviational Adjustment Example */
!#define INNER_PRODUCT   /* Tangent/Adjoint State Matrix Inner Product Test */
!#define KELVIN          /* for Kelvin wave test */
!#define LAB_CANYON      /* for Lab Canyon, Polar Coordinates Example */
!#define LAKE_SIGNELL    /* for Lake Signell Sediment Test Case */
!#define LMD_TEST        /* Test for LMD and KPP */
!#define OVERFLOW        /* for Graviational/Overflow Example */
!#define RIVERPLUME1     /* for River plume Example 1 */
!#define RIVERPLUME2     /* for River plume Example 2 (Hyatt and Signell) */
!#define OPT_PERT2D      /* Optimal Perturbation 2D Test */
!#define OPT_PERT3D      /* Optimal Perturbation 3D Test */
!#define SEAMOUNT        /* for Seamount Example */
!#define SED_TEST1       /* for Suspended Sediment Test in a Channel */
!#define SED_TOY         /* for One-dimension (vertical) Sediment Toy */
!#define SOLITON         /* for Equatorial Rossby Wave Example */
#define UPWELLING        /* for Upwelling Example */
!#define USWEST          /* for US West Coast Application */
!#define WEDDELL         /* for Idealized Weddell Sea Shelf Application */
!#define WINDBASIN       /* linear wind-driven constant Coriolis basin */

Some users may prefer to specify the application in the makefile and never to change header file cppdefs.h. Recall that now there is a specific header file for each application (see this post).

For the current updated file list .

arango - February 6, 2007 @ 18:23
New version, copyright, and license- Comments (1)

We started the process of releasing the long awaited ROMS/TOMS new version:

  • We have been working on the copyright and other legal aspects of ROMS/TOMS for awhile. The new version will now be distributed with the following copyright:

    Copyright (c) 2002-2007 The ROMS/TOMS Group
    Licensed under a MIT/X style license
    See License_ROMS.txt

    Many thanks to Chris Sherwood and Rich Signell (USGS) for their help with the copyright and open source license.

  • ROMS/TOMS will be distributed primarily using subversion version control (svn). In the future the user will be able to download the latest version of the model and/or frozen version(s) from our new server by just typing a single UNIX command, like:

    svn checkout MyLocalDir

    or using any GUI interface like esvn (Unix), RapidSVN (cross-platform) or TortoiseSVN (Windows).

    The ROMS svn project managment and bug/issue tracking system is:

    The new ROMS sever hosting will be open to the community in few days. We are currently migrating all services and testing. The new server is a Linux quad completely dedicated to ROMS business: web sites, svn and trac, wikiROMS, developers blog, and forum.

  • All files were modified to include the copyright and license notice. I also added the svn keyword id. For example, get_state.F looks like:
    #include "cppdefs.h"
          SUBROUTINE get_state (ng, model, msg, ncname, IniRec, Tindex)
    !svn $Id: get_state.F 8 2007-02-06 19:00:29Z arango $
    !================================================== Hernan G. Arango ===
    !  Copyright (c) 2002-2007 The ROMS/TOMS Group                         !
    !    Licensed under a MIT/X style license                              !
    !    See License_ROMS.txt                                              !
    !                                                                      !
    !  This routine reads in requested model state from specified NetCDF   !
    !  file. It is usually used to read initial conditions.                !
    !                                                                      !
    !  On Input:                                                           !
    !                                                                      !
    !     ng         Nested grid number.                                   !
    !     model      Calling model identifier.                             !
    !     msg        Message index for Mstate.                             !
    !     ncname     Nonlinear initial conditions NetCDF file name.        !
    !     IniRec     Nonlinear initial conditions time record to read.     !
    !     Tindex     State variable time index to intialize.               !
    !                                                                      !
  • Converted distribute.F into a module to allow module procedure interface to distinguish scalar and vector operations:
         INTERFACE mp_bcastf
            MODULE PROCEDURE mp_bcastf_s
            MODULE PROCEDURE mp_bcastf_v
          END INTERFACE mp_bcastf

    This fixes a problem with Absoft Pro Fortran10 compilers. Many thanks to Brian Powell for reporting this.

  • Fixed few bugs in several drivers that have risen during the compilation of all of then.
  • This new version was committed into svn and frozen as ROMS/TOMS 2.3 in the tags directory. The Version file is:
    ROMS/TOMS Framework:  February 6, 2007
    Copyright (c) 2002-2007 The ROMS/TOMS Group
      Licensed under a MIT/X style license
      See License_ROMS.txt
    svn: $LastChangedBy: arango $
    svn: $LastChangedRevision: 8 $
    svn: $LastChangedDate: 2007-02-06 14:00:29 -0500 (Tue, 06 Feb 2007) $
    svn: $Id: Version 8 2007-02-06 19:00:29Z arango $
For the current updated file list .

arango - January 20, 2007 @ 18:31
Various Updates- Comments (0)

I introduced the following updates to the code:

  • Add new time-averaged quantities which are needed to compute eddy fluxes. For example, the tracer eddy flux is:

    <H u T / n> = <H u / n> <T> + <H’ u’ t’ / n>
    <H v T / m> = <H v / m> <T> + <H’ v’ t’ / m>

    we are interested in the last term which can be computed as:

    <H’ u’ t’ / n> = <H u / n> – <H u T / n> <T>
    <H’ v’ t’ / m> = <H v / m> – <H v T / m> <T>

    where the quantities inside <…> indicate time-averaged. In model variables, the tracer eddy flux is:

    <H’ u’ t’ / n> = <Huon*t> – <Huon> <t>
    <H’ v’ t’ / m> = <Hvom*t> – <Hvom> <t>

    all the three time-averaged quantities in the right-hand-size are now saved in the averages NetCDF file and can be activated with cpp option AVERAGES_QUADRATIC. Many thanks to John Wilkin for helping us to implement this option.

  • Modified cppdefs.h in such a way that each application has it own cpp definitions include file:
    **  Include the appropriate header file for IDEALIZED APPLICATION.
    #if defined A4DVAR_TOY
    # include "a4dvar_toy.h"
    #elif defined BASIN
    # include "basin.h"
    #elif defined BENCHMARK1 || defined BENCHMARK2 || defined BENCHMARK3
    # include "benchmark.h"
    #elif defined  BIO_TOY
    # include "bio_toy.h"
    #elif defined BL_TEST
    # include "bl_test.h"
    #elif defined CANYON_A || defined CANYON_B
    # include "canyon.h"
    #elif defined CHANNEL_NECK
    # include "channel_neck.h"
    #elif defined COUPLING_TEST
    # include "coupling_test.h"
    #elif defined DOUBLE_GYRE
    # include "double_gyre.h"
    #elif defined ESTUARY_TEST
    # include "estuary_test.h"
    #elif defined FLT_TEST
    # include "flt_test.h"
    #elif defined GRAV_ADJ
    # include "grav_adj.h"
    #elif defined INNER_PRODUCT
    # include "inner_product.h"
    #elif defined KELVIN
    # include "kelvin.h"
    #elif defined LAB_CANYON
    # include "lab_canyon.h"
    #elif defined LAKE_SIGNELL
    # include "lake_signell.h"
    #elif defined LMD_TEST
    # include "lmd_test.h"
    #elif defined OVERFLOW
    # include "overflow.h"
    #elif defined RIVERPLUME1 || defined RIVERPLUME2
    # include "riverplume.h"
    #elif defined SEAMOUNT
    # include "seamount.h"
    #elif defined SED_TEST1
    # include "sed_test.h"
    #elif defined SED_TOY
    # include "sed_toy.h"
    #elif defined SOLITON
    # include "soliton.h"
    #elif defined UPWELLING
    # include "upwelling.h"
    #elif defined WEDDELL
    # include "weddell.h"
    #elif defined WINDBASIN
    # include "windbasin.h"
    **  Include the appropriate header file for REALISTIC APPLICATION.
    #elif defined ADRIA02
    # include "adriatic.h"
    #elif defined CBLAST
    # include "cblast.h"
    #elif defined DAMEE_4
    # include "damee.h"
    #elif defined EAC_4 || defined EAC_8
    # include "eac.h"
    #elif defined IAS
    # include "ias.h"
    #elif defined NATL
    # include "natl.h"
    #elif defined NENA
    # include "nena.h"
    #elif defined NJ_BIGHT
    # include "nj_bight.h"
    #elif defined NPACIFIC
    # include "npacific.h"
    #elif defined SCB
    # include "scb.h"
    #elif defined SW06_COARSE || defined SW06_FINE
    # include "sw06.h"
    #elif defined USWEST
    # include "uswest.h"
      CPPDEFS - Choose an appropriate ROMS application.

    This new design is cleaner since cppdefs.h was getting very big. I have noticed that users like to put a lot of comments in their file to document their application. The user needs now to activate the appropriate application option in cppdefs.h (for example, #define UPWELLING) and make the appropriate changes to its respective definitions file (upwelling.h). All the include files are located in the Include sub-directory. The user needs to create an include file for each different application. I wanted to do this for very long time. The feedback that I got from several of you about this was very positive.

  • Several of you have been requesting for a perfect restart option in ROMS. I started coding this option. A perfect restart option is provided for the basic kernel. It can be activated with cpp option PERFECT_RESTART. This option is still under testing. I have tested this option with the upwelling example. It is run for 20 time-steps. The perfect restart fields are written at time-step 10. The RMS errors at time-step 20 between restarted and control run are:
                              RMS               RMS               RMS
       zeta              2.73101330e-06    2.73138360e-06    2.73142573e-06
       ubar              1.50954195e-06    1.50982080e-06    1.50982771e-06
       vbar              1.47805759e-07    1.47870988e-07    1.47942021e-07
       temp              1.12177271e-05    1.30822796e-05    1.40771552e-05
       salt              2.70888331e-05    2.90445209e-05    3.22833452e-05
       u                 1.50989621e-06    1.54476679e-06    1.54760557e-06
       v                 5.84640682e-07    1.13022193e-06    1.17730862e-06
                           ANA_VMIX          GLS_MIXING        MY25_MIXING

    However, if PERFECT_RESTART is not activated, we get:

                              RMS               RMS               RMS
       zeta              1.71578595e-09    5.68765614e-09    2.07986550e-09
       ubar              3.91111746e-09    4.38520664e-09    4.21003794e-09
       vbar              9.83973064e-11    2.34650383e-09    1.13328922e-10
       temp              4.01893636e-07    7.00800631e-05    5.55409335e-07
       salt              0.00000000E+00    0.00000000E+00    0.00000000E+00
       u                 9.59030197e-08    1.05812267e-06    2.71992162e-07
       v                 2.89748763e-07    7.39400620e-07    8.01745441e-07
                           ANA_VMIX          GLS_MIXING        MY25_MIXING

    Obviously, this option is not working yet. Two new routines were introduced to achieve the perfect restart in a generic way: nf_read4d.F and nf_write4d.F.

For the current updated file list .

kate - November 7, 2006 @ 18:49
Restart question- Comments (4)

This is code from checkvars.F:

   +84  #ifndef ANA_INITIAL
   +85        get_var(idFsur)=.TRUE.
   +86        get_var(idUbar)=.TRUE.
   +87        get_var(idVbar)=.TRUE.
   +88  # ifdef SOLVE3D
   +89        get_var(idUvel)=.TRUE.
   +90        get_var(idVvel)=.TRUE.
   +91        DO itrc=1,NAT
   +92          get_var(idTvar(itrc))=.TRUE.
   +93        END DO
   +94  # endif
   +95  #endif

I am having trouble in the restart where it reads the time from the restart file, but nothing else. I have a case with #define ANA_INITIAL because I want zero initial flow and zeta (2-D tides), but want to spin up the tides, then restart and save more often. I can’t be the only one who ever wants to restart a test problem. If we ever tackle the problems in the restart, a test problem is an ideal situation to be investigating. I’ll get back to you with a fix…

Problems in restart you ask? Yes, I believe there are some, one being the case of changing history files every say ten saves, then restarting after five or fifteen saves. Try it, you’ll like it.

Edit: I’ve found a fix, hope it works.