Getting Started

ROMS is a very complex model with many options and capabilities. ROMS is composed of many Fortran files (*.F), a few header files (*.h), various input script files (*.in), a metadata variable definition file (varinfo.dat), and a single makefile. The ROMS algorithms are distributed with the following directory structure:

 
 src/                                         main root directory
      -------- Compilers/                     make configuration files
      -------- Lib/                           external libraries
      -------- makefile                       a single makefile
      -------- Master/                        main programs
      -------- ROMS/                          ROMS root directory
                      -------- Adjoint/       adjoint model
                      -------- Bin/           executable scripts
                      -------- Drivers/       computational drivers
                      -------- External/      input scripts
                      -------- Include/       configuration header files
                      -------- Modules/       declaration modules
                      -------- Nonlinear/     nonlinear model
                      -------- Obsolete/      discontinued files
                      -------- Programs/      support programs
                      -------- SeaIce/        sea-ice model
                      -------- Representer/   representer model
                      -------- Tangent/       tangent linear model
                      -------- Utility/       generic utility files
                      -------- Version        version information

ROMS uses extensively C-preprocessing to activate and/or deactivate the various numerical and physical algorithm options. It also uses NetCDF to manage input and output data streams. It is highly recommended that first time users learn the basics about NetCDF before starting working with ROMS.

Basic Steps:

• Register in the ROMS website (www.myroms.org) to get access to the algorithms and other user privileges. The user needs to select an username and password which will be used in the future to login and post messages in the ROMS forum, algorithm downloads, and contributing to wikiROMS.

• Download the ROMS distribution file, unzip and untar to the desired directory. After unpacking, the ROMS files are placed in the directory tree structure shown above.

Questions from New Users

• My build finished with no errors. Where is the ROMS executable?

It is either in oceanS (serial), oceanO (OpenMP), oceanM (MPI), or oceanG (debug). Check the makefile to see which options are on.

• What do I have to do to run an application?

There are basically four levels of complexity in running an application.

1. Canned applications that come with the ROMS distribution and don't need input. These can be run by editing ./Include/cppdefs.h to #define one (all others should be #undef) of the pre-defined model applications. Then make (good practice to make clean first) and, if you are lucky, the program will build. It should run with the command ./oceanS
2. Canned applications that come with ROMS and require input files. Same as above, but now they have to be run with a command like ./oceanS < External/ocean_some_predefined_app.in. These may also require netCDF input files with names like ocean_some_predefined_app.nc.
3. User-specified applications with no input data. These are the best test beds for new users or new algorithms. They consist of a set of selected cpp options in /Include/cppdefs.h, a user-generated .in file, and usually modifications to /Nonlinear/analytical.F to specify intial, boundary, and forcing conditions internally.
4. User applications with input data...the real deal. These require changes to cppdefs.h, some_app.in, and appropriate input files for initialization and forcing.

• Why the _r8 at the end of real constants?

Some computers use 32 bits for single precision real numbers and 64 bits for double precision, and some use 64 and 128, respectively. For consistent results on various machines, ROMS takes advantage of the intrinsic F90/95 function SELECTED_REAL_KIND( ). (See ./Modules/mod_kinds.F). This allows you to associate an integer parameter with a specific data type...in this case r8 is associated with 64-bit precision. RTFM (Read the Fortran90 Manual), or better yet, chapter 11 in Chapman, 2004.