ROMS 2.2 Released

ROMS Code Release Announcements

Moderators: arango, robertson

Post Reply
User avatar
Site Admin
Posts: 1295
Joined: Wed Feb 26, 2003 4:41 pm
Location: DMCS, Rutgers University

ROMS 2.2 Released

#1 Unread post by arango »

ROMS/TOMS 2.2 Release Notes

This is another major release and upgrade to ROMS/TOMS. We have been working on this new version for some time. There is a substantial restructuring of the code to facilitate the coding of the tangent linear (TLM), representer tangent linear (RPM) and adjoint (ADM) models. However, these models are not included in this release. They will be released in version 3.0 in a couple of months if not earlier. We are only releasing the new structure and the Nonlinear model in version 2.2. This will allow us to correct any problems with this version.

ROMS/TOMS has now the following tree-directory structure:

Code: Select all

Adjoint/    Drivers/   Lib/        Obsolete/     SeaIce/   Version 
Bin/        External/  Modules/    Programs/     Tangent/  makefile 
Compilers/  Include/   Nonlinear/  Representer/  Utility/
Notice the uppercase in the directories names. Some care was taken to not repeat an uppercase letter so we can use auto-complete when processing. ROMS/TOMS is partitioned into several sub-directories as follows:

Code: Select all

Adjoint/                ROMS/TOMS Adjoint model 
Bin/                    executable scripts: cpp_clean, sfmakedepend ... 
Compilers/              makefile rules and MakeDepend 
Drivers/                ROMS/TOMS drivers 
External/               Input scripts (*.in), varinfo.dat 
Include/                cppdefs.h, globaldefs.h, set_bounds.h, tile.h, wrf_io_flags.h 
Lib/                    ROMS/TOMS needed libraries, PARPACK, etc 
Modules/                ROMS/TOMS declaration modules 
Nonlinear/              ROMS/TOMS nonlinear model 
Obsolete/               Obsolete files 
Programs/               Other support programs 
Representer/            ROMS/TOMS representer tangent linear model 
SeaIce/                 ROMS/TOMS Sea Ice 
Tangent/                ROMS/TOMS tangent linear model 
Utility/                ROMS/TOMS generic routines, IO, etc 
Version                 ROMS/TOMS Version 
makefile                A single makefile
First, I want to acknowledge the contributions of several of my collaborators who helped me to improve and patiently tested this version over and over:

Mark Hadfield, NIWA
Kate Hedstrom, ARSC
John C. Warner, USGS
John Wilkin, Rutgers University

You all are great :!: John Warner implemented MPDATA so we can have positive definite advection of tracers. We have gone through several versions of this code over the last year. He substantially enhanced the sediment model. I appreciate his curiosity and scientific approach and the time spent testing this version. Kate helped us to redesign the makefile structure for ROMS/TOMS. Now only a single makefile is needed. Many thanks to Mark for helping us with the makefile design and testing. Finally, many thanks to John Wilkin for testing this version in all his complex and realistic applications.

Many thanks to the ROMS/TOMS adjoint group:

Hernan G. Arango, Rutgers University
Bruce Cornuelle, Scripps Institute of Oceanography
Emanuele Di Lorenzo, Georgia Institute of technology
Arthur J. Miller, Scripps Institute of Oceanography
Andrew M. Moore, University of Colorado

It has taken us almost four years to get to this point. You guys are fantastic. We are almost there 8)

Finally, many thanks to ONR for their funding and support. Also many thanks to all of you who reported bugs from the previous version.

What is New:

(*) ROMS/TOMS is now split into several sub-directories. This will facilitate future updates of the code and better organization of over 420 files :shock:

(*) All the Makefiles of previous versions were eliminated and replaced by a single makefile and several compiling rules files in the Compilers sub-directory:

Code: Select all     MakeDepend   MakeDepend.orig
This new makefile structure will only work with GNU make (in some computers it is aliased to gmake) :!: We have tested with several versions of GNU make and it works with versions 3.77 or higher. To check which version you have in your system just execute the command:

% make -v

Update GNU make if necessary. This can be done very easily. For more information about the new makefile design please check Kate's posting:


There is the user section in the new makefile:

Code: Select all

#  Start of user-defined options. Modify macro variables: on is TRUE while
#  blank is FALSE.
#  Activate debugging compiler options:

       DEBUG :=

#  If parallel applications, use at most one of these definitions
#  (leave both definitions blank in serial applications):

         MPI :=
      OpenMP :=

#  If applicable, compile with the ARPACK library (GST analysis):

      ARPACK :=

#  If applicable, activate 64-bit compilation:

       LARGE := on

