ROMS UNSW2008

Installing and Running ROMS for First Time Users

A tutorial for new ROMS users will be held at the UNSW Computer Labs on Monday 30 March 2009, immediately prior to the ROMS Sydney 2009 User Workshop at the Sydney Institute of Marine Sciences, 31 March to 2 April 2009.

This tutorial is intended for complete newcomers to ROMS. It assumes basic knowledge of working in a UNIX environment, and that the essential components required to compile and execute ROMS are already installed on the host computer network. This wiki page borrows heavily from David's Robertson's excellent Installing ROMS under Cygwin tutorial where you will find more information about setting up the required computing environment (compilers, libraries etc.) for ROMS.

In this tutorial, we cover how to download the code, configure it for an application, and run the model. Error messages that arise during the configuration process will be explained so that these can better be debugged when users return to their home institutions and try to work through this process again.

An important resource you should use as you get started is the Frequently Asked Questions entry in WikiROMS.

Download ROMS

The disk space available on the UNSW Computer Lab machines is quite limited, so for the purposes of this tutorial we have downloaded the ROMS source code to /srv/ckpt/roms/shared/src on host matht001. Instructions below will explain how to point the build.bash script that compiles ROMS to this directory.

To download the code to your own machine, these are the steps you would follow:

• You must have already registered on the ROMS portal and obtained your ROMS username/password as indicated in the Register.

• Create a src folder where you will keep the ROMS source code. You can place this wherever you wish in your directory tree (here we assume under your home directory "~") and name it whatever you like.

cd ~
mkdir src

• Check out the ROMS source code replacing bruce with the ROMS user name you registered with.

svn checkout --username bruce https://www.myroms.org/svn/src/trunk src

Note the target directory src at the end of the command. If your code ends up in the wrong place, you may have omitted this.

You will see many lines stream by indicating the files that are being added to your src directory. When it finishes, you can type ls src to see the contents of the directory.

To see the contents of the directory where the code is downloaded for this tutorial, type this:

cd /srv/ckpt/roms/shared
ls src

Customize the Build Script

The ROMS source code comes with a build script in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. The UNSW Computer Lab machines are configured to use bash as the default login shell, so we will work with build.bash. A full description of the build script can be found here.

• In your home directory (you can use some other directory to organize your ROMS projects if you wish) create a new folder named Projects and change into it.

cd ~
mkdir Projects
cd Projects

• Create a folder named upwelling and change into it. ROMS is distributed with several Test Cases and the Upwelling example is the default which we will compile and run here.

mkdir upwelling
cd upwelling

• Copy the build.bash file distributed with ROMS to your Projects/upwelling directory.

cp /srv/ckpt/roms/shared/src/ROMS/Bin/build.bash .

Next we need to configure a few options inside build.bash so that it finds the directories where the source code and your Project are located.

• Open the build.bash script you just copied into your upwelling directory using your preferred text editor, e.g. vi.

vi build.bash

• Scroll down until you find MY_PROJECT_DIR and set it as follows.

export MY_PROJECT_DIR=${HOME}/Projects/upwelling

This obviously assumes you put Projects/upwelling under your home directory.

If you frequently move your ROMS project between hosts where you have a different directory structure, e.g. a temporary scratch space, you can use the MY_ROOT_DIR variable to minimize the changes you make to build.bash.

• For example:

export MY_ROOT_DIR=/usr/scratch/bruce
export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/upwelling

Next we tell build.bash where to find the ROMS source code downloaded from the svn repository (which you can keep up to date the svn update command - see more on this at LINK ). Note that most of the source code changes you make to customize ROMS will be made in your Projects space, and need not be made to the downloaded code directly. We will discuss exceptions to this during the tutorial, and how source code modifications interact with svn.

• Set MY_ROMS_SRC to the location of the source code:

export MY_ROMS_SRC=/srv/ckpt/roms/shared/src

In practise, you will probably do something more like this:

export MY_ROMS_SRC=${MY_ROOT_DIR}/src

assuming this is the relative path in which you keep your source code on the various machines you work on.

Make sure that MY_CPP_FLAGS is not set. Sometimes this is set in the distributed build.bash exmaple. Comment out options with the # symbol like so:

#export MY_CPP_FLAGS="-DAVERAGES"

The UNSW Computer Lab machines are single core, so we need to tell build.bash not to assume MPI parallel compilation.

• Comment out the options for USE_MPI and USE_MPIF90

#export USE_MPI=on
#export USE_MPIF90=on

• If you were compiling in parallel you would leave the default entries in build.bash.

export USE_MPI=
export USE_MPIF90=

• We leave the compiler option as the default because this says use the ifort (Intel FORTRAN) compiler which is what we want on the UNSW machines.

export FORT=ifort

• In the interests of speed for this tutorial, we turn off compiler optimization by activating the debug option:

export USE_DEBUG=on

On the UNSW Lab machines compiling with optimization on will take over 15 minutes, but with optimization off (USE_DEBUG=on) it will be less than 60 seconds.

Save and close the build.bash file.

Copy the input and CPPDEFS options files

We need three more files in Projects/upwelling to configure and run ROMS. We copy the versions downloaded with svn because these are files you will work with locally when you experiment with changes to the test case example configuration.

• Copy files ocean_upwelling.in, varinfo.dat and upwelling.h into the Projects/upwelling directory you just created.

