ParFlow
An open-source, modular, parallel watershed flow model.
https://github.com/parflow/parflow
Category: Hydrosphere
Sub Category: Freshwater and Hydrology
Keywords from Contributors
open-science hydrology vtk climate earth-system-model
Last synced: about 20 hours ago
JSON representation
Repository metadata
Parflow is an open-source parallel watershed flow model.
- Host: GitHub
- URL: https://github.com/parflow/parflow
- Owner: parflow
- License: other
- Created: 2016-05-25T03:35:57.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2026-11-16T20:47:36.000Z (5 days ago)
- Last Synced: 2026-11-20T15:02:16.781Z (about 20 hours ago)
- Language: C
- Homepage: http://parflow.org
- Size: 108 MB
- Stars: 215
- Watchers: 21
- Forks: 131
- Open Issues: 153
- Releases: 16
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
README.md
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:
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:
The most recent build/installation guides are now located on the Parflow Wiki:
A Parflow blog is available with notes from users on how to use Parflow:
To report Parflow bugs, please use the GitHub issue tracker for Parflow:
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:
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 keys documentation
cmake \
-S ./parflow \
-B ./build-docker \
-D BUILD_TESTING=OFF \
-D PARFLOW_ENABLE_TOOLS=OFF \
-D PARFLOW_ENABLE_SIMULATOR=OFF \
-D PARFLOW_ENABLE_KEYS_DOC=ON \
-D PARFLOW_ENABLE_PYTHON=ON \
cd ./build-docker && make ParFlowKeyDoc
On MacOS the key documentation may be viewed with open or use a browser to open the index.html file:
open ./build-docker/docs/user_manual/build-site/index.html
Configure options
A number of packages are optional for building ParFlow. The optional
packages are enabled by PARFLOW_ENABLE_ value to be TRUE or
setting the _ROOT= value. If a package is enabled
with the using an ENABLE flag CMake will attempt to find the package
in standard locations. Explicitly setting the location using the ROOT
variable for a package automatically enables it, you don't need to
specify both values.
Here are some common packages:
- SIMULATOR: The simulator is actually the core of ParFlow as it represent the simulation code.
- DOCKER: This provide helpers for building docker images with ParFlow enable in them.
- DOXYGEN: Doxygen and building of code documentation (C/Fortran).
- ETRACE: builds ParFlow with etrace
- HDF5: builds ParFlow with HDF5 which is required for the NETCDF file format.
- HYPRE: builds ParFlow with Hypre
- KEYS_DOC: builds documentation (rst files) from key definitions.
- LATEX: enables LaTEX and building of documentation (Manual PDF)
- NETCDF: builds ParFlow with NetCDF. (If ON, HDF5 is required)
- PROFILING: This allow to enable extra code execution that would enable code profiling.
- TIMING: enables timing of key Parflow functions; may slow down performance
- TOOLS: enables building of the Parflow tools (TCL version)
- VALGRIND: builds ParFlow with Valgrind support
- PYTHON: This is to enable you to build the Python version of pftools.
- SILO: builds ParFlow with Silo.
- SLURM: builds ParFlow with SLURM support (SLURM is queuing system on HPC).
- SUNDIALS: builds ParFlow with SUNDIALS
- SZLIB: builds ParFlow with SZlib compression library
- ZLIB: builds ParFlow with Zlib compression library
KINSOL Solver
There are two compile options for the KINSOL solver used by ParFlow.
The current default is to use an old version of KINSOL that is
embedded in ParFlow. The newer option is to use KINSOL from the
SUNDIALS package. To use the SUNDIALS package you will need to have a
SUNDIALS install that includes KINSOL and specify during the CMake configuration:
-DSUNDIALS_ROOT=<directory of the location of sundials install>
The GitHub repository for SUNDIALS
has downloads and build instructions.
How to specify the launcher command used to run MPI applications
There are multiple ways to run MPI applications such as mpiexec,
mpirun, srun, and aprun. The command used is dependent on the job
submission system used. By default CMake will attempt to determine an
appropriate tool; a process that does not always yield the correct result.
There are several ways to modify the CMake guess on how applications
should be run. At configure time you may override the MPI launcher
using:
-DMPIEXEC="<launcher-name>"
-DMPIEXEC_NUMPROC_FLAG="<flag used to set number of tasks>"
An example for mpiexec is -DMPIEXEC="mpiexec" -DMPIEXEC_NUMPROC_FLAG="-n".
The ParFlow script to run MPI applications will also include options
specified in the environment variable PARFLOW_MPIEXEC_EXTRA_FLAGS on
the MPI execution command line. For example when running with OpenMPI
on a single workstation the following will enable running more MPI
tasks than cores and disable the busy loop waiting to improve
performance:
export PARFLOW_MPIEXEC_EXTRA_FLAGS="--mca mpi_yield_when_idle 1 --oversubscribe"
Last the TCL script can explicitly set the command to invoke for
running ParFlow. This is done by setting the Process.Command key in
the input database. For example to use the mpiexec command and
control the cpu set used the following command string can be used:
pfset Process.Command "mpiexec -cpu-set 1 -n %d parflow %s"
The '%d' will be replaced with the number of processes (computed using
the Process.Topology values : P * Q * R) and the '%s' will be replaced
by the name supplied to the pfrun command for the input database name.
The following shows how the default_single.tcl script could be
modified to use the custom command string:
pfset Process.Command "mpiexec -cpu-set 1 -n %d parflow %s"
pfrun default_single
pfundist default_single
Building simulator and tools support separately
This section is for advanced users running on heterogeneous HPC architectures.
ParFlow is composed of two main components that maybe configured and
built separately. Some HPC platforms are heterogeneous with the login
node being different than the compute nodes. The ParFlow system has
an executable for the simulator which needs to run on the compute
nodes and a set of TCL libraries used for problem setup that can be
run on the login node for problem setup.
The CMake variables PARFLOW_ENABLE_SIMULATOR and PARFLOW_ENABLE_TOOLS
control which component is configured. By default both are TRUE. To
build separately use two build directories and run cmake in each to
build the simulator and tools components separately. By specifying
different compilers and options for each, one can target different
architectures for each component.
Using Docker
ParFlow includes a Docker file for configuring a Docker image for
running ParFlow.
Pre-built Docker Image
A Docker image for ParFlow is available on Docker hub. See the
following section for how to run the Docker image. The Docker
latest image is automatically downloaded by Docker when run.
Running ParFlow with Docker
The https://github.com/parflow/docker repository contains an example
setup for running ParFlow in a Docker instance. See the README.md
file in this repository for more information.
Building the Docker image
If you want to build a Docker image, the build script in the bin
directory will build an image using the latest ParFlow source in the
master branch. If you want to build a different version of ParFlow
you will need to modify the 'Dockerfile' file.
Unix/Linux/MacOS
./bin/docker-build.sh
Windows
.\bin\docker-build.bat
Building the Docker image with CMake (expirmental not supported)
Rather than building ParFlow on your computer, you can use the build
system to create a container and build ParFlow in it.
cmake \
-S ./parflow \
-B ./build-docker \
-D BUILD_TESTING=OFF \
-D PARFLOW_ENABLE_TOOLS=OFF \
-D PARFLOW_ENABLE_SIMULATOR=OFF \
-D PARFLOW_ENABLE_DOCKER=ON
cd ./build-docker && make DockerBuildRuntime
For more information look into our Docker Readme
Release
Copyright (c) 1995-2021, Lawrence Livermore National Security LLC.
Produced at the Lawrence Livermore National Laboratory.
Written by the Parflow Team (see the CONTRIBUTORS file)
CODE-OCEC-08-103. All rights reserved.
Parflow is released under the GNU General Public License version 2.1
For details and restrictions, please read the LICENSE.txt file.
Owner metadata
- Name: Parflow
- Login: parflow
- Email:
- Kind: organization
- Description: ParFlow is an integrated, parallel watershed model that makes use of high-performance computing to simulate surface and subsurface fluid flow.
- Website: https://www.parflow.org
- Location:
- Twitter:
- Company:
- Icon url: https://avatars.githubusercontent.com/u/19506192?v=4
- Repositories: 5
- Last ynced at: 2026-11-15T12:39:13.531Z
- Profile URL: https://github.com/parflow
GitHub Events
Total
- Create event: 16
- Delete event: 16
- Fork event: 18
- Gollum event: 13
- Issue comment event: 73
- Issues event: 36
- Member event: 12
- Pull request event: 129
- Pull request review comment event: 77
- Pull request review event: 97
- Push event: 142
- Release event: 3
- Watch event: 29
Last Year
- Create event: 8
- Delete event: 12
- Fork event: 2
- Issue comment event: 19
- Issues event: 8
- Pull request event: 23
- Pull request review comment event: 12
- Pull request review event: 8
- Push event: 65
- Watch event: 3
Committers metadata
Last synced: 2 days ago
Total Commits: 986
Total Committers: 57
Avg Commits per committer: 17.298
Development Distribution Score (DDS): 0.372
Commits in past year: 57
Committers in past year: 14
Avg Commits per committer in past year: 4.071
Development Distribution Score (DDS) in past year: 0.684
| Name | Commits | |
|---|---|---|
| Steven Smith | s****4@l****v | 619 |
| Reed Maxwell | r****l@m****u | 130 |
| Ian Ferguson | i****n@u****v | 31 |
| gartavanis | 3****s | 26 |
| reedmaxwell | r****l@p****u | 25 |
| Paul Rigor | k****r | 13 |
| Muhammad Fahad Azeemi | m****d@f****e | 11 |
| Nick Engdahl | n****l@w****u | 9 |
| Fabian Gasper | f****r@f****e | 8 |
| Jaro Hokkanen | j****n@f****e | 7 |
| Calla Chennault | c****t@g****m | 7 |
| Patrick Avery | p****y@k****m | 6 |
| Manuel Assunção | m****o@h****m | 6 |
| Juan S. Acero Triana | 5****t | 6 |
| Andrew Bennett | b****r@g****m | 5 |
| Sebastien Jourdain | s****n@k****m | 5 |
| grapp1 | 4****1 | 5 |
| Laura Condon | l****n@e****u | 5 |
| dependabot[bot] | 4****] | 4 |
| Ketan Kulkarni | k****i@g****m | 3 |
| Vineet Bansal | v****l@p****m | 3 |
| aureliayang | 3****g | 3 |
| xy124 | x****4 | 3 |
| Joe Beisman | j****n@g****m | 2 |
| Laura Condon | l****n@m****u | 2 |
| John Williams | j****i@g****m | 2 |
| alanquits | g****e@g****m | 2 |
| westb2 | w****2@r****u | 2 |
| elena-leo | 7****o | 2 |
| Rob de Rooij | r****j@u****u | 2 |
| and 27 more... | ||
Committer domains:
- fz-juelich.de: 4
- kitware.com: 3
- llnl.gov: 3
- uni-bonn.de: 2
- mymail.mines.edu: 2
- hulten.org: 1
- lanl.gov: 1
- ucar.edu: 1
- ufl.edu: 1
- rpi.edu: 1
- email.arizona.edu: 1
- wsu.edu: 1
- princeton.edu: 1
- usbr.gov: 1
- mines.edu: 1
Issue and Pull Request metadata
Last synced: 5 days ago
Total issues: 251
Total pull requests: 471
Average time to close issues: 3 months
Average time to close pull requests: 19 days
Total issue authors: 65
Total pull request authors: 53
Average comments per issue: 1.39
Average comments per pull request: 0.78
Merged pull request: 402
Bot issues: 0
Bot pull requests: 4
Past year issues: 15
Past year pull requests: 49
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 24 days
Past year issue authors: 3
Past year pull request authors: 15
Past year average comments per issue: 0.73
Past year average comments per pull request: 1.0
Past year merged pull request: 26
Past year bot issues: 0
Past year bot pull requests: 1
Top Issue Authors
- smithsg84 (133)
- jsacerot (11)
- tikoh-station (10)
- xy124 (9)
- elappala (4)
- vineetbansal (4)
- alanquits (3)
- cozisco (3)
- mvhulten (3)
- surak (3)
- kulkarni1 (2)
- nbengdahl (2)
- chrisreidy (2)
- kvrigor (2)
- wrs827 (2)
Top Pull Request Authors
- smithsg84 (250)
- reedmaxwell (35)
- gartavanis (30)
- kvrigor (15)
- jourdain (8)
- callachennault (8)
- hokkanen (7)
- mfahdaz (7)
- jsacerot (7)
- psavery (6)
- tikoh-station (6)
- arbennett (6)
- nbengdahl (6)
- grapp1 (5)
- kulkarni1 (5)
Top Issue Labels
- enhancement (12)
- bug (10)
- question (2)
Top Pull Request Labels
- enhancement (4)
- dependencies (4)
- bug (2)
- python (1)
Package metadata
- Total packages: 2
-
Total downloads:
- pypi: 550 last-month
- Total docker downloads: 64
- Total dependent packages: 2 (may contain duplicates)
- Total dependent repositories: 8 (may contain duplicates)
- Total versions: 41
- Total maintainers: 7
proxy.golang.org: github.com/parflow/parflow
- Homepage:
- Documentation: https://pkg.go.dev/github.com/parflow/parflow#section-documentation
- Licenses: other
- Latest release: v3.15.0+incompatible (published 7 months ago)
- Last Synced: 2026-11-19T14:32:05.148857Z (2 days ago)
- Versions: 18
- Dependent Packages: 0
- Dependent Repositories: 0
-
Rankings:
- Dependent packages count: 5.395%
- Average: 5.576%
- Dependent repos count: 5.758%
pypi.org: pftools
A Python package creating an interface with the ParFlow hydrologic model.
- Homepage: https://github.com/parflow/parflow/tree/master/pftools/python
- Documentation: https://parflow.readthedocs.io/en/latest/
- Licenses: BSD
- Latest release: 1.3.15 (published 7 months ago)
- Last Synced: 2026-11-19T14:32:11.037850Z (2 days ago)
- Versions: 23
- Dependent Packages: 2
- Dependent Repositories: 8
- Downloads: 550 Last month
- Docker Downloads: 64
-
Rankings:
- Docker downloads count: 3.836%
- Forks count: 4.848%
- Dependent repos count: 5.252%
- Stargazers count: 5.943%
- Average: 6.48%
- Dependent packages count: 7.306%
- Downloads: 11.695%
- Maintainers (7)
Dependencies
- PyYAML ==5.4
- Sphinx >=4.0.0
- sphinx-rtd-theme *
- sphinxcontrib-bibtex *
- actions/cache v3 composite
- actions/checkout v3 composite
- ubuntu 22.04 build
- ${BASE_IMAGE} latest build
- ${BASE_IMAGE} latest build
- ${DEV_IMAGE} latest build
- PyYAML ==5.4.1
- click ==8.0.1
- importlib-metadata ==4.4.0
- typing-extensions ==3.10.0.0
- zipp ==3.4.1
- PyYAML ==5.4
- dask *
- numba *
- numpy *
- xarray *
- twine * development
- imageio >=2.9.0
- actions/cache v4 composite
- actions/checkout v4 composite
- actions/setup-python v5 composite
- fortran-lang/setup-fortran v1 composite
- mpi4py/setup-mpi v1 composite
- actions/cache v4 composite
- actions/checkout v4 composite
- softprops/action-gh-release v2 composite
- h5py *
- actions/checkout v4 composite
- actions/cache v4 composite
- actions/checkout v4 composite
- actions/upload-artifact v4 composite
- fortran-lang/setup-fortran v1 composite
- mpi4py/setup-mpi v1 composite
Score: 16.40002360015034