#  We are going to include a file with all the settings that depend on
#  the system and the compiler. We are going to build up the name of the
#  include file using information on both. Set your compiler here from
#  the following list:
#  Operating System        Compiler(s)
#     AIX:                    xlf
#     ALPHA:                  f90
#     CYGWIN:                 g95, df
#     Darwin:                 f90
#     IRIX:                   f90
#     Linux:                  ifc, ifort, pgi, path, g95, mpif90
#     SunOS:                  f95
#     UNICOS-mp:              ftn
#     SunOS/Linux:            ftn (Cray cross-compiler)
#  Feel free to send us additional rule files to include! Also, be sure
#  to check the appropriate file to make sure it has the right paths to
#  NetCDF and so on.

        FORT ?= pgi

#  Set directory for executable.

      BINDIR := .

#  End of user-defined options. See also the machine-dependent include
#  file being used above.
The user needs to edit the makefile and provide the values for the FORT macro above since it is used to determine the compiling rules file to include. Notice that this macro is defined with ?= operator. This indicates that the Unix enviromental variable FORT takes precedence, if defined. This is very convienient when running in several computers communicating with the same disk storage system. The user just needs to define this environmental variable in his/her .cshrc or .login file, for example:

setenv FORT ifort

Similarly, the user can define environmental variables NETCDF_INCDIR and NETCDF_LIBDIR to specify the location of NetCDF include files and library.

The compiling rules file to include is determined as follows:

Code: Select all

#  "uname -s" should return the OS or kernel name and "uname -m" should
#  return the CPU or hardware name. In practice the results can be pretty
#  flaky. Run the results through sed to convert "/" and " " to "-",
#  then apply platform-specific conversions.

OS := $(shell uname -s | sed 's/[\/ ]/-/g')
OS := $(patsubst CYGWIN_%,CYGWIN,$(OS))
OS := $(patsubst sn%,UNICOS-sn,$(OS))

CPU := $(shell uname -m | sed 's/[\/ ]/-/g')

ifndef FORT
  $(error Variable FORT not set)

ifneq "$(MAKECMDGOALS)" "clean"
  include Compilers/$(OS)-$(strip $(FORT)).mk
The other macros are used to compile with debugging flags (DEBUG), parallel applications (MPI or OPENMP), link with ARpack library (ARPACK, used in some TLM/ADM applications), and activate 64-bit compilation (LARGE). Finally, the user can modify the BINDIR macro to send the executable to any directory.

The Bin sub-directory contains the cpp_clean and sfmakedepend perl scripts used by the makefile. Many thanks to Kate for developing these complex perl scripts. The cpp_clean script is used to clean the *.f90 files after C-preprocessing. The sfmakedepend script is used to create ROMS/TOMS compiling dependency file MakeDepend. This is a very important file :!: To create the dependency file just execute:

% make depend

This needs to be executed only when new files are added or file association via the USE command is changed :roll:

To compile your application, just type:

% make

Alternatively, you can compile in parallel by executing:

% make -j jobs

where jobs is an integer indicating the number of CPUs to compile simultaneously. This is a wonderful capability :wink:

The new makefile has a handy debugging target. This will allow to print the value of any makefile defined macro. For example, to find the value of CPPFLAGS execute:

% make print-CPPFLAGS

(*) There are several new files associated with the TLM, RPM, and ADM. All the infrastructure is already in place for generalized stability analysis, variational data assimilation (S4DVAR, IS4DVAR), adjoint sensitivity studies. However, the actual Kernel of these new models is not included in this release. Notice that the Adjoint, Representers, and Tangent sub-directories are empty. We are very advanced in the testing of these algorithms and hope to release them in version 3.0 soon.

(*) Notice also that the sub-directory SeaIce is also empty. Paul Budgell's Sea/Ice model will be also available in version 3.0.

(*) There are several new entries in all input scripts which are now located in the External sub-directory.

(*) The IO metadata descriptor External/varinfo.dat has been updated to include precise information about input and output units and scale factors. For more information check the following posting:


(*) Added few variables to the time averaged NetCDF file: net salt flux, net evaporation, net rain fall, sediment bed load fluxes, and other quadratic terms which are activated with CPP option AVERAGES_QUADRATIC.

(*) There is a new bottom boundary layer model which can be activated with CPP option SSW_BBL. Many thanks to Chris Sherwood, Rich Signell, and John Warner (USGS) for coding this new model. This model has several variations to the Styles and Glenn (2000) model.

(*) The EcoSim bio-optical model was updated and it is now running in our East Coast applications. Many thanks to Paul Bissett and John Wilkin for their testing.

(*) Added the capability to write the latest model state into the next time record of the RESTART NetCD file if the model blows-up. This is very helpful when tracking blow-up problems. In the past, we have to restart the model so we can output the model fields just before blowing-up. This is not longer needed :D

(*) The sediment transport algorithms have been modified to include bed load transport. The bed load formulation is based on the Meyer-Peter Muller method to calculate bed load transport fluxes at the RHO-points. The fluxes are then "upwind-shifted" to U- or V-points and flux divergences are calculated to determine the change in bed mass. Other bed properties of thickness and sediment fractions and bed surface properties are then updated. User can select BEDLOAD and/or SUSPLOAD together or independently. Many thanks to John Warner developing and updating these algorithms.

