ParFlow

ParFlow is an open-source, modular, parallel watershed flow model. It includes fully-integrated overland flow, the ability to simulate complex topography, geology and heterogeneity and coupled land-surface processes including the land-energy budget, biogeochemistry and snow (via CLM). It is multi-platform and runs with a common I/O structure from laptop to supercomputer. ParFlow is the result of a long, multi-institutional development history and is now a collaborative effort between CSM, LLNL, UniBonn and UCB. ParFlow has been coupled to the mesoscale, meteorological code ARPS and the NCAR code WRF.

For an overview of the major features and capabilities see the following paper: Simulating coupled surface–subsurface flows with ParFlow v3.5.0: capabilities, applications, and ongoing development of an open-source, massively parallel, integrated hydrologic model.

An online version of the users manual is available on Read the Docks:Parflow Users Manual. The manual contains additional documentation on how to use ParFlow and setup input files. A quick start is included below. A PDF version is available at Parflow Users Manual PDF.

Citing Parflow

If you want the DOI for a specific release see: Zendo

A generic DOI that always links to the most current release :

If you use ParFlow in a publication and wish to cite a paper reference please use the following that describe model physics:

Ashby S.F. and R.D. Falgout, Nuclear Science and Engineering 124:145-159, 1996
Jones, J.E. and C.S. Woodward, Advances in Water Resources 24:763-774, 2001
Kollet, S.J. and R.M. Maxwell, Advances in Water Resources 29:945-958, 2006
Maxwell, R.M. Advances in Water Resources 53:109-117, 2013

If you use ParFlow coupled to CLM in a publication, please also cite two additional papers that describe the coupled model physics:

Maxwell, R.M. and N.L. Miller, Journal of Hydrometeorology 6(3):233-247, 2005
Kollet, S.J. and R.M. Maxwell, Water Resources Research 44:W02402, 2008

Additional Parflow resources

The ParFlow website has additional information on the project:

Parflow Web Site

You can join the Parflow Google Group/mailing list to communicate with the Parflow developers and users. In order to post you will have to join the group, old posts are visible without joining:

Parflow-Users

The most recent build/installation guides are now located on the Parflow Wiki:

Parflow Installation guides

A Parflow blog is available with notes from users on how to use Parflow:

Parflow Blog

To report Parflow bugs, please use the GitHub issue tracker for Parflow:

Parflow Issue Tracker

Quick Start on Unix/Linux

Important note for users that have built with Autoconf, the CMake configure process is one step by default. Most builds of of ParFlow are on MPP architectures or workstations where the login node and compute nodes are same architecture the default build process builds both the ParFlow executable and tools with the same compilers and libraries in one step. This will hopefully make building easier for the majority of users. It is still possible to build the two components separately; see instruction below for building pftools and pfsimulator separately.

CMake supports builds for several operating systems and IDE tools (like Visual Studio on Windows and XCode on MacOS). The ParFlow team has not tested building on platforms other than Linux; there will likely be some issues on other platforms. The ParFlow team welcomes bug reports and patches if you attempt other builds.

Step 1: Setup

Decide where to install ParFlow and associated libraries.

Set the environment variable PARFLOW_DIR to the chosen location:

For bash:

   export PARFLOW_DIR=/home/snoopy/parflow

For csh and tcsh:

   setenv PARFLOW_DIR /home/snoopy/parflow

Step 2: Extract the Source

Extract the source files from the compressed tar file.

Obtain the release from the ParFlow GitHub web site:

https://github.com/parflow/parflow/releases

and extract the release. Here we assume you are building in new subdirectory in your home directory:

   mkdir ~/parflow
   cd ~/parflow
   tar -xzvf ../parflow-<version>.tar.gz

Note the ParFlow tar file will be have a different name based on the version number.

Step 3: Running CMake to configure ParFlow

CMake is a utility that sets up makefiles for building ParFlow. CMake allows setting of compiler to use and other options. First create a directory for the build. It is generally recommend to build outside of the source directory to make it keep things clean. For example, restarting a failed build with a separate build directory simply involves removing the build directory.

Building with the ccmake GUI

