Installing ParFlow on Ubuntu LTS

Since we have been working with ParFlow on Ubuntu, we thought that it might be helpful to provide a guide for others to install ParFlow on Ubuntu systems. The following directions are to install the current version of ParFlow on the two most recent Ubuntu LTS releases, 18.04 and 20.04.

1) Setup development packages on Linux

First, you need to download the new package information and install some new packages. Copy and paste the following in your command line:

   sudo apt-get update 

   sudo apt-get install \ 

     build-essential \ 

     curl \ 

     git \ 

     gfortran \ 

     libopenblas-dev \ 

     liblapack-dev \ 

     openssh-client \ 

     openssh-server \ 

     openmpi-bin \ 

     libopenmpi-dev \ 

     tcl-dev \ 

     tk-dev 

This may take a little while. Note: you may not need the sudo command if you are running with root privileges.

2) Create the ParFlow directory and its components

Next, you need to create a directory for ParFlow with a few subfolders. This example installs ParFlow and all its dependencies in the home (~) folder, although you can change this to whatever you’d like.

   mkdir -p ~/parflow/build \

     ~/parflow/dependencies/cmake \

     ~/parflow/dependencies/hypre-src 

3) Fetch the dependencies (cmake and hypre)

Let’s start with downloading cmake (3.17.3 being the current version):

   cd ~/parflow/dependencies/cmake 

   curl -L https://cmake.org/files/v3.17/cmake-3.17.3-Linux-x86_64.tar.gz \

     | tar --strip-components=1 -xzv 

Once that is completed, you can install hypre (2.19.0 being the current version):

   cd ~/parflow/dependencies/hypre-src 

   curl -L https://github.com/hypre-space/hypre/archive/v2.19.0.tar.gz \

     | tar --strip-components=1 -xzv 

   cd src 

   ./configure --prefix=~/parflow/dependencies/hypre \

     --with-MPI 

   make install 

4) Download and build ParFlow

You can then download ParFlow from GitHub using the commands below. The current release as of this post is v3.6.0. Note: Ubuntu 20.04 has a newer version of tcl that is not compatible with the current release. If you are installing ParFlow on Ubuntu 20.04, replace the “v3.6.0” with “master” to clone the master branch instead. The current master branch of ParFlow is compatible with the newer version of tcl on Ubuntu 20.04.

   git clone --single-branch --branch v3.6.0 \

     --recursive https://github.com/parflow/parflow.git \

     ~/parflow/src 

Enter the following in your command line to build ParFlow.

   ~/parflow/dependencies/cmake/bin/cmake \
     -S ~/parflow/src \
     -B ~/parflow/build \
     -D PARFLOW_AMPS_LAYER=mpi1 \
     -D PARFLOW_AMPS_SEQUENTIAL_IO=TRUE \
     -D HYPRE_ROOT=~/parflow/dependencies/hypre \
     -D PARFLOW_ENABLE_TIMING=TRUE \
     -D PARFLOW_HAVE_CLM=TRUE

   ~/parflow/dependencies/cmake/bin/cmake --build \
     ~/parflow/build

   ~/parflow/dependencies/cmake/bin/cmake --install \
     ~/parflow/build --prefix ~/parflow/install 

5) Create an environment file

Here, you will create an environment file “env.sh” to store the ParFlow directory, making it easier to reference ParFlow when you want to run it later. Type the following:

   echo export PARFLOW_DIR=~/parflow/install \

     >> ~/parflow/env.sh 

With that environment file, you can use ParFlow from anywhere by sourcing it, as shown:

   source ~/parflow/env.sh 

6) Test ParFlow

Here, you will create an environment file “env.sh” which points to the necessary directories for keeping the components necessary for running ParFlow. Enter the following:

Hopefully you haven’t gotten any errors at this point and you have installed ParFlow successfully. To test ParFlow, source the environment file above and then type:

   cd ~/parflow/build/ 

   ~/parflow/dependencies/cmake/bin/ctest -VV 

This will run the series of tests to make sure your install of ParFlow is working correctly. As of this writing, nine tests fail that are attempting to reference .silo files (note that this installation guide does not install Silo). We are currently addressing this issue. The tests that will fail due to the bug are: water_balance_x.hardflow.nojac.tcl (all topologies), water_balance_x.hardflow.jac.tcl (all topologies), and impes.plinear.tcl.

Conclusion

Congratulations, you now have ParFlow on your system! The ParFlow executable is located in ~/parflow/src/pfsimulator/, and the pftools are located in ~/parflow/src/pftools/. Before running a ParFlow script, you may have to re-source your environment file by typing in “source ~/parflow/env.sh” as shown above.

These install instructions are combined into shell scripts within the scripts folder on this GitHub repo. The install directions above are divided into two scripts: “01_packages.sh” executes step 1, and “02_parflow.sh” executes steps 2 through 5. You will have to execute the testing on your own. The Readme file provides directions for how to use these scripts, as well as instructions and files for building ParFlow within an Ubuntu Docker image.

For more information, please refer to the ParFlow manual PDF located in ~/parflow/src/ and ParFlow’s GitHub page (https://github.com/parflow/parflow). Happy modeling!