PyWMP: Professional Watershed Modeling Framework

About PyWMP

Network-Based Watershed Modeling

PyWMP is an innovative, open-source framework designed for watershed modeling and hydrologic planning. It provides a flexible and extensible toolset for simulating runoff generation and flow routing through complex hydrologic systems using a network-based approach.

A key feature of PyWMP is its fully automated workflow for generating high-precision inundation depth raster maps by leveraging high-resolution LiDAR Digital Elevation Models (DEM). To achieve this, PyWMP conceptualizes the watershed as a directed acyclic graph (DAG), a network-based approach that offers significant advantages over traditional grid-based or lumped-parameter models. In this framework:

• Nodes represent hydrologically significant features such as catchment outlets, hydraulic structures (pumps, weirs), and depressions.
• Edges represent the conveyance pathways (e.g., streams, canals) that connect these nodes.

By leveraging the NetworkX library, PyWMP captures the complex, non-linear relationships within a watershed, providing an intuitive and adaptable method for representing hydrologic systems. The framework calculates runoff at each node and routes these flows through the network, dynamically updating the hydraulic conditions at each simulation interval. This makes PyWMP an effective tool for researchers, water resource managers, and urban planners engaged in flood modeling, water resource management, and environmental conservation.

Key Features

🐍 Open Source Python Library (pywmp)

Free, Open, and Extensible

The pywmp library is the core engine that powers watershed modeling through Python. Perfect for researchers, developers, and anyone who needs programmatic control over hydrologic simulations.

Terminal

$ pip install pywmp # Ready to model watersheds! 🚀

Start Tutorial View on GitHub API Docs

Why Choose the Open Source Library?

5-Minute Example

Get started with a simple watershed simulation in just a few lines of code:

import pandas as pd
from pywmp.models import Cascade2001Model
from pywmp.simulate import HydrologicSimulator

# Load your watershed data
df = pd.read_csv('my_watershed.csv')

# Create the network model
model = Cascade2001Model(df=df, from_col='Basin_ID', to_col='Receives_From')

# Set up and run simulation
simulator = HydrologicSimulator(
    graph=model.graph,
    scenarios={"100yr": "Rainfall_100yr_in"},
    column_mapping={
        'name_col': 'Basin_ID',
        'area_col': 'Area_ac', 
        'tc_col': 'Time_Concentration_hr'
    }
)

# Run the simulation - results saved automatically
simulator.run()

print("✅ Simulation complete! Check the 'simulation_results' directory.")

Installation & Requirements

PyWMP-Pro (ArcGIS) Tutorial

This section provides a hands-on tutorial for users of the ArcGIS Pro toolbox. This guide is designed to get you productive with the software quickly through a practical, real-world example.

Video Tutorial: Complete Workflow

This video provides a complete visual guide to using PyWMP-Pro, from project setup to result interpretation. It's the perfect starting point for new users.

Workshop: Flood Inundation Mapping

This workshop guides you through a complete modeling workflow to produce a flood inundation map for a 100-year storm event. For a complete walkthrough, a sample data package can be made available.

Step 1: Create the Hydrologic Model

First, add the PyWMP-Pro.pyt toolbox to your ArcGIS Pro project. Open the Create Hydrological Model tool. This tool processes your raw GIS and tabular data (e.g., a CSV or shapefile defining your basins and structures) into a structured JSON file that defines the watershed network. The most important step is to carefully map your data columns to the model's required fields in the tool's interface.

Step 2: Run the Simulation and Analyze Results

Open the Simulate Multi-Scenario Model tool. Use the .json file generated in the previous step as the primary input and select the desired storm scenarios to run. The tool automatically runs the simulation and adds a `simulation_results` point layer to your map. Use its attribute table and symbology to visualize peak water stages and identify areas of potential flooding. The output directory will also contain detailed hydrograph plots and CSV files for each simulated node.

pywmp (Python) Tutorial

For developers and researchers who prefer a programmatic approach, this tutorial provides an interactive, code-first introduction to the `pywmp` library.

Video Tutorial: Introduction to the `pywmp` API

This video introduces the core concepts and objects in the `pywmp` Python library, showing you how to set up your environment and run a basic simulation script.

Example: Scripting a Multi-Scenario Simulation

This example demonstrates the core workflow: loading data, creating a model network, configuring the simulator, and running a multi-scenario analysis programmatically.

