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:
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:
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
, NIWAKate Hedstrom
, ARSCJohn C. Warner
, USGSJohn 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 UniversityBruce Cornuelle
, Scripps Institute of OceanographyEmanuele Di Lorenzo
, Georgia Institute of technologyArthur J. Miller
, Scripps Institute of OceanographyAndrew 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
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
All the Makefiles of previous versions were eliminated and replaced by a single makefile
and several compiling rules files in the Compilers
AIX-xlf.mk Linux-ftn.mk Linux-path.mk SunOS-f95.mk
CYGWIN-df.mk Linux-g95.mk Linux-pgi.mk SunOS-ftn.mk
CYGWIN-g95.mk Linux-ifc.mk MakeDepend UNICOS-mk-f90.mk
Darwin-f90.mk Linux-ifort.mk MakeDepend.orig UNICOS-mp-ftn.mk
IRIX64-f90.mk Linux-mpif90.mk OSF1-f90.mk UNICOS-sn-f90.mk
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:viewtopic.php?t=183
There is the user section in the new makefile
# Start of user-defined options. Modify macro variables: on is TRUE while
# blank is FALSE.
# Activate debugging compiler options:
# If parallel applications, use at most one of these definitions
# (leave both definitions blank in serial applications):
# If applicable, compile with the ARPACK library (GST analysis):
# 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
file, for example:setenv FORT ifort
Similarly, the user can define environmental variables NETCDF_INCDIR
to specify the location of NetCDF include files and library.
The compiling rules file to include is determined as follows:
# "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')
$(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
), 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.
sub-directory contains the cpp_clean
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
To compile your application, just type:
Alternatively, you can compile in parallel by executing:
% make -j jobs
is an integer indicating the number of CPUs to compile simultaneously. This is a wonderful capability
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
% make print-CPPFLAGS
There are several new files associated with the TLM
, and ADM
. All the infrastructure is already in place for generalized stability analysis, variational data assimilation (S4DVAR
), adjoint sensitivity studies. However, the actual Kernel of these new models is not included in this release. Notice that the Adjoint
, 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
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
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
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
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
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
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
previously) has been redesigned and allows any combination of ANA_INITIAL
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
. 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
. 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 (ocean.in
). 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
. 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
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
. See the following posting for patching guidelines.
, you need to split your version to the above directory structure. Use the following split_21.sh
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
, ROMS/TOMS Developing Team