Getting Started

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:

 trunk/                               Main trunk directory
      /Atmosphere/                    Atmosphere models root directory
                 /COAMPS              COAMPS root directory (empty)
                 /WRF                 WRF root directory (empty)
      /Compilers/                     make configuration files
      /Data/                          Input data root directory
           /ROMS/                     ROMS data root directory
                /CDL                  ROMS NetCDF metadata design
                /Forcing              Input test cases forcing NetCDF files
                /Grid                 Input test cases grid NetCDF files
                /Initial              Input test cases initial conditions NetCDF files
      /Lib/                           External libraries
          /ARPACK                     Arpack eigenvalue problems library
          /MCT                        Modeling Coupling Tool library
      /Master                         Main standalone and coupling programs
      /ROMS/                          ROMS root directory
           /Adjoint                   Adjoint model
                   /Biology           Adjoint biology/ecosystem models
           /Bin                       Executable scripts
           /Drivers                   Computational drivers
           /External                  Standard input scripts
           /Functionals               Analytical expression header files
           /Include                   Test cases configuration header files
           /Modules                   Declaration modules
           /Nonlinear                 Nonlinear model
                     /Biology         Nonlinear biology/ecosystem models
                     /Sediment        Nonlinear sediment transport model
           /Obsolete                  Discontinued files
           /Programs                  Support programs
           /SeaIce                    Sea-ice model (empty)
           /Representer               Representer model
                       /Biology       Representer biology/ecosystem models
           /Tangent                   Tangent linear model
                   /Biology           Tangent linear biology/ecosystem models
           /Utility                   Generic utility files
           License_ROMS.text          Open source license
           Version                    SVN Version information
      /User/                          ROMS User interface root directory
           /External                  User standard input scripts
           /Functionals               User analytical expressions templates
           /Include                   User application header files
      /WAVES/                         Waves models root directory
            /SWAN                     SWAN root directory
                 /External            SWAN input data and standard input files
                 /Src                 SWAN model

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 at the ROMS website (www.myroms.org) to get access to the algorithms and other user privileges. 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.

• Make sure that you have the following required software in your computer before compiling and running an application:
  • Subversion client to download source
  • Fortran 90 or Fortran 95 compiler
  • cpp program for C-preprocessing ROMS source code.
  • GNU make version 3.81 or higher to compile ROMS
  • Perl interpreter program
  • NetCDF library, Fortran 90 interface
  • Message Passing Interface (MPI) library to run in parallel on a distributed-memory system

• Use a Subversion client to checkout the latest version of the ROMS trunk.

• Compile and link ROMS by typing
  make
  at the top of the directory structure where the makefile is located. This make will build and compile the default ROMS upwelling application. The makefile will include a special machine-dependent include file (Linux-pgi.mk, for instance) particular to your operating system and compiler, found in the Compilers sub-directory. You may need to edit this machine-dependent file so the makefile can find your NetCDF library or set the environmental variables NETCDF_INCDIR and NETCDF_LIBDIR with the path of its include and library directories. You can also modify the makefile if you want to, say, compile ROMS to run with the MPI libraries.
  • You can type make -j N to compile ROMS faster where N is the number of processors. This will spread the compilation and linking over N-processors. Often, you can also compile in debug mode (FFLAGS = -g) -- that will typically compile much faster, so you can make sure the code compiles. However, it will cause the code to run much more slowly. Usually, you will want to optimize the code with a compiler flag -O. We have found that level 2 optimization (FFLAGS = -O2) is usually good enough, and compiles faster (and introduces fewer bugs) than higher level optimization.
  • You can also build ROMS without modifying the makefile or anything else in the source distribution by using the build Script build.sh or build.bash located in the ROMS/Bin sub-directory.

• To run ROMS in serial, just type:
  oceanS < ROMS/External/ocean_upwelling.in > & log &
  or to run in parallel (distributed-memory) on two processors:
  mpirun -np 2 oceanM ROMS/External/ocean_upwelling.in > & log &
  or to run in parrallel (shared-memory) on two processors:
  setenv OMP_THREAD_NUM 2
  oceanO < ROMS/External/ocean_upwelling.in > & log &
  Here, the the file ROMS/External/ocean_upwelling.in contains all the input parameters to required by this application. Notice that in distributed-memory, the leading < is omitted so all parallel threads can read and process this input script without any communications in between.