import pandas as pd
import networkx as nx
from pywmp.models import Cascade2001Model
from pywmp.simulate import HydrologicSimulator

# 1. Load data and create the network model
# The model requires a dataframe with columns defining the basins,
# their connectivity, and their physical and hydrologic parameters.
df = pd.read_csv('path/to/your/basin_data.csv')
model = Cascade2001Model(df=df, from_col='Basin_ID', to_col='Receives_From')
graph = model.graph

# 2. Define scenarios and instantiate the simulator
# The keys are the scenario names, and the values are the corresponding
# rainfall column names in your input dataframe.
scenarios_to_run = {
    "1d_100y": "Rainfall_1d_100y_in",
    "1d_25y": "Rainfall_1d_25y_in"
}

# The column_mapping dictionary tells the simulator which columns to use
# for essential parameters.
column_map = {
    'name_col': 'Basin_ID', 
    'area_col': 'Area_ac',
    'tc_col': 'Time_of_Concentration_hr',
    'soil_storage_col': 'Soil_Storage_in',
    'initial_stage_col': 'Initial_Stage_ft',
    'high_elev_col': 'High_Elevation_ft'
}

simulator = HydrologicSimulator(
    graph=graph,
    outdir="simulation_results",
    scenarios=scenarios_to_run,
    column_mapping=column_map,
    start_hour=0.0,
    end_hour=72.0,
    time_interval=1.0
)

# 3. Run the simulation
# This will execute all defined scenarios and save results to the output directory.
simulator.run()

# 4. Access summary results
# A consolidated summary of all scenarios is saved to the output directory.
summary_df = pd.read_csv('simulation_results/all_scenarios_summary.csv')
print(summary_df.head())

PyWMP-Pro Tool Guide

This guide provides conceptual explanations of the PyWMP-Pro toolbox for ArcGIS, helping you understand its components and how they work together.

Tool Reference

The toolbox contains primary tools that guide the user through the modeling process. Refer to each tool's help documentation within ArcGIS Pro for detailed parameter descriptions.

• Create Hydrological Model: This tool is the first step in the workflow. It processes your raw GIS and tabular data into a structured JSON file that defines the watershed network, its connectivity, and all associated parameters. This file serves as the master input for the simulation engine.
• Simulate Multi-Scenario Model: This tool is the computational core of the workflow. It takes the JSON model file as input, runs the `pywmp` engine for all user-selected scenarios, and generates a comprehensive set of outputs, including GIS layers with summary results, and detailed hydrograph data tables and plots for each node.

pywmp Library Guide

This guide is for developers and researchers using the core Python library. It explains the library's architecture and data structures.

Installation

Since the project is under active development, it is recommended to clone the repository for testing and contributing to improvements:

git clone https://github.com/mandalanil/pywmp.git
cd pywmp
pip install -e .

Module Breakdown

The `pywmp` library is organized into several key modules, each responsible for a specific part of the hydrologic modeling process:

• simulate: Contains the main HydrologicSimulator class that orchestrates the entire simulation, managing time steps, scenarios, and data flow.
• models: Includes the Cascade2001Model class, which uses NetworkX to construct the watershed graph from input data.
• hyetograph: Provides functions like generate_rainfall_table to create rainfall distributions and calculate rainfall excess using the SCS-CN method.
• hydrograph: Contains functions like generate_runoff_hydrograph to perform convolution and generate direct runoff hydrographs from rainfall excess.
• stage_storage: Implements functions to relate a basin's storage volume to its water surface elevation (stage).
• structure_flows: Provides functions to calculate discharge through hydraulic structures like pumps and gated spillways based on hydraulic conditions.

Methodological Foundations

This section provides a citable, academic-quality reference on the theoretical underpinnings of the models implemented in `pywmp`. Understanding these methods is crucial for conducting and publishing rigorous scientific research.

Rainfall-Runoff Modeling

1. Rainfall Excess Generation (SCS-CN)

PyWMP estimates direct runoff from storm rainfall using the widely-accepted SCS Curve Number (CN) method. This empirical model calculates rainfall excess based on total rainfall, soil type, land use, and antecedent moisture conditions. The framework first determines the initial abstraction ($I_a$), the amount of rainfall captured by interception and surface storage before runoff begins, as a function of the potential maximum soil moisture retention ($S$):

