Installing ParFlow in OS X Yosemite

by Nick Engdahl

No matter how good or bad your eyesight may be, OS X Yosemite (version 10.10 for those of you keeping track) looks a little different than the other recent OS X versions. As it turns out, the new OS X really isn't that different under the hood when you compare it to the previous version, OS X Mavericks. In fact, if you've already got ParFlow installed on a Mac running Mavericks, it will probably keep on running with no problems at all after you upgrade to Yosemite. Of course, if you ever try to update ParFlow (which you should do from time to time), it's all going to go to you-know-where if you aren't set up correctly.

The setup procedure is very much the same as what we did for OS X Mavericks. The biggest differences are that the GCC suite and OpenMPI both have newer versions, so we'll want to use those to minimize any future compatibility issues. It'll probably be necessary to update your command line tools too, so we'll start there.

>> From here on I'm assuming you are running Yosemite <<

1. Install/update your command line tools

First, we need to make sure command line tools are installed/updated. Just because you had them installed in your old OS X version doesn't mean they're still there/working. Open a terminal window and type:

> xcode-select --install

which will install the most recent version of command line tools. Note that you do not need to install all of Xcode anymore, unless you want to. If you do, after installing Xcode, be sure to check for the command line tools just in case.

Note: If you get an error saying the tools are already installed, go ahead and move on to the next step.

2. Setup environment variables 

In the terminal, navigate to your home folder and edit your ".bash_profile" for example:

> cd ~
> vim .bash_profile

Depending on your setup, there might be a lot in this file or it might be empty. Key down to the bottom of the file, press "i" to enter insert mode, move to the end of this line and hit "return" twice to add some blank lines. We want to make sure the following lines are included in this file:

export SILO_DIR=~/ParF/silo/
export HYPRE_DIR=~/ParF/hypre/
export PARFLOW_DIR=~/ParF/parflow/

Assuming those are the paths you intend to use, if not modify as necessary. Modify or add the following lines:

export CC=gcc
export CXX=g++
export FC=gfortran
export F77=gfortran

There is one additional thing that needs to be added to this file. In the next step we're going to install the necessary compilers and the command that calls them might conflict with a symbolic link to the internal compiler Apple includes in OS X. To make sure the system uses the compilers we want it to, add the following line to the BOTTOM of the file:

export PATH=/usr/local/bin/:$PATH