cd ~/Projects/upwelling
cp /srv/ckpt/roms/shared/src/ROMS/External/ocean_upwelling.in .
cp /srv/ckpt/roms/shared/src/ROMS/External/varinfo.dat .
cp /srv/ckpt/roms/shared/src/ROMS/Include/upwelling.h .

View the file upwelling.h. It contains all the C-Pre-Processor (CPP) options that the compiler interprets to activate certain source code options within ROMS.

View the file ocean_upwelling.in. It contains the inputs options that ROMS reads from standard input at run time to set options that need not be fixed at compile time.

View varinfo.dat. The file varinfo.dat contains descriptions of the names and attributes of input and output variables that ROMS reads and writes from netcdf files. For most applications you will not need to change the entries in this file. If you need to know the default units assumed for different variables, those are noted in this file. (Before we run ROMS, we will need to tell it where to find this file).

Now we are ready to compile ROMS by executing the build.bash script.

Compile ROMS

Before you run ROMS, you need to compile it to create an executable oceanS file (S for serial or single processor computer), or oceanM file (if using MPI on a parallel computer).

• Go to your upwelling project directory:

cd ~/Projects/upwelling

• Then type:

./build.bash

• If lots of stuff comes on the screen then compilation is proceeding, and make take some time.

• If the build process ends quickly with an error, then it is likely that build.bash does not point to the correct location for the upwelling.h file, the FORTRAN compiler, or some libraries. We describe common getting started errors and solutions in the next section.

• You may give the option -j to the build command to distribute the compilation to multiple processors if your host supports this, e.g.:

./build.bash -j 8

to compile on 8 processor at once.

If your build was successful it will not have reported any errors, and there will be an executable file in your Projects/upwelling directory called oceanG. The "G" in the file name indicates build.bash activated the USE_DEBUG option.

If USE_DEBUG were not selected, the executable would be oceanS, where the "S" indicates "serial" or "single-processor" because we deactivated MPI.

If you had activated MPI with the USE_MPI option the executable would be named oceanM.

(See also FAQ: My build finished with no errors, where is the ROMS executable?).

Common getting started compile error messages

Getting past the first few errors with compilation is often tricky. Carefully read any error messages you get for clues on what might be wrong with your configuration. Here are some common difficulties new users encounter getting started when first executing the build.bash command.

• Compilers/../ROMS/Include/cppdefs.h:709:22:
  error: /student/0/a0000020/Projects/upwelling/upwelling.h: No such file or directory
  This says the file upwelling.h is not where Build expects it to be, which is in MY_PROJECT_DIR. You set this to ~/Projects/upwelling.

• cp: cannot stat `/opt/intelsoft/netcdf/include/netcdf.mod': No such file or directory
  This says that netcdf is not where build.bash expects to find it. Locate where the netcdf include and lib directories with steps something like:
  cd /usr
  find . -name netcdf.mod -print
  ./local/netcdf-3.6.2/include/netcdf.mod
  ./local/netcdf/intel/3.6.3/include/netcdf.mod
  This tells us the most recent (3.6.3) netcdf is in /usr/local/netcdf/intel/3.6.3. Direct ROMS to this location by making two changes to build.bash. First, advise ROMS to read your changes to the default library path by uncommenting the option for USE_MY_LIBS.

export USE_MY_LIBS=on

Then specifiy the correct location for netcdf:

export NETCDF_INCDIR=/usr/local/netcdf/intel/3.6.3/include
export NETCDF_LIBDIR=/usr/local/netcdf/intel/3.6.3/lib

Be careful where you make this change. You need to make it for the ifort compiler option, and NOT for the USE_NETCDF4 option (we are using netcdf-3). If you've done this correctly, your compilation with build.bash should now succeed.

• error
  error:
  Note here further errors we encounter during the tutorial.

Run ROMS

You run ROMS by executing the oceanG (or oceanS) binary, giving it the ocean_upwelling.in file as UNIX standard input.

./oceanS < ocean_upwelling.in

ROMS standard output will be typed to the screen. To save it a file instead, enter, e.g.:

./oceanS < ocean_upwelling.in > my_upwelling.log

If you have compiled a parallel (MPI) executable, the syntax for running the mode is slightly but critically different. The ocean_upwelling.in file is no longer read from UNIX standard input (it has handled by all the MPI threads) so the "<" disappears from the command, and you need the correct syntax on your UNIX host for running an MPI process. It is probably something like:

mpirun -np 8 ./oceanM ocean_upwelling.in > my_upwelling.log

where the "-np 8" indicates use 8 processors and this number of tiles must have been set by

(See also FAQ: What do I have to do to runs ROMS?).

Common getting started run error messages

bash: oceanG: command not found

The working directory is not in your UNIX path. That's why we type "dot-slash" in front of the commands above.

Successful execution

When ROMS runs it will type a lot of information to UNIX standard output. This is the "logfile" you named following the ">", or your terminal if you did not redirect stdout.

stdout shows the following:

unix shell

UNIX process info, run time, run TITLE

Process Information:
Thread #  0 (pid=    4449) is active.
Model Input Parameters:  ROMS/TOMS version 3.2  
                         Monday - March 23, 2009 - 10:02:39 AM
-----------------------------------------------------------------------------
Wind-Driven Upwelling/Downwelling over a Periodic Channel