ROMS Mac Snow Leopard

From WikiROMS
Revision as of 16:08, 24 September 2010 by Robertson (talk | contribs) (Created page with '<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div> <center>{{warning}}<span class="red">THIS PAGE IS UNDER CONSTRUCTION</span>{{warning}}</center> Sp…')
(change visibility) (diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search
Tutorial: Installing ROMS on Mac OS X Snow Leopard


WarningTHIS PAGE IS UNDER CONSTRUCTIONWarning


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.


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

Install Supporting Software

NoteNote: 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 as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

WarningCaution: 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.

NoteNote: 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.

> 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

NoteNote: 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

Warning 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

NoteNotice 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
/usr/local/bin/gcc43
> which g++43
/usr/local/bin/g++43
> which gfortran
/usr/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.

WarningCaution: GNU make 3.82 is available from MacPorts but is untested with ROMS and may require changes to the makefile depending on how new your code is.

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.

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)

Note 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

WarningIMPORTANT: 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.

NoteCaution: 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.)

> 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

WarningIMPORTANT: 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.

NoteCaution: 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.)

> export PATH=/opt/gfrotransoft/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.

NetCDF

Download netcdf-3.6.3.tar.gz from www.unidata.ucar.edu/software/netcdf (down on the lower right part of the page). This is the source code for NetCDF 3, which you are going to compile on your machine using gfortran, the same compiler you will use for compiling ROMS. You could also move up to NetCDF 4, but this requires installing HDF5. Perhaps those instructions will be added later. Put the tar file in ~/src, extract it, and go into the directory netcdf-3.6.3 that is created. Also, make sure that the directory /opt exists on your machine. Then execute (the second command has a capital "o" not a zero):

export FC=gfortran
export FFLAGS='-O3'
./configure --prefix=/opt/gfortran/serial/netcdf3
make
make check
sudo make install

Subversion (SVN)

Get subversion 1.5.2-2 from www.collab.net/downloads/community and follow the standard installation.

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.

NoteNote: 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:

  • 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. 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 = /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! 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!

Retrieved from "https://www.myroms.org/wiki/index.php?title=ROMS_Mac_Snow_Leopard&oldid=4314"