Skip to main content
U.S. flag

An official website of the United States government

pywatershed: A hydrologic model in Python

Pywatershed is Python package for simulating hydrologic processes motivated by the need to modernize important, legacy hydrologic models at the USGS, particularly the Precipitation-Runoff Modeling System (PRMS, Markstrom et al., 2015) and its role in GSFLOW (Markstrom et al., 2008). 

Overview of pywatershed

Pywatershed's modernization of these legacy models aims to make the more flexible as process representations, to support testing of alternative hydrologic process conceptualizations, and to facilitate the incorporation of cutting-edge modeling techniques and data sources. Pywatershed is a place for experimentation with software design, process representation, and data fusion in the context of well-established hydrologic process modeling.

The Python language was chosen because it is accessible to a wide audience of potential contributors which will help foster community development and experimentation. A large number of advanced libraries available for Python can also be applied to hydrologic modeling, including libraries for parallelism, data access and manipulation, and machine learning.

Following the conceptual design of PRMS, pywatershed calculates explicit solutions of spatially distributed hydrologic process representations including evaporation, transpiration, runoff, infiltration, interflow, snowpack, soil moisture, conceptual groundwater storage, and channel flow. These process representations simulate hydrologic response and water budgets given inputs of spatially distributed weather variables and land use change at temporal scales ranging from days to centuries.

Pywatershed enhances PRMS with a new software design that is object-oriented and highly flexible, allowing users to easily run “sub-models”, replace process representations, and incorporate new data. There are base classes which manage mass and energy conservation, and the implementation of concrete process classes follows a self-describing design which allows for a Model class to connect hydrologic process classes based on their descriptions of themselves. A variety of input data sources is managed by the Adapter class which implements subclasses for different sources. The design of pywatershed is documented in these docs and also demonstrated by numbered Jupyter Notebooks in the examples/ directory.

The flexible structure of pywatershed helps it to couple with other hydrologic models. We can easily one-way couple pywatershed to MODFLOW 6 (MF6, Hughes et al., 2017) via its XMI interface (Hughes et al., 2022). We are working towards a two-way, tight coupling with MF6 to reproduce GSFLOW. Our goal is to support integrated hydrologic process modeling of surface water and groundwater in a sustainable manner that allows individual software components to evolve independently.

Current version: 1.0.0

With pywatershed version 1.0.0, we have faithfully reproduced the PRMS process representations used in the USGS National Hydrolgical Model (NHM, Regan et al., 2018). For more information on version 1.0.0 see the release notes and the extended release notes for version 1.0.0.

Upcoming development in 2024

The broad goal is to reproduce GSFLOW coupling using the MODFLOW 6 API. This will include gridded configurations and cascading flows. We are also working on reservoir representations. Follow the development at the pywatershed repository.

Getting started

Pywatershed can be installed from PyPI, conda-forge, or directly from the repository. See the file in the repository for installation instructions. Reading the pywatershed docs lets you browse the API reference and developer info. But the best way to get started with pywatershed is to dive into the example notebooks.

For introductory example notebooks, look in the examples/ directory in the repository. Numbered starting at 00, these are meant to be completed in order. Notebook outputs are not saved in Github. But you can run these notebooks locally or using WholeTale (free but sign-up or log-in required) where the pywatershed environment is all ready to go. Follow these links to run the latest release in WholeTale or the the develop branch in WholeTale See for more details on both running locally or using WholeTale.

Community engagement

We value your feedback! Please use discussions or issues on Github. You may also suggest edits to this documentation or open an issue by clicking on the Github Octocat at the top of the page. For more in-depth contributions, please start by reading over the file.

Thank you for your interest.

How to Cite pywatershed

Software/Code Citation for pywatershed

McCreight, J., Langevin, C. D., & Hughes, J. D. (2023). pywatershed (Version 1.0.0) [Computer software].