Iₐ = 0.2 * S

As the storm continues, the cumulative runoff depth ($Q$) is calculated at each time step based on the cumulative rainfall ($P$):

Q = (P - Iₐ)² / (P - Iₐ + S)     for P > Iₐ

The retention parameter $S$ is derived from the user-provided Curve Number: S = (1000 / CN) - 10. The model then calculates the incremental rainfall excess for each time step, which becomes the input for hydrograph generation.

2. Runoff Hydrograph Generation (Unit Hydrograph & Convolution)

The incremental rainfall excess is transformed into a direct runoff hydrograph using the synthetic unit hydrograph method. The framework generates a unit hydrograph (UH), representing the response of the watershed to one inch of excess rainfall over a specific duration. This UH is then convoluted with the rainfall excess time series to produce the final runoff hydrograph.

The shape of the unit hydrograph is determined by the basin's time of concentration ($t_c$) and area. The time to peak ($t_p$) and peak discharge ($q_p$) of the unit hydrograph are calculated using specific empirical relationships implemented in the code. The resulting runoff hydrograph represents the inflow to a specific node in the watershed network.

Hydrologic Routing and Hydraulic Structures

Level-Pool Routing (Storage Routing)

For outlet nodes that represent storage features like ponds or reservoirs, PyWMP employs a Level-Pool Routing (also known as Modified Puls or storage routing) method. This is a hydrologic (lumped) routing technique that solves the continuity equation:

Inflow - Outflow = ΔStorage / Δt

At each time step ($\Delta t$), the model performs the following calculations for a given node:

1. The inflow volume is determined from the node's own runoff hydrograph plus the routed outflows from any upstream nodes.
2. The outflow is calculated as the sum of discharges from all immediately downstream structures (e.g., pumps, weirs), based on the current water stage at the node.
3. The change in storage is calculated, and the total storage volume is updated.
4. A new water surface elevation (stage) is calculated from the updated storage volume using a predefined stage-storage relationship. In the current implementation, this is handled by the simple_average function, which assumes a linear relationship between stage and storage.

This iterative process provides a time-series of stage and discharge for each storage node in the network.

Hydraulic Control Structures

The outflow from a storage node is controlled by the hydraulic characteristics of its downstream structures. PyWMP models two primary types of control structures:

• Pumps: Modeled as simple on/off devices. When the headwater elevation at the storage node exceeds a defined "on" elevation, the pump operates at its full rated capacity. Below this elevation, its discharge is zero.
• Gated Spillways and Weirs: Modeled using standard hydraulic equations that account for different flow regimes. The model can simulate free-orifice flow, submerged-orifice flow, and weir flow based on the relative headwater and tailwater elevations compared to the structure's crest and gate opening. Submergence corrections are applied to accurately reduce discharge when tailwater effects become significant.

API Reference

The API Reference is the definitive, code-level guide for developers. It is auto-generated from the docstrings in the `pywmp` source code to ensure it is always accurate and up-to-date with the latest version of the software. Each function and class entry includes detailed parameter descriptions, return values, and practical, executable examples. This section provides a reference for the most critical components of the library.

Related Projects & Further Reading

1. pyswmm
2. GeoFlood
3. GSFLOW
4. pyflo
5. Cascade
6. Triton
7. GWLF
8. ABCD
9. stormcatchments
10. muskingum-cunge
11. Why is the Muskingum-Cunge the best...
12. Python Hydrology Tools
13. lidar
14. HAND
15. A scale-adaptive urban hydrologic framework...
16. HydroCNHS
17. USGS Surface Water Data
18. Engineering Hydrology Notebooks

Use Limitations

Both PyWMP-Pro and the `pywmp` library are intended for planning-level analysis, not for detailed engineering design where high-precision hydraulics are required. The primary limitation stems from the use of hydrologic routing methods.

How to Cite

If you use PyWMP or PyWMP-Pro in your research, please cite it as follows:

References

The methods implemented in `pywmp` are based on foundational and widely accepted literature in the field of hydrology.

1. Chow, V. T., Maidment, D. R., & Mays, L. W. (1988). *Applied Hydrology*. McGraw-Hill.
2. U.S. Department of Agriculture, Natural Resources Conservation Service. (1986). *National Engineering Handbook, Part 630: Hydrology*. Washington, D.C.