(*) Added an option for MPDATA advection of tracers. Many thanks to John Warner for helping us to implement this option which can be activated with TS_MPDATA. This algorithm computes the anti-diffusive velocities using the recursive method of Margolin and Smolarkiewicz (1998).

(*) Information about the operating system, compiler, and compiler flags is added to the output NetCDF files global attributes.

(*) Added logic for three-ghost points. This is only needed when TS_MPDATA is activated.

(*) Updated the bulk fluxes algorithm to COARE version 3.0. Many thanks to Kate Hedstrom for helping us to update this code. Also, many thanks to Jim Edson for looking at our version and correcting the code for specific humidity. We added also the EMINUP option to compute equivalent salt flux. Many thanks to Paul Goodman for coding and testing this option.

(*) The Fasham-type biology model has been updated. Many thanks to Katja Fennel for developing and testing this model. It now includes CARBON and OXYGEN options. This ecosystem model has now been expanded to 12-components.

(*) Added the capability to include inert passive tracers other than biological and sediment tracers. An inert passive tracer is one that is only advected and diffused. Other processes are ignored. These inert tracers include, for example, dyes, pollutants, oil spills, etc. This option is activated with T_PASSIVE. The analytical option ANA_PASSIVE can be used to specify the inert tracer initial distribution and concentration.

(*) The routine get_state (get_initial previously) has been redesigned and allows any combination of ANA_INITIAL, ANA_BIOLOGY, ANA_SEDIMENT, ANA_PASSIVE and initial conditions from NetCDF file.

(*) In the past, we needed both tidal elevation and currents to force the model. This is still the optimal approach. However if there is only tidal elevation available, we can estimate the tidal currents using reduced-physics. See u2dbc_im.F and v2dbc_im.F. Notice that the Flather boundary conditons also have a new option to determine the barotropic pressure gradient at the boundary. It can be computed from the boundary arrays (FSOBC_REDUCED, i.e. data) or from the model state free-surface. Notice that if tidal currents are not available, the bry_val is computed by reduced physics (pressure gradient, Coriolis and surface and bottom stress) at the boundary edge.

(*) In addition, there are four new reduced-physics boundary condition options: WEST_M2REDUCED, EAST_M2REDUCED, SOUTH_M2REDUCED, NORTH_M2REDUCED. So you have the choice of applying tidal forcing with Flather boundary conditions, reduced-physics, or combinations of both.

(*) The routine clm_tides was renamed to set_tides. A new parameter, TIDE_START, was added to the model input script ( This is the reference time origin for tidal forcing (days). It is the time used when processing input tidal data (from models). It is needed to compute the correct phase lag with respect ROMS/TOMS initialization time.

(*) The routine gls_corstep.F now includes CPP options: CHARNOK and CRAIG_BANNER. The Charnok definition allows specification of the sea surface roughness coefficient to be zos = alpha u*s2 / g, where alpha = 1400 (can be modified by user in gls_corstep.F). See Charnok, H. 1995. Wind stress on a water surface. Quart J Roy. Meteor. Soc. 81, 639-640. The Craig-Banner definition provides a surface flux boundary condition for tke and gls representing the effect of surface wave breaking, based on Craig, P.D., and Banner, M.L. (1994) Modelling wave-enhanced turbulence in the ocean surface layer. J. Phys. Oceanogr., 24, 2546-2559. Many thanks to John Warner for implementing these options.

How To Patch:

You have the choice to take the full tar of the new version from the web site or patch your current version using patch_roms-2.1 to patch from version 2.1 to 2.2. See the following posting for patching guidelines.


If patching, you need to split your version to the above directory structure. Use the following shell script to do so:

Before running this script make sure that you save your current version of the model in case that something fails. Warning, this script will delete all your old Makefiles. It will also rename some files and then move the files to the appropriate sub-directories.

To patch, go to ROMS/TOMS tree-directory (i.e. the directory where Version file is located) and excute:

% patch -p1 < patch_roms-2.1

Happy Computing :) , ROMS/TOMS Developing Team
Last edited by arango on Sun Jun 05, 2005 5:30 pm, edited 6 times in total.

User avatar
Posts: 521
Joined: Tue Jul 01, 2003 4:12 am
Location: NIWA

#2 Unread post by m.hadfield »

Great work, Hernan!

A quibble:
This new makefile structure will only work with GNU make (gmake) Exclamation We have tested with several versions of gmake and it works with versions 3.7.x or higher.
That should be "version 3.77 or higher". (Note that it's "version three point seventy-seven", not "three point seven point seven".) Version 3.77 came out in 1998 and the current version is 3.80, with 3.81 due soon.

Post Reply