ROMS/TOMS Developers

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:
  #
  #    ROMS_APPLICATION := UPWELLING
  #
  #  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.
  
  ROMS_APPLICATION ?= UPWELLING
    

• Notice that cppdefs.h contains now the following directive to include the appropriate application header file:

  #if defined ROMS_HEADER
  # include ROMS_HEADER
  #else
    CPPDEFS - Choose an appropriate ROMS application.
  #endif
    

  The macro ROMS_HEADER is assigned in the makefile as:

  
  ifdef ROMS_APPLICATION
    HEADER := $(addsuffix .h,$(shell echo ${ROMS_APPLICATION} | tr [A-Z] [a-z]))
    CPPFLAGS += -D$(ROMS_APPLICATION)
    CPPFLAGS += -D'ROMS_HEADER="$(HEADER)"'
    MDEPFLAGS += -DROMS_HEADER="$(HEADER)"
    CPPFLAGS += -DNestedGrids=$(NestedGrids)
  endif
    

• 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.
  
  MY_HEADER_DIR ?=
  
  #  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.
  
  MY_ANALYTICAL_DIR ?=

  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 ocean.in. Pretty neat, right? This is all possible because the model uses dynamical allocation for all model variables. For example, the input script ocean_upwelling.in 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
        is=LEN_TRIM(Coptions)+1
        lstr=LEN_TRIM(MyAppCPP)
        Coptions(is:is+lstr)=TRIM(ADJUSTL(MyAppCPP))
        is=LEN_TRIM(Coptions)+1
        Coptions(is:is)=','  

  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       Module.mk
     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.