How to start using ROMS/TOMS

Instructions and hints for beginners

Moderators: arango, robertson

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

How to start using ROMS/TOMS

#1 Post by arango »

I keep getting this question over and over. So I think that is time to add this information to the forum. Please use the following guidelines when learning to use ROMS/TOMS. The model is somewhat complex with a high learning curve but it would payoff big time when running realistic applications in the future.

For first time users, I highly recommend to:

(1) Learn everything that you can about NetCDF files. The NetCDF (Network Common Data Form) library is used extensively by ROMS/TOMS to manage input and output data streams. The NetCDF library defines a machine-independent format for representing scientific data. Together, the interface, library, and format support the creation, access, and sharing of scientific data. The NetCDF software was developed at the Unidata Program Center in Boulder, Colorado. The freely available source can be obtained from Unidata:

The above link provides a comprehensive information about the NetCDF library. In order to compile ROMS/TOMS you need to install this library correctly on your computer.

(2) If possible, you need to get access to a computer with Matlab installed. Matlab is a licensed software by MathWorks:

You have different choices for the kind of license to buy from MathWorks according to your needs and budget. Usually, a single-user Matlab license is affordable, and you pay a one-time only fee for its usage. This sounds like a commercial endorsement of Matlab. However, we do not have absolutely any commercial deals with Matlab. For the last few years, several tools using Matlab have been written by us and others to process ROMS/TOMS input and output files. I have been using Matlab for more than ten years and I have hundreds of ROMS/TOMS related scripts. Many users have also written a large number of these scripts. We are planing to have repository for those scripts in the future. The reason for this is that there is an interface between Matlab and NetCDF. This interface is known as MeXCDF. For more information about MeXCDF and the NetCDF toolbox for Matlab, please visit: ... excdf.html ... c4ml5.html

How to use ROMS/TOMS:

(1) For first time users, it is recommended to run the provided ROMS/TOMS test cases. Any of these test cases are activated by turning on/off the appropriate CPP flag in cppdefs.h. Only one application option can be activated at the time. Each test case has an associated input script. Currently, the following CPP flags and input scripts are available:

Code: Select all

By default the model is configured with the wind-driven upwelling/downwelling over a periodic channel: UPWELLING.

Notice than in addition to the ROMS/TOMS input script ocean_*.in, there are other default input scripts associated with the following CPP options:

Code: Select all

The file name for these input scripts is specified in ROMS/TOMS input script ocean_*.in. Currently, the following test cases have the following associated scripts:

Code: Select all

(2) Select the appropriate Makefile for your computer. Currently, the following Makefiles are available for serial, distributed-memory (MPI), and shared-memory (OMP) configurations:

Code: Select all

    Makefile.alpha       Makefile.MPI_alpha        Makefile.OMP_alpha
    Makefile.cray        Makefile.MPI_cray
    Makefile.crayx1      Makefile.MPI_crayx1
    Makefile.df         Makefile.MPI_ibm          Makefile.OMP_ibm
    Makefile.ifc                                   Makefile.OMP_ifc
    Makefile.ifort                                 Makefile.OMP_ifort
    Makefile.pgi         Makefile.MPI_pgi
    Makefile.sgi         Makefile.MPI_sgi          Makefile.OMP_sgi
    Makefile.sun         Makefile.MPI_sun          Makefile.OMP_sun
Usually, you need to edit the selected Makefile to specify the correct location of the NetCDF include file and library in macro variable NETCDF_INCDIR and NETCDF_LIBRARY, respectively. I always redirect the binary file to different directory than the source code. For the Upwelling test case, I modify the BIN macro to:

BIN = ../Test/Upwelling/oceanS

That is, the executable oceanS is saved in the ../Test/Upwelling directory. To compile your application just type, for example:

make -f Makefile.ifort

(3) If compilation is successful, then ROMS/TOMS can be run by just typing:

oceanS < > & log &

This redirect the standard output of ROMS/TOMS to log file. In distributed-memory, the command is different:

mprun -np 4 oceanM > & log &

Here, the input script is read using the Unix intrinsic routine getarg or similar command-line argument routine used by your operating system. See file mp_routines.F and search for the my_getarg routine. Other system routines can be added very easily, if necessary. Please let me know if this is the case.

In serial and parallel applications, the user need to modify the input parameters NtileI and NtileJ in ocean_*.in. Notice that you can have partitions in serial applications. It turns out that, in some computers, the code run faster if you partition the domain grid, and then run on a single processor. This is because of better use of the cache in your computer. In distributed-memory applications, the number of nodes (CPUs) used must be equal to the product of NtileI and NtileJ. In shared-memory applications, the product of NtileI and NtileJ must be a multiple of the total number of parallel threads (CPUs) assigned.

Good luck, :)

User avatar
Posts: 3939
Joined: Wed Jul 02, 2003 5:29 pm
Location: CFOS/UAF, USA

#2 Post by kate »

If anyone is interested, I have a NetCDF talk prepared at
The examples are in NCL because NCL has a very nice NetCDF interface.

Post Reply