ROMS Cygwin

Tutorial: Installing ROMS in Windows XP / Vista (via Cygwin)

Disclaimer: This post was written for the very beginners. Some parts may be a bit tedious for more advanced users or people with solid Linux knowledge.

The following recipe will guide you through the steps required to download, compile and run ROMS on Windows XP or Vista.

Register

The very first thing to do is to Register. After some checking, ROMS crew will give you a username and a password within a day or two. While you wait, you can prepare your PC with lots of ancillary software that you will need. See below...

Install Cygwin

ROMS runs on a Unix or Linux command-line environment. So, to run ROMS on Windows, first we need to install a Linux emulator for Windows. We need to download and install Cygwin.

• Download: Go to the Cygwin website and download the setup.exe file, by clicking on any of the cygwin-install icons. Or simply click here to start the download.
• Open the recently downloaded setup.exe file
• Select to 'Install from Internet'
• Keep the selected defaults (i.e. 'All Users' and 'Unix / Binary')
• Choose a path where to save Cygwin installation packages, I chose: C:\cygwinfiles
• Select Internet Connection... likely 'Direct Connection' if you have high speed internet.
• Select a download mirror-site. Choose one close to you... University sites are usually reliable.

IMPORTANT: You will need to tell cygwin to install some modules that are not installed by default.

• Install Perl: As shown in the figure below, find the Perl Category and click on 'Default' until it turns into 'Install'.

• Install X11: Do the same in the category of X11. (I needed X11 to run applications on a remote computer. Technically you don't need this to run ROMS on Windows. However, I haven't installed Cygwin without X11 so I'm not sure that some modules installed under X11 may be required later, but feel free to experiment and leave out X11).
• Expand the window and click on the 'View' button on the upper right corner (shown below), until it toggles into 'Full' view.

• Install diffutils: Scroll down and find 'diffutils' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
• Install gcc-g++: Scroll down and find 'gcc-g++' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
• Install gcc4-fortran: Scroll down and find 'gcc4-fortran' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
• Install GNUmake: Similarly, scroll down and find 'make' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See below.

• Install Subversion: Scroll down and find 'subversion' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
• Install wget: Scroll down and find 'wget' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
• Click next. A list of dependencies will show. Install them all by making sure the tick-mark (bottom left) is on and click 'next'
• Make a cup of coffee. Sit back. The download/installation took about 30 min on my machine.

Helpful Cygwin notes

IMPORTANT to keep in mind:

• Cygwin's home directory, which is where cygwin opens by default is, in this example, /cygwin/cygdrive/c/Users/Administrator/ but when in cygwin, this directory abbreviated it as ~
• Cygwin's HOME directory (i.e. ~) = C:\Users\Administrator\ in Windows Explorer
• Cygwin's ROOT directory (i.e. /) = C:\cygwin\ in Windows Explorer

Useful Notes:

• PASTE: To paste text in the cygwin window, right-click on the cygwin symbol on the left-upper corner of the window. Chose Edit > Paste.
• Here are some websites where you can learn more Linux commands
  • http://www.howtoforge.com/useful_linux_commands
  • http://www.tuxfiles.org/linuxhelp/cli.html

Install NetCDF

ROMS needs NetCDF to read input files and to write output files. NetCDF is free to download from Unidata. However, the executable file available is not good for ROMS. We need get the source code and recompile an executable file that is ROMS-friendly. Here are the step-by-step instructions:

• In cygwin change into your software directory and download the NetCDF source code.

cd ~/software
wget http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf.tar.Z

• Unpack it and change into the resulting directory (at the time of this writing this is netcdf-3.6.2).

tar -xvzf netcdf.tar.Z
cd netcdf-3.6.2

• Start the compilation by typing the line below. It will take about 10 minutes. Enough to start a fresh batch of coffee.

CC=gcc FC=gfortran-4 F77=gfortran-4 CPPFLAGS=-DpgiFortran ./configure

• Then, type the text below. This will take just about enough the time for the coffee to brew.

make check

• Finally, type the text below. This is fast; just enough to mix coffee, sugar and milk.

make install

Well done! Have a sip

Download ROMS

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

• Create a roms folder and change into it.

cd ~
mkdir roms
cd roms

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

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

• You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

Customizing 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. Cygwin uses bash by default so we will work with build.bash. A full description of the build script can be found here.

• At the same level as your new trunk directory 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 ocean_upwelling.in file into the Upwelling directory you just created.

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

NOTE: In Cygwin and Linux/UNIX ' ../ ' translates to "up one directory" so what we are doing here is going "up" two directories ( ../../ ), which puts us in the directory containing trunk and Projects (~/roms), then going into the trunk/ROMS/External directory and getting the ocean_upwelling.in file. Likewise, ' . ' translates to "current directory". Which, in this case, is ~/roms/Projects/Upwelling. So, we are copying the ocean_upwelling.in file TO ~/roms/Projects/Upwelling/.

• Copy the upwelling.h file into the Upwelling directory in the same way.

cp ../../trunk/ROMS/Include/upwelling.h .

• Copy the build.bash file into the Upwelling directory.

cp ../../trunk/ROMS/Bin/build.bash .

• Open the build.bash script you just copied into your Upwelling directory using Wordpad or your preferred text editor (except Notepad).

IMPORTANT: The paths you set in this file are relative to the cygwin root directory. So, for example, C:\cygwin\ROMS in Windows Explorer would be /ROMS in cygwin.

• Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your ROMS user name).

 export MY_ROOT_DIR=/home/joeroms/roms
 export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling

