Skip to content

README.md

Latest commit

 

History

History
175 lines (130 loc) · 5.87 KB

README.md

File metadata and controls

175 lines (130 loc) · 5.87 KB
Raw

Python License SWAT+ Streamlit CI

Overview

PySWATPlus is a Python framework for calibrating, validating, and analyzing SWAT+ watershed models. It provides multiple optimization algorithms (DDS, PSO, GLUE), global sensitivity analysis (Sobol, Morris), and an interactive Streamlit dashboard for managing calibration workflows.

Built for hydrologists and water resources engineers who need reproducible, efficient model calibration with statistical rigor.

Features

  • Multi-Algorithm Calibration — DDS (Dynamically Dimensioned Search), PSO (Particle Swarm Optimization), GLUE (Generalized Likelihood Uncertainty Estimation)
  • Global Sensitivity Analysis — Sobol variance decomposition, Morris elementary effects
  • Multi-Objective Optimization — Pareto-optimal parameter sets with NSE, KGE, PBIAS, RMSE
  • Parallel Execution — Concurrent SWAT+ simulations with configurable worker pools
  • Interactive Dashboard — Streamlit UI for project setup, parameter management, and result visualization
  • Validation Framework — Split-sample, k-fold, and multi-site validation with statistical tests
  • SWAT+ Native — Direct cal_parms.cal editing, output parsing, and project management

Installation

pip install pyswatplus

Or from source:

git clone https://github.com/rushmarshall/PySWATPlus.git
cd PySWATPlus
pip install -e ".[dev]"

Quick Start

Command Line

from pyswatplus import Calibrator, SWATProject

project = SWATProject("path/to/swatplus/model")

calibrator = Calibrator(
    project=project,
    algorithm="dds",
    objective="kge",
    max_iterations=1000,
    n_workers=4,
)

# Define parameter bounds
calibrator.add_parameter("cn2", -0.3, 0.3, method="relative")
calibrator.add_parameter("esco", 0.0, 1.0, method="replace")
calibrator.add_parameter("alpha_bf", 0.0, 1.0, method="replace")

# Run calibration
results = calibrator.run(
    observed="observed_flow.csv",
    warmup_years=2,
    calibration_period=("2010-01-01", "2015-12-31"),
)

print(f"Best KGE: {results.best_objective:.4f}")
results.plot_hydrograph("calibration_hydrograph.png")
results.save("calibration_results.json")

Streamlit Dashboard

streamlit run src/pyswatplus/ui/app.py

Calibration Algorithms

Algorithm Type Best For Parameters
DDS Single-objective Fast convergence, high-dimensional r_val, max_iter
PSO Single/Multi-objective Global search, avoiding local optima n_particles, w, c1, c2
GLUE Uncertainty Behavioral parameter identification n_simulations, threshold

Sensitivity Analysis

from pyswatplus.sensitivity import SobolAnalysis

sobol = SobolAnalysis(project=project, n_samples=1024)
sobol.add_parameter("cn2", -0.3, 0.3)
sobol.add_parameter("esco", 0.0, 1.0)
sobol.add_parameter("alpha_bf", 0.0, 1.0)

results = sobol.analyze(output_variable="streamflow")
results.plot_indices("sobol_indices.png")

Objective Functions

Metric Range Optimal Description
NSE (-inf, 1] 1.0 Nash-Sutcliffe Efficiency
KGE (-inf, 1] 1.0 Kling-Gupta Efficiency
PBIAS (-inf, inf) 0.0 Percent Bias
RMSE [0, inf) 0.0 Root Mean Square Error
R2 [0, 1] 1.0 Coefficient of Determination
LogNSE (-inf, 1] 1.0 Log-transformed NSE (low flows)

Architecture

pyswatplus/
├── calibration/        # Calibration engine
│   ├── algorithms/         DDS, PSO, GLUE implementations
│   ├── objective.py        Objective function library
│   └── sampler.py          Parameter sampling strategies
├── sensitivity/        # Sensitivity analysis
│   ├── sobol.py            Sobol variance decomposition
│   └── morris.py           Morris elementary effects
├── core/               # SWAT+ integration
│   ├── project.py          Project management
│   ├── runner.py           Parallel SWAT+ execution
│   ├── parser.py           Output file parsing
│   └── parameters.py       cal_parms.cal management
├── validation/         # Model validation
│   ├── splitter.py         Train/test splitting strategies
│   └── metrics.py          Statistical validation tests
└── ui/                 # Streamlit dashboard
    ├── app.py              Main application
    └── components.py       Reusable UI components

Contributing

Contributions welcome. Please open an issue to discuss proposed changes before submitting a pull request.

git clone https://github.com/rushmarshall/PySWATPlus.git
cd PySWATPlus
pip install -e ".[dev]"
pytest tests/ -v

Developed at Hydrosense Lab, University of Virginia
Part of the Global Hydrology and Water Resources research group