You can control build options for ParFlow using the ccmake GUI.

   mkdir build
   cd build
   ccmake ../parflow-<version>

First press c to generate an initial configuration. Hereafter, at a minimum, you will want to set the CMAKE_INSTALL_PREFIX value to the same thing as PARFLOW_DIR was set to above. Other variables should be set as desired.

After setting a variable c will configure ParFlow. When you are completely done setting configuration options, use g to generate the configuration and exit ccmake.

If you are new to CMake, the creators of CMake provide some additional ccmake usage notes here:

https://cmake.org/resources/

Building with the cmake command line

CMake may also be configured from the command line using the cmake command. Instructions to build with different accelerator backends are found from the following documents: CUDA, KOKKOS, OpenMP. The default will configure a sequential version of ParFlow using MPI libraries. CLM is being enabled.

   mkdir build
   cd build
   cmake ../parflow-<version> \
     -DCMAKE_INSTALL_PREFIX=${PARFLOW_DIR} \
     -DPARFLOW_HAVE_CLM=ON

If TCL is not installed in the standard locations (/usr or /usr/local) you need to specify the path to the tclsh location:

    -DTCL_TCLSH=${PARFLOW_TCL_DIR}/bin/tclsh8.6

Building a parallel version of ParFlow requires the communications layer to use must be set. The most common option will be MPI. Here is a minimal example of an MPI build with CLM:

   mkdir build
   cd build
   cmake ../parflow \
     -DCMAKE_INSTALL_PREFIX=${PARFLOW_DIR} \
     -DPARFLOW_HAVE_CLM=ON \
     -DPARFLOW_AMPS_LAYER=mpi1

Here is a more complex example where location of various external packages are being specified and some features are being enabled:

   mkdir build
   cd build
   cmake ../parflow-<version> \
     -DPARFLOW_AMPS_LAYER=mpi1 \
     -DHYPRE_ROOT=${PARFLOW_HYPRE_DIR} \
     -DHDF5_ROOT=${PARFLOW_HDF5_DIR} \
     -DSILO_ROOT=${PARFLOW_SILO_DIR} \
     -DCMAKE_BUILD_TYPE=Debug \
     -DPARFLOW_ENABLE_TIMING=TRUE \
     -DPARFLOW_HAVE_CLM=ON \
     -DCMAKE_INSTALL_PREFIX=${PARFLOW_DIR}

Step 4: Building and installing

Once CMake has configured and created a set of Makefiles; building is easy:

   cd build
   make
   make install

Step 5: Running a sample problem

If all went well a sample ParFlow problem can be run using:

   cd parflow-<version>/test/tcl
   tclsh default_single.tcl 1 1 1

Note that the environment variable PARFLOW_DIR must be set for this to work and it assumes tclsh is in your path. Make sure to use the same TCL shell as was used in the cmake configure.

Some parallel machines do not allow launching a parallel executable from the login node; you may need to run this command in a batch file or by starting a parallel interactive session.

Building documentation

User Manual

An online version of the user manual is also available on Read the Docks:Parflow Users Manual, a PDF version is available at Parflow Users Manual PDF.

Generating the user manual in HTML

An HTML version of the user manual for Parflow may be built using:

cd docs/user_manual
pfpython -m pip install -r requirements.txt

make html

The main HTML page created at _build/html/index.html. Open this using a browser. On MacOS:

open _build/html/index.html

or a browser if on Linux:

firefox _build/html/index.html

Generating the user manual in PDF

An HTML version of the user manual for Parflow may be built using:

cd docs/user_manual
pfpython -m pip install -r requirements.txt

make latexpdf

This command is currently failing for a number of users, possibly due to old LaTex installs. We are currently investigating.

Code documentation

Parflow is moving to using Doxygen for code documentation. The documentation is currently very sparse.

Adding the -DPARFLOW_ENABLE_DOXYGEN=TRUE option to the CMake configure will enable building of the code documentation. After CMake has been run the Doxygen code documentation is built with:

   cd build
   make doxygen

HTML pages are generated in the build/docs/doxygen/html directory.

Parflow

Install / Use

README