• Now set MY_ROMS_SRC to:

 export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk

• Make sure that MY_CPP_FLAGS is not set. I had to comment out one line with the # symbol like so:

#export MY_CPP_FLAGS="-DNPZD_POWELL"

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

 export USE_MPI=
 export USE_MPIF90=
 export FORT=gfortran

• Uncomment the line:

#export USE_MY_LIBS=on

to look like:

 export USE_MY_LIBS=on

• Find the gfortran ) section inside the if [ -n "${USE_MY_LIBS:+1}" ] block.

• Near the bottom of the gfortran ) section you will find the following lines:

      else
          export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include
          export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib
      fi

change them to:

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

• Save and close the build.bash file.

Customizing the CYGWIN-gfortran.mk file

Gfortran is part of the 4.x line of the GNU Compiler Collection. Cygwin allows both the 3.x and 4.x versions to be installed at the same time. As a result, the gfortran compiler has the non-standard name of gfortran-4. This means that we have to edit the CYGWIN-gfortran.mk file in the ROMS source.

• Open ~roms/trunk/Compilers/CYGWIN-gfortran.mk with your preferred text editor (except Notepad).

• Find the line following line:

FC := gfortran

and change it to:

FC := gfortran-4

• Save and close the CYGWIN-gfortran.mk file.

Compile ROMS

Before you run ROMS, you need to compile it to create an executable oceanS file. ROMS Source-Code files are readable by humans while executable files are readable by computers. The compilation process translates the source files into executables. Here are the instructions:

• In cygwin, if you're not there already, go to the Upwelling directory:

cd ~/roms/Projects/Upwelling

• Then type:

./build.bash

• If lots of stuff comes on the screen then you are good. Poor one more cup of coffee, sit back, and enjoy the compiling show. This will take ~15 min.
• When it finishes type ls; if you can see oceanS (your executable file), then the compilation was successful.

Run ROMS

• We need to make one change to our ocean_upwelling.in file so open it with your favorite editor and find the following line:
  VARNAME = ROMS/External/varinfo.dat
  and change it to (again replacing 'joeroms' with your ROMS user name):
  VARNAME = /home/joeroms/roms/trunk/ROMS/External/varinfo.dat
• Save and close the ocean_upwelling.in file
• In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:

./oceanS < ocean_upwelling.in

If lots of numbers are displayed on the screen ROMS is running! Poor one last cup of coffee and enjoy the show (~15 min). Out of the box, ROMS comes programmed to run the Upwelling test case, which is what you are running now. When it finishes, the following output files are created:

ocean_avg.nc
ocean_dia.nc
ocean_his.nc
ocean_rst.nc

To learn one way to visualize them, click here.

Thats it! You got ROMS running!

Now comes the hard part: Learn how to use ROMS. But by now you are probably all coffeed-up and ready learn more. Click here for a good place to start.

Good luck!

Related Pages

• makefile - Detailed information about the ROMS makefile
• Build Script - Detailed information about the ROMS build scripts
• Visualization - Guides for plotting ROMS output
• Test Cases - Description of the test cases that come with ROMS