This forces your Mac to look in /usr/local/bin/ first while preserving the rest of your PATH variable and any changes made to it in the rest of your .bash_profile (that's why we add this to the bottom of the file) . Hit "esc" to exit insert mode, and type ":x" followed by "return" to save the changes and exit. Back at the command prompt, type:

> source .bash_profile

which will apply the changes to your active terminal and any future terminal sessions.

Note: If you use macports or homebrew to install things on your mac, the .bash_profile might be changed when things are installed. If ParFlow was working before but stops working after you install something, double check your .bash_profile and make sure all the required lines are still there and that the PATH variable is still last.

3. Install GCC

As of this writing the latest compiled binary for the GNU compiler collection (GCC) on OS X is version 5.0, and you can download GCC from http://hpc.sourceforge.net using this link:
gcc-5.0-bin.tar.gz

This is a pre-compiled version of GCC specifically for OS X Yosemite (also Mavericks) that is very easy to install compared to building your own GCC from the source code. In your terminal window, navigate to your downloads folder (or wherever the file is saved):

> cd ~/Downloads

Your browser may have automatically unzipped the archive for you, creating a file called "gcc-5.0-bin.tar" (but if not type gunzip gcc-5.0-bin.tar.gz to unzip the archive). In your terminal window, execute the following:

> sudo tar -xvf gcc-5.0-bin.tar -C /

which installs GCC to "/usr/local/". Check the version by typing "gfortran -v" and  you'll see something like this among the output lines:

gcc version 5.0.0 20141012 (experimental) (GCC)

telling us the version we just installed is actually recognized. Now type "gcc -v" and see what comes back. If you see the same thing as before, you're in good shape and can move on to the next step

...but if you see something like this in the output:

Apple LLVM version 6.0 (clang-600.0.51) (based on LLVM 3.4svn)

Apple's internal C-compiler "clang" is still being used instead of the GCC we just installed. Make sure that PATH line from step 2 is correct, and try restarting and reinstalling GCC if it still doesn't recognize the GCC compiler. So far, this step has been pretty smooth for most people, so let us know if something keeps going wrong.

4. Install or update OpenMPI

If you've compiled ParFlow before, you probably followed one of the last two sets of instructions posted on the blog. If you did, you already placed all of your required code in a folder called "ParF". If not, go ahead and create one now. In a terminal window, type the following:

> cd ~

> mkdir ParF

> cd ParF

By now, there is sure to be a newer version of OpenMPI (this is what allows ParFlow to run in parallel) than the one you've been using so bite the bullet and download the latest version; as of this writing it's 1.8.3. Assuming you're in the "ParF" folder, these next few lines will download OpenMPI directly in to the "ParF" folder then install it:

> curl "http://www.open-mpi.org/software/ompi/v1.8/downloads/openmpi-1.8.3.tar.gz" -o "openmpi-1.8.3.tar.gz"
> tar -xvf openmpi-1.8.3.tar.gz
> cd openmpi-1.8.3
> ./configure --prefix=/usr/local/
> sudo make all install

On a fairly new Retina MacBookPro all of that took about 10 minutes but it might take a lot longer depending on your internet connection and system setup. Be patient. As long as the screen doesn't display an error message the next time you see the command prompt, the installation should be successful. If you want to remove the "openmpi-1.8.3.tar.gz" you can.

Note: If you're not familiar with "curl" it's the OS X equivalent of "wget". If you haven't heard of either, they're both direct download commands so you don't have to use a web browser.


If you have an old version of OpenMPI you want to completely wipe out before installing the new version, look at the blog post for OS X Mavericks for those details. Most people won't take the time to do that so we'll leave it out this time. 

5. Download and install SILO

Navigate to "ParF", download SILO and extract the archive with:

> cd ~/ParF
> curl "https://wci.llnl.gov/codes/silo/silo-4.9.1/silo-4.9.1.tar.gz" -o "silo-4.9.1.tar.gz"
> tar -xvf silo-4.9.1.tar.gz

This is the same version we used for the Mavericks If you have an existing folder named silo, remove it (i.e. "rm -rf silo") or rename it (i.e. "mv silo silo_old"), then complete the setup with:

> mv silo-4.9.1 silo
> cd silo
> ./configure --disable-silex
> make install
> cd ..

If the setup was successful, near the end of the output you'll see a "NOTICE:" about the test cases not being compiled by default. If you're not familiar, SILO is a just a particular type of file format that ParFlow can use.

6. Download and install HYPRE

Hypre (the numerical solver library) hasn't been update in a while so the current version is still 2.9.0b. Assuming you're back in the folder "ParF", download, extract, and install HYPRE with:

> curl "http://computation.llnl.gov/casc/hypre/download/hypre-2.9.0b.tar.gz" -o "hypre-2.9.0b.tar.gz"
> tar -xvf hypre-2.9.0b.tar.gz
> mv hypre-2.9.0b hypre
> cd hypre/src
> ./configure --prefix=$HYPRE_DIR
> make install

It might take a little time to install, but much less than OpenMPI took. HYPRE should now be installed.

Note: If you are changing versions of HYPRE, the method for removing the old version is very similar to what's outlined for OpenMPI in the Mavericks post. Just switch out the OpenMPI paths for the HYPRE path.

7. Install ParFlow

Download the source code and move it to a folder called "parflow" within the "ParF" directory (if you already have ParFlow, navigate to "$PARFLOW_DIR/pfsimulator" and reconfigure). One way of getting ParfFow is with the "curl" command. The current release is 693, but you can always check Reed Maxwell's download page for a newer version. To get the ParFlow source, execute the following:

> cd ~/ParF
> curl "http://inside.mines.edu/%7Ermaxwell/parflow.r693.tar.gz" -o "parflow.tar.gz"
> tar -xvf parflow.tar.gz
> cd parflow/pfsimulator
> ./configure --prefix=$PARFLOW_DIR --with-clm --enable-timing --with-silo=$SILO_DIR --with-hypre=$HYPRE_DIR --with-amps=mpi1 --with-amps-sequential-io

Now, a minor bug in the Makefile script (which will be fixed eventually) means that we need to modify the Makefile to fix a few errors or else the installation will fail.

Within the "config" folder, there exists a file called "Makefile.config"; locate it and open it in the editor of your choice. The changes we need to make happen in the LDLIBS specification near the bottom of the file. There are three changes to make: 1) add a "-l" in front of "gfortran", 2) remove the stray "-l", and 3) remove the space between a "-l" and "gfortran". Each change is highlighted in red below:

