SWAT-DG: Diagnostic-Guided SWAT Calibration

Python framework for the SWAT2012 hydrological model (Rev. 681+) with diagnostic-guided calibration — physics-based parameter tuning that converges in minutes, not days. Developed by Lynxce | Download Portable ZIP

The Problem: Calibration is a Bottleneck

SWAT has more than 45 adjustable parameters. Standard calibration tools try thousands of parameter combinations blindly — like tuning a complex instrument while blindfolded. The popular SCE-UA algorithm (used in SWAT-CUP) typically requires 5,000 to 50,000 model runs to converge. At one minute per run, that's 3 to 35 days of compute time.

Worse, blind optimization tells you what the best parameters are — but not why they work. When the model fails in a new scenario, you start over from scratch.

The Solution: Diagnose Before You Calibrate

SWAT-DG acts like an experienced hydrologist reading the hydrograph. Before touching any parameters, it runs 5 diagnostic checks on simulated vs. observed streamflow:

1. Volume balance — Is total simulated water too high or too low?
2. Baseflow partition — Is the groundwater/surface runoff split correct?
3. Peak events — Are storm peaks the right magnitude and timing?
4. Flow duration curve — Does the model reproduce wet, median, and dry flow statistics?
5. KGE decomposition — Is poor performance from timing, variability, or bias?

These diagnostics feed 14 expert rules that prescribe targeted parameter adjustments in 4 sequential phases. The result:

SWAT-DG is a rapid screening tool and smart warm-start. For publication-quality calibration, run SWAT-DG first to get a physically informed starting point, then refine with SCE-UA — cutting total iterations by 30–60%.

Web Interface — No Code Required

SWAT-DG includes a 7-page Streamlit web app that runs 100% locally. All data stays on your computer. A portable Windows ZIP is available — no Python installation needed.

App pages:

• Project Setup — Load SWAT project, auto-detect executable, view project info
• Watershed Map — Interactive Folium map of subbasins and reaches with simulation output overlay
• Simulation Results — Browse raw SWAT outputs, compare runs, spatial summaries
• Observation Data — Import from USGS NWIS API, CSV, Excel, WQP/STORET with auto unit conversion
• Parameter Editor — Edit 45+ parameters with live bounds, batch editing, save/load presets
• Calibration — Choose mode (single-site, multi-site, sequential, partial-basin), algorithm, and run
• Results — Performance metrics, before/after hydrographs, scatter plots, FDC, diagnostic plots, export

Key Features

• Diagnostic-Guided Calibration — Single diagnostic, ensemble (parallel runs for uncertainty), phased (hydrology → sediment → nitrogen → phosphorus), multi-constituent water quality calibration with load calculator and WQ-specific diagnostic engines

• Traditional Calibration (SPOTPY) — 8+ algorithms (SCE-UA, DREAM, Monte Carlo, LHS, ROPE, DE-MCZ), 45+ parameters with recommended bounds, 8 objective functions (NSE, KGE, PBIAS, RMSE, MAE, R², RSR, Log-NSE), sensitivity analysis (FAST, Sobol), multi-site and sequential calibration, parallel multi-core support

• Complete Python SWAT Wrapper — Run simulations, read/write all input files (.bsn, .sol, .mgt, .gw, .cio), parse all outputs to DataFrames, backup/restore with 99.9% size reduction, fig.fig routing parser with upstream/downstream traversal, partial-basin active subbasin optimization

• Rich Visualization — Hydrographs (daily/monthly), scatter plots, flow duration curves, diagnostic plots (baseflow separation, peak comparison, seasonal bias, rating curves), interactive Plotly charts, sensitivity tornado charts, export to PNG/PDF/HTML

• Data Automation — USGS NWIS streamflow/WQ import, Water Quality Portal (WQP/STORET) with auto unit conversion, NOAA CDO weather data, SSURGO soil data, NLCD land cover, DEM processing and watershed delineation

Installation

pip install swat-dg

Or install from source:

git clone https://github.com/wasailin/SWAT-DG.git
cd swat-dg
pip install -e .

For calibration features:

pip install swat-dg[calibration]  # Installs spotpy, pathos

For GIS/spatial features:

pip install swat-dg[gis]  # Installs geopandas, rasterio, pyproj, xarray, folium

For data automation:

pip install swat-dg[data]  # Installs requests, openpyxl

For the Streamlit web app:

pip install swat-dg[app]  # Installs streamlit, plotly, folium

