ROMS UNSW2008

Installing and Running ROMS for First Time Users

A Tutorial at the UNSW Computer Labs, 30 March 2009

John Wilkin - this is work in progress

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 the course of the tutorial, we cover how to download the code, configure it for a set of applications, 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.

This wiki entry will be updated on tutorial day as we discover the questions that arise when a set of novice users approach using ROMS for the first time.

Download ROMS

This section assumes you have registered on the ROMS portal and obtained your ROMS username/password as indicated in the Register section.

• Create a src folder where you will keep the ROMS source code. You can place this wherever you wish in your directory tree, 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 a 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. When it finishes, type ls. Your folder src contains the ROMS source code.

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 /tmp/jwilkin/src on host matht001. Instructions below will explain how to point the build.bash script that compiles ROMS to this directory.

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, or in whichever directory you want to organize your ROMS projects, create a new folder named Projects and change into it.

mkdir Projects
cd Projects

• Create a folder named Upwelling and change into it. 'Upwelling' is the name of the ROMS test case we are going to compile and run.

mkdir Upwelling
cd Upwelling

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

cp /tmp/jwilkin/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=/tmp/jwilkin/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 buiuld.bash exmaple. Comment out options with the # symbol like so:

#export MY_CPP_FLAGS="-DNPZD_POWELL"

• Save and close the build.bash file.

• We are compiling in serial using the g95 compiler so make your build.bash match the following:

export USE_MPI=
export USE_MPIF90=
export FORT=g95

• You will need to add the following two lines anywhere above the line that reads cd ${MY_ROMS_SRC}

export NETCDF_INCDIR=/usr/local/include
export NETCDF_LIBDIR=/usr/local/lib

• Copy ocean_upwelling.in file into the Upwelling directory you just created.

cp ../../trunk/ROMS/External/ocean_upwelling.in .