BEFORE:

LDLIBS        = $(LDLIBS_EXTRA)  -lHYPRE  -lsilo    -lmpi  gfortran -L/usr/local/lib/gcc/x86_64-apple-darwin13.4.0/5.0.0/../../.. -L/usr/local/lib/gcc/x86_64-apple-darwin13.4.0/5.0.0  -l -lgfortran -lSystem -lgcc_ext.10.5 -lgcc -lquadmath -lm -lm -lm  -lgfortran -lquadmath -lm  -lgfortran -lquadmath -lm -l gfortran -lgfortran -lSystem -lgcc_ext.10.5 -lgcc -lquadmath -lm -lm

AFTER:

LDLIBS        = $(LDLIBS_EXTRA)  -lHYPRE  -lsilo    -lmpi  -lgfortran -L/usr/local/lib/gcc/x86_64-apple-darwin13.4.0/5.0.0/../../.. -L/usr/local/lib/gcc/x86_64-apple-darwin13.4.0/5.0.0  -lgfortran -lSystem -lgcc_ext.10.5 -lgcc -lquadmath -lm -lm -lm  -lgfortran -lquadmath -lm  -lgfortran -lquadmath -lm -lgfortran -lgfortran -lSystem -lgcc_ext.10.5 -lgcc -lquadmath -lm -lm

Some of the paths might be slightly different on your machine, but the changes should be the same. This line cannot have any stray "-l" characters or anything that doesn't begin with "-l" or "-L", so if you're getting additional errors, check the LDLIBS line for any of those. Save "Makefile.config", make sure you're in "~/ParF/parflow/pfsimulator" and type

> make install

You'll see lots of things flash by, including lots of warnings, but at the end you should see:

Installing parflow to /Users/*USERNAME*/ParF/parflow

which means pfsimulator is installed. Of course, *USERNAME* will be your actual username and not that text...

8. Install pftools

We also need to install PFtools so from "~/ParF/parflow/pfsimulator" do the following:

> cd ../pftools
> ./configure --prefix=$PARFLOW_DIR --with-clm --enable-timing --with-silo=$SILO_DIR --with-hypre=$HYPRE_DIR --with-amps=mpi1 --with-amps-sequential-io

You need to make the exact same change to the "Makefile.config" in the "pftools/config" folder that you did for pfsimulator. After making that change, type "make install" to finish the installation.

9. Test the installation

It would be very bad to assume that ParFlow is going to play nice just because you didn't get any error messages. To run all of the included ParFlow test cases, navigate to the "test" folder:

> cd $PARFLOW_DIR/test
> make check

Some of the tests will indicate failures but that has to do with specific processor topologies that don't exist on your computer. As long as most are passing, you're probably in good shape.

If you just want to run one test, try seeing if default_richards.tcl passes:

> tclsh default_richards.tcl 1 1 1

Hopefully that returns:

default_richards : PASSED

That means it worked, at least for that test, and it is now time for great rejoicing. Within "parflow/test", type "make clean" to remove the outputs of the tests and that's all there is to the installation.

10. Recompiling a ParFlow installation

If you change something within the ParFlow source code, or update to a newer version, you don't need to redo every single step in this guide. ParFlow contains two "cleaning" scripts that remove some of the files from the configuration and installation steps. If you navigate to the "pfsimulator" folder and type:

> make clean

this will remove the ParFlow executable and the object files created during the installation but, critically, you will not need to re-run the configure script. ParFlow can be reinstalled by typing:

> make install

It's fast and it's easy, so that's the method most people should use for recompiling.


The second option is to type (from"pfsimulator"):

> make veryclean

but that pretty much removes everything that isn't part of the source code distribution. You will have to re-run the configure script and remove the stray "-l" characters in "Makefile.config" again before you'll be able to install successfully again.

Both of these also work for PF Tools.

11. What if Professor Farnsworth walks in the room while I'm installing?

"Good news everyone", you probably fell asleep in front of the TV while reading these instructions. If not, you're hallucinating from a lack of fresh air and should immediately go outside.