ROMS Mac Snow Leopard

Tutorial: Installing ROMS on Mac OS X Snow Leopard

THIS PAGE IS UNDER CONSTRUCTION

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found here.

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, click here. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

Code Box Legend: In the code boxes, The text in green is what you need to type at the terminal prompt and the black text is what is displayed as a result of your command. Ellipsis (. . .) mean that large amounts of output are omitted for brevity.

You must be logged in as a user with administrator privileges to complete most this tutorial.

Install Supporting Software

Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

Xcode

Download the Apple Developers Tools Xcode, from developer.apple.com/technologies/tools/, click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

Caution: the download is almost 3 GB so it might take a while to download.

MacPorts

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at www.macports.org/install.php and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

# MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate
PATH variable for use with MacPorts.
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
# Finished adapting your PATH environment variable for use with MacPorts.

Note: If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word appropriate.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

which port
/opt/local/bin/port

If no path is returned, you need to update your PATH environment variable to include /opt/local/bin.

GNU Fortran Compiler

Note: I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

sudo port install gcc43

This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

cd /opt/local/bin
sudo ln -s gcc-mp-4.3 gcc43
sudo ln -s g++-mp-4.3 g++43
sudo ln -s gfortran-mp-4.3 gfortran

Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

which gcc43
/opt/local/bin/gcc43
which g++43
/opt/local/bin/g++43
which gfortran
/opt/local/bin/gfortran

GNU Make

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

make -v
GNU Make 3.81
Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

This program built for i386-apple-darwin10.0

If make is not found, check your PATH environment variable; my make is at /usr/bin/make.

Perl

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

Set Up Your Build Environment

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

export CC=gcc43
export CXX=g++43
export FC=gfortran
export F90=gfortran
export F77=gfortran

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

mkdir ~/source_builds

MPI (optional)

If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

Open MPI

Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from www.open-mpi.org/software/ompi/v1.4/ into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

cd ~/source_builds
tar xjf openmpi-1.4.2.tar.bz2
cd openmpi-1.4.2
./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2
. . .
make -j 4
. . .
make -j 4 check
. . .
sudo make install

IMPORTANT: Do not set --prefix to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

Caution: I have found that if you don't give the -j option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

> cd /opt/gfortransoft/openmpi
> sudo ln -s openmpi-1.4.2/bin
> sudo ln -s openmpi-1.4.2/etc
> sudo ln -s openmpi-1.4.2/include
> sudo ln -s openmpi-1.4.2/lib
> sudo ln -s openmpi-1.4.2/share

Configuring Open MPI to build static only libraries (--disable-shared) caused run-time segmentation faults. A side effect of this fact is that you will have to set the DYLD_LIBRARY_PATH environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib
> export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}

MPICH2

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

> cd ~/source_builds
> tar xzf mpich2-1.2.1p1.tar.gz
> cd mpich2-1.2.1p1
> ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1
. . .
> make -j 4
. . .
> sudo make install

IMPORTANT: Do not set --prefix to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

Caution: I have found that if you don't give the -j option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

> cd /opt/gfortransoft/mpich2
> sudo ln -s mpich2-1.2.1p1/bin
> sudo ln -s mpich2-1.2.1p1/etc
> sudo ln -s mpich2-1.2.1p1/include
> sudo ln -s mpich2-1.2.1p1/lib
> sudo ln -s mpich2-1.2.1p1/sbin
> sudo ln -s mpich2-1.2.1p1/share

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

> export PATH=/opt/gfortransoft/mpich2/bin:${PATH}

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

> echo "secretword=shh_secret" > ~/.mpd.conf
> chmod 600 ~/.mpd.conf

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

> mpd &
. . .
> make -j 4 check

If no errors are reported, we are ready to move on.

HDF5 (optional)

If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

> cd ~/source_builds
> tar xzf hdf5-1.8.4-patch1.tar.gz
> cd hdf5-1.8.4-patch1

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

hdf5_cv_mpi_complex_derived_datatype_works='no'

Once you have made this change you can configure, build, and install HDF5:

> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \
--enable-static-exec --disable-shared
. . .
> make -j 4
. . .
> make -j 4 check
. . .
> sudo make install

Caution: I have found that if you don't give the -j option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

> cd /opt/gfortransoft/serial
> sudo ln -s hdf5-1.8.4-patch1 hdf5

Note: It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

NetCDF

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

> cd ~/source_builds
> tar xzf netcdf-4.1.1.tar.gz
> cd netcdf-4.1.1

NetCDF Version 3 Format (recommended)

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

> CPPFLAGS='-DNDEBUG -DpgiFortran'
> ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx
. . .
> make -j 4
. . .
> make -j 4 check
. . .
> sudo make install

Caution: I have found that if you don't give the -j option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

> cd /opt/gfortransoft/serial
> sudo ln -s netcdf-4.1.1 netcdf3

NetCDF Version 4 Format (optional)

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, --enable-dap requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

> CPPFLAGS='-DNDEBUG -DpgiFortran'
> ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \
--prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \
--enable-netcdf-4 --disable-shared --disable-cxx
. . .
> make -j 4
. . .
> make -j 4 check
. . .
> sudo make install

Notice: If you get lots of undefined symbol references you are probably missing some of the libraries required for the OPeNDAP (--enable-dap and --with-udunits) capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

> CPPFLAGS='-DNDEBUG -DpgiFortran'
> ./configure \
--with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \
--prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \
--enable-netcdf-4 --disable-shared --disable-cxx
. . .
> make -j 4
. . .
> make -j 4 check
. . .
> sudo make install

Caution: I have found that if you don't give the -j option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

> cd /opt/gfortransoft/serial
> sudo ln -s netcdf-4.1.1 netcdf4

Download ROMS

This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

> cd ~
> mkdir ROMS
> cd ROMS
> 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.

Note: The first time you run the svn command you will be asked for your ROMS password and store it for future use.

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. For convenience, we will work with build.bash since bash is the default shell on a Mac. 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 .

• 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 your favorite text editor.

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

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

Create the Darwin-gfortran.mk file

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

cd ~/ROMS/trunk/Compilers
cp Linux-gfortran.mk Darwin-gfortran.mk
cd ~/ROMS/Projects/Upwelling

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:

• 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. 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 Mac user name):
  VARNAME = /Users/joeroms/ROMS/trunk/ROMS/External/varinfo.dat
• Save and close the ocean_upwelling.in file
• 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! 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!