For all features:

pip install swat-dg[full]  # All above + scipy, shapely

Quick Start

Launch the Calibration App (Easiest!)

# Install with app dependencies
pip install -e ".[app]"

# Launch the calibration app
streamlit run src/swat_modern/app/main.py

# Opens browser at http://localhost:8501
# Browse to your SWAT project folder
# Load observation data, select parameters, run calibration!

The app runs 100% locally - all data stays on your computer.

Basic Usage

from swat_modern import SWATModel

# Load a SWAT project
model = SWATModel("C:/my_watershed", executable="C:/swat2012.exe")

# Run simulation
result = model.run()

# Get streamflow output
flow = model.get_output("FLOW_OUTcms", output_type="rch", unit_id=1)
print(flow.head())

# Modify parameters
model.modify_parameter("CN2", -0.1, method="multiply")  # Reduce CN2 by 10%

# Run again
result2 = model.run()

Calibration

from swat_modern import SWATModel
from swat_modern.calibration import Calibrator

# Load model
model = SWATModel("C:/my_watershed")

# Create calibrator with observed data
calibrator = Calibrator(
    model=model,
    observed_data="streamflow.csv",
    parameters=["CN2", "ESCO", "GW_DELAY", "ALPHA_BF", "GWQMN"],
    output_variable="FLOW_OUT",
    reach_id=1,
    objective="nse"
)

# Run automatic calibration (parallel across cores)
results = calibrator.auto_calibrate(
    n_iterations=5000,
    algorithm="sceua",
    parallel=True,
    n_cores=4
)

# View results
results.print_summary()
results.plot_comparison()

# Save best parameters
results.save_best_parameters("best_params.json")

Diagnostic-Guided Calibration

from swat_modern.calibration import Calibrator

calibrator = Calibrator(model=model, observed_data="streamflow.csv", reach_id=1)

# Single diagnostic run (uses flow signatures to guide parameter selection)
result = calibrator.diagnostic_calibrate(n_iterations=2000)

# Ensemble diagnostic (multiple runs for uncertainty)
result = calibrator.ensemble_diagnostic_calibrate(n_ensemble=5, n_iterations=1000)

# Phased: hydrology first, then sediment, then nitrogen, then phosphorus
result = calibrator.phased_calibrate(phases=["hydrology", "sediment", "nitrogen", "phosphorus"])

Sensitivity Analysis

from swat_modern.calibration import Calibrator

calibrator = Calibrator(model=model, observed_data="streamflow.csv", reach_id=1)

# Parallel sensitivity analysis
sa_result = calibrator.sensitivity_analysis(
    method="fast",
    n_samples=500,
    parallel=True,
    n_cores=4
)

sa_result.plot_rankings()
print(sa_result.top_parameters(n=10))

Using Objective Functions

from swat_modern.calibration.objectives import nse, kge, pbias, rsr, evaluate_model

# Calculate single metric
score = nse(observed, simulated)
print(f"NSE = {score:.3f}")

# Calculate multiple metrics
metrics = evaluate_model(observed, simulated)
print(metrics)  # {'nse': 0.85, 'kge': 0.78, 'pbias': 5.2, 'rsr': 0.45, ...}

Visualization Dashboard

from swat_modern.visualization import CalibrationDashboard

dashboard = CalibrationDashboard(
    dates=dates,
    observed=observed,
    simulated=simulated,
    site_name="Big Creek Watershed",
    variable_name="Streamflow",
    units="m³/s"
)

dashboard.create_dashboard()
dashboard.save("calibration_report.png")
dashboard.to_html("calibration_report.html")

Requirements

• Python 3.10+
• numpy, pandas, matplotlib
• SWAT2012 executable, Rev. 681 or above (available from Releases or the official SWAT website)

Documentation

See the docs/ folder:

• Quick Start
• Installation
• API Reference
• User Manual

Contributing

Contributions are welcome! Please see our contributing guidelines.

License

Apache 2.0 License - see LICENSE file for details.

Acknowledgments

This project builds on the SWAT model developed at Texas A&M University. See https://swat.tamu.edu/ for more information about SWAT.

References

• Arnold, J.G., et al. (2012). SWAT: Model Use, Calibration, and Validation. ASABE.
• Abbaspour, K.C. (2015). SWAT-CUP: SWAT Calibration and Uncertainty Programs.
• Moriasi, D.N., et al. (2007). Model evaluation guidelines. ASABE, 50(3), 885-900.