Thursday, June 4, 2020

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!


1 comment:

Phil said...

Just to confirm that these instructions seem to work on the following: Windows 10 running Ubuntu 20.4 on Windows Subsystem for Linux 1 (WSL1).

I had to modify one instruction:

> ./configure --prefix=~/parflow/dependencies/hypre \
--with-MPI

On my computer, it does not seem to accept relative paths for this command for some reason. I instead used the absolute path, and before that created the directory hypre in ~/parflow/dependencies/

In addition, I missed the fact that Ubuntu 20.4 needed a different branch (as the instructions note). So this command works:

git clone --single-branch --branch master \
--recursive https://github.com/parflow/parflow.git \
~/parflow/src

Of the approx 200 tests, about 25 failed, and those that failed seemed to fail for the following reasons

-----------------

170: There are not enough slots available in the system to satisfy the 9
170: slots that were requested by the application:
170:
170: /home/mememe/parflow/install/bin/parflow
170:
170: Either request fewer slots for your application, or make more slots
170: available for use.
170:
170: A "slot" is the Open MPI term for an allocatable unit where we can
170: launch a process. The number of slots available are defined by the
170: environment in which Open MPI processes are run:
170:
170: 1. Hostfile, via "slots=N" clauses (N defaults to number of
170: processor cores if not provided)
170: 2. The --host command line parameter, via a ":N" suffix on the
170: hostname (N defaults to 1 if not provided)
170: 3. Resource manager (e.g., SLURM, PBS/Torque, LSF, etc.)
170: 4. If none of a hostfile, the --host command line parameter, or an
170: RM is present, Open MPI defaults to the number of processor cores
170:
170: In all the above cases, if you want Open MPI to default to the number
170: of hardware threads instead of the number of processor cores, use the
170: --use-hwthread-cpus option.
170:
170: Alternatively, you can use the --oversubscribe option to ignore the
170: number of available slots when deciding the number of processes to
170: launch.

---------------------

I am trying to track down what this Open MPI error is about, but perhaps we need to tweak the test command?