ParFlow Skill

A progressive-disclosure skill for ParFlow, the open-source parallel watershed flow model.

ParFlow upstream: Maxwell, Kollet, Condon, Smith, Woodward, Falgout, Ferguson, Engdahl, Hokkanen et al. Skill author: Koutian Wu (ktwu01@gmail.com) Skill version: 0.1.0

⚠️ Disclaimer — please read before using this skill. This skill is not a gold-standard reference. It is a helper that lowers the barrier for new users to get their hands dirty with the model. AI agents (and the humans drafting this material) make mistakes; commands, file paths, namelist options, and physics explanations here can be wrong, incomplete, or out of date. Always cross-check with the official model documentation, the source code, and a human expert before trusting any output for research, publication, or operational use.

What This Is

A self-contained knowledge package that teaches AI agents (and humans) how to install, configure, run, post-process, debug, and contribute to ParFlow. The package covers:

• The CMake build system and its dependencies (Hypre, Silo, HDF5, NetCDF, PDI)
• MPI, OpenMP, CUDA, HIP, and Kokkos accelerator backends
• The Python and TCL pftools workflow for input setup and post-processing
• Richards equation, overland flow boundary conditions, and the Newton-Krylov solver
• ParFlow-CLM coupling for integrated land-surface hydrology
• The pfb binary format, Silo, NetCDF via PDI, and visualization tools
• The GitHub fork-branch-PR contribution flow with Uncrustify and Black style checks

The skill captures procedural knowledge that is normally only learned by working alongside an experienced ParFlow developer: the order of CMake flags, why MGSemi is the only Jacobian-compatible preconditioner on GPU, the trap of forgetting pfdist before a parallel run, and the file-by-file path needed to add a new key.

Progressive disclosure:

• SKILL.md is the routing hub: decision tree, repo layout, quick start, critical rules.
• reference/*.md are deep-dive docs loaded on demand.

Contents

Document	What is inside
SKILL.md	Entry point: decision tree, repo layout, quick start, critical rules
reference/getting-started.md	CMake build, dependencies, MPI/OpenMP/CUDA backends, Docker, Spack, NUOPC, smoke test
reference/architecture.md	pfsimulator, pftools, pf-keys, pfnuopc, examples, performance_tests, AMPS, KINSOL, CLM, IDB
reference/running-simulations.md	TCL vs Python pftools, pfset keys, Solver Impes vs Richards, examples, parallel topology
reference/physics-and-numerics.md	Richards equation, overland flow variants, conductivity tensors, Newton-Krylov, Hypre
reference/coupling-with-clm.md	ParFlow-CLM coupling, Solver.LSM, drv_clmin.dat, vegm/vegp tables, NLDAS forcing
reference/output-formats.md	pfb, c.pfb, pfsb, Silo, NetCDF via PDI, VisIt, ParaView, HydroFrame
reference/gpu-and-performance.md	CUDA/HIP/Kokkos backends, RMM and Umpire, GPUDirect, OpenMP, scaling tips
reference/debugging.md	CMake errors, Hypre version mismatches, KINSOL convergence, mass balance failures
reference/contributing-pr.md	Fork-branch-PR, pfformat (Uncrustify, Black), Doxygen, LGPL header, CI

Sources

This skill is grounded in:

1. The parflow/parflow repository at release 3.14.1: top-level README.md, README-GPU.md, README-OPENMP.md, README-PDI.md, README-SAMRAI.md, README-Spack.md, RELEASE-NOTES.md, CONTRIBUTING.md, metadata.yml, CMakeLists.txt.
2. The ParFlow Users Manual (Sphinx source under docs/user_manual/), in particular intro.rst, start.rst, models.rst, files.rst, pftools.rst.
3. The ParFlow wiki and the parflow.org project website.
4. Foundational papers: Ashby and Falgout 1996, Jones and Woodward 2001, Kollet and Maxwell 2006, Maxwell 2013, Maxwell and Miller 2005, Kollet and Maxwell 2008.
5. The HydroFrame project for the surrounding data and analysis ecosystem.

Acknowledgments

Gold-standard references for ParFlow (use these to cross-check anything in this skill):

• ParFlow Users Manual: https://parflow.readthedocs.io/
• parflow/parflow repository and wiki: https://github.com/parflow/parflow and https://github.com/parflow/parflow/wiki
• Project website: https://parflow.org
• Foundational papers: Ashby and Falgout 1996, Jones and Woodward 2001, Kollet and Maxwell 2006, Maxwell 2013
• HydroFrame data and analysis ecosystem: https://hydroframe.org

This skill exists only because of the work of other people, and any value it has is borrowed from theirs.

• The ParFlow developer community — Maxwell, Kollet, Condon, Smith, Woodward, Falgout, Ferguson, Engdahl, Hokkanen, and many more — for building parflow/parflow, writing the ParFlow Users Manual, and curating the ParFlow wiki.
• The authors of the foundational ParFlow papers — Ashby and Falgout (1996), Jones and Woodward (2001), Kollet and Maxwell (2006, 2008), Maxwell and Miller (2005), and Maxwell (2013) — whose work this skill references when explaining the Richards-equation solver, overland flow coupling, and the Newton-Krylov method.
• The HydroFrame project for the surrounding data, tools, and analysis workflows that make ParFlow usable end-to-end.
• Zesen Huang for laps-skill, the progressive-disclosure layout this repo borrows.
• Sibling skills noahmp-skill, summa-skill, and vic-skill for shared structure and cross-references across hydrologic models.

Any errors, oversimplifications, or out-of-date claims in this skill are the skill author's responsibility, not the upstream community's.

Install

This skill follows the same layout as laps-skill and the noahmp-skill sibling repo:

parflow-skill/
|-- SKILL.md              <- routing hub (read first)
|-- README.md             <- this file
|-- LICENSE
|-- .gitignore
+-- reference/            <- deep-dive docs

To use with a Claude Code or similar agent harness, drop the directory into your skills library and refresh.

License

MIT. ParFlow itself is governed by the GNU LGPL v2.1: see https://github.com/parflow/parflow/blob/master/LICENSE.txt.