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, I chose: C:\Program Files\cygwin
• 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 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 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.

• 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.

Install g95

This Fortran compiler works in cygwin/Windows. In theory, you should be able to install other Fortran compilers instead, but I just didn't have luck with the others I tried. If you don't know what compiling is, read Compile ROMS below.

• Go to the g95-project website and download the G95 binaries. Or simply click here to start the download.
• Save it inside the cygwin folder (C:\cygwin in this tutorial).
• Now you have to open cygwin and go to the place where you saved the g95-x86-cygwin.tgz file. Here you need to know that cygwin uses the folder C:\cygwin\cygdrive as a pseudo-drive. When cygwin starts, you will be able to see all your files and folders that you have in your Windows-user root (i.e. C:\Users\Administrator\), but they will appear to be in a different location (i.e. /cygwin/cygdrive/c/Users/Administrator/ ). This is just cygwin's way to emulate a Linux-type hard-drive inside Windows.

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 it, cygwin abbreviates 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

Ok back to g95. Open cygwin and go to the root directory. To do this type cd / (cd = command for: 'change directory'). Now that you are in the root directory, type ls (command for: "show contents of this directory"), you should see our recently downloaded g95-x86-cygwin.tgz file.

• Extract (or unzip) g95-x86-cygwin.tgz by typing:

tar -xvzf g95-x86-cygwin.tgz

• This should install g95 in /usr/local/bin and its documentation in /usr/local/doc/g95

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:

• Go to the Unidata website and download the NetCDF C/C++/Fortran Source Code and Documentation. Or simply click here to start the download.
• Same as before, save the file in the cygwin folder C:\cygwin
• Unpack it by typing:

tar -xvzf netcdf.tar.Z

• Go to the location where it unpacked by typing cd netcdf-3.6.2 and 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=g95 CPPFLAGS=-DpgiFortran FFLAGS=-fno-second-underscore FCFLAGS=-fno-second-underscore ./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

Install subversion

This is software needed to download ROMS source code. I used a GUI for subversion called Tortoise (wonderful and free), but you can use most any subversion client. Tortoise is an ADD-ON for Windows Explorer.

• First download the installer at the TortoiseSVN website. Or simply click here to start the download.
• Open the installer and follow instructions.
• Restart your computer (The Installer asks you to do so).

Download ROMS

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

• In Windows Explorer, create a folder for ROMS in a place easy to find under cygwin. I.e. under C:\cygwin\ (I named my folder simply ROMS)
• Then, using Windows Explorer, get into the folder you just created and right-click and choose 'SVN Checkout...'
• Type the URL where ROMS lives: https://www.myroms.org/svn/src/trunk

Note: You could check out the entire repository by using the URL https://www.myroms.org/svn/src but this will download several unnecessary, older versions of ROMS in the 'tags' directory. Therefore, we recommend that you only check out the trunk.

• Add \trunk to end of the path in the 'Checkout directory:' box (Mine now reads C:\cygwin\ROMS\trunk) now click 'OK' and then 'Yes' when it asks you if you would like to create the trunk folder.

• Enter your username and password, poor another cup of coffee and let the download begin!

Note: In Windows VISTA there was a problem at the end of the download. Tortoise couldn't access the .svn folder. I think this will cause problems when getting ROMS updates. However, all source code got downloaded, compiling was successful and test case ran ok. This problem DIDN'T occur in Windows XP.

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.

• With Windows Explorer create a folder named Projects in the same directory as your new trunk directory.
• Go into the Projects folder and create a folder named Upwelling. 'Upwelling' is the name of the ROMS test case we are going to compile and run.
• Open a new Windows Explorer window and go to C:\cygwin\ROMS\trunk\ROMS\External
• Copy ocean_upwelling.in and ocean_upwelling.in file and paste it in the Upwelling directory you just created
• Using Windows Explorer, go to C:\cygwin\ROMS\trunk\ROMS\Bin
• Copy the build.bash file and paste it in the Upwelling directory
• Open the build.bash script you just pasted into 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, span class="red">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.

export MY_ROOT_DIR=/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 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

• Save and close the build.bash 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, 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:
  VARNAME = /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 a 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