8.1. PFTools

Welcome to Python PFTools. This is a Python package that creates a user-friendly Python interface for ParFlow. This package allows users to run ParFlow directly from a Python script, leveraging the power and accessibility of Python. More documentation for this package can be found here: https://pypi.org/project/pftools/

8.1.1. Installation

pftools can be installed with the following command:

pip install pftools[all]

The [all] argument will download the dependencies necessary for running ParFlow and fully employing the other tools within this package. [all] encompasses the subsets of dependencies, including:

  • [pfsol]: installs the imageio package for handling image processing to assist some workflows to build ParFlow solid (.pfsol) files.

  • [io]: installs the numpy, xarray, and dask packages for handling reading and storing of ParFlow binary (.pfb) data.

  • [fastio]: installs the numba package for translating certain I/O operations into fast machine code.

If you would like to set up a virtual environment to install pftools, execute the following commands:

python3 -m venv py-env
source py-env/bin/activate
pip install pftools[all]

8.1.2. Execution

Command: python3 /path/to/script/run_script.py [args]


run_script.py [-h] [--parflow-directory PARFLOW_DIRECTORY] [--parflow-version PARFLOW_VERSION]
[--working-directory WORKING_DIRECTORY] [--skip-validation] [--dry-run] [--show-line-error]
[--exit-on-error] [--write-yaml] [--validation-verbose] [-p P] [-q Q] [-r R]

Parflow run arguments:

  • Optional arguments:

    -h, --help            show help message and exit
  • Parflow settings:

    --parflow-directory PARFLOW_DIRECTORY
                    Path to use for PARFLOW_DIR
    --parflow-version PARFLOW_VERSION
                    Override detected Parflow version
  • Execution settings:

    --working-directory WORKING_DIRECTORY
                    Path to execution working directory
    --skip-validation     Disable validation pass
    --dry-run             Prevent execution
  • Error handling settings:

    --show-line-error     Show line error
    --exit-on-error       Exit at error
  • Additional output:

    --write-yaml          Enable config to be written as YAML file
    --validation-verbose    Prints validation results for all key/value pairs
  • Parallel execution:

    -p P
         P allocates the number of processes to the grid-cells in x (overrides Process.Topology.P)
    -q Q
         Q allocates the number of processes to the grid-cells in y (overrides Process.Topology.Q)
    -r R
         R allocates the number of processes to the grid-cells in z (overrides Process.Topology.R)


When executing ParFlow via the Python script using run(), you will get the following message if the ParFlow run succeeds:


Or if it fails:


This will be followed by the contents of the runname.out.txt file.