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]

---

Usage:

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)
  

---

Output:

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.