HYDRA2DGPU
CUDA-accelerated shallow-water equation solver inside QGIS
HYDRA2DGPU is a QGIS plugin for 2D shallow water equation (SWE) modeling with a CUDA-accelerated finite-volume solver. It brings real-time 2D flood simulation into the QGIS map canvas — coupling surface hydrodynamics with 1D urban drainage networks, hydraulic structures, and rainfall/infiltration, with no external tools needed.
Features
- GPU-accelerated solver — CUDA finite-volume with graph caching
- Unstructured mesh FVM — triangles, quads, polygons (Gmsh or built-in)
- Multiple spatial schemes — first-order, MUSCL, WENO5
- Multiple temporal schemes — Euler, RK2, RK4
- Boundary conditions — wall, inflow, stage, open, hydrograph
- 1D drainage coupling — SWMM-style pipes, culverts, weirs, gates, bridges, pumps
- Rainfall & infiltration — rain-on-grid with SCS Curve Number
- Results export — GeoPackage, UGRID NetCDF, GeoTIFF, CSV
- Headless CLI + batch simulation for parameter sweeps
Gallery
Requirements & Install
Requirements
| Component | Requirement |
|---|---|
| QGIS | 3.28+ |
| Python | 3.12+ |
| GPU | NVIDIA, Compute Capability ≥ 7.5 (no CPU fallback) |
| OS | Linux (x86_64) or Windows (x86_64) |
Install
- Download the plugin zip from GitHub Releases.
- In QGIS, install it via Plugins → Manage and Install Plugins → Install from ZIP.
- On first launch, HYDRA2DGPU downloads and installs the matching backend wheel for your platform automatically.
AI & Automation
Agent-assisted modeling
HYDRA2DGPU ships with a built-in MCP server that lets AI assistants drive the full workflow inside QGIS — build models, run parameter sweeps, inspect results, and control the Studio GUI. A headless CLI enables batch simulation for parameter sweeps.
This builds on the same automation research as my automated culvert characterization study for MoDOT.
Agent-Driven Development
The HYDRA2DGPU codebase is developed through an agent-driven workflow — codified conventions, project-specific skills, a curated agent memory, staged test gates, and automated CI — so that large, multi-language (CUDA/C++/Python/QGIS) changes can be built, validated, and shipped repeatably.
Agent Conventions & Rules
- AGENTS.md onboarding — build/test commands, coding conventions (units discipline, computation source-of-truth, PyQt widget liveness, no premature backwards compatibility)
- 13 codified rule files (.opencode/rules/): git safety, debugging hygiene, cache discipline, release testing, planning, MVP architecture, agent selection
- Docs lifecycle — active plans/specs carry status frontmatter; completed work moves to docs/archive/
Custom Skills
- Domain skills — CUDA/FVM solver patterns, Studio UI architecture, GeoPackage schema expert
- Workflow skills — agent memory, subagent-driven development, skills discovery
- Tooling skills — release & publish, hydra MCP server, frontend design
Agent Memory System
- tools/memory.py captures and curates lessons learned; docs/memory/ holds active, review-pending, and superseded entries
- Agents use remember/recall so hard-won pitfalls are reused instead of re-learned
Test Harness & Gates
- tools/fast_fail.sh — staged gates ordered cheapest-to-most-expensive: collect, self-tests, wired-in parity, real headless-QGIS GUI suite (~274 tests), MCP integration
- GPU validation suite (dambreak, unstructured, performance) plus compute-sanitizer memcheck for CUDA memory/race checking
- Fast-fail runs pre-commit; the MCP-integration stage runs pre-PR
CI/CD
- Automated tests on every push/PR
- Multi-platform wheel builds for Linux and Windows
- Release publishing and CodeQL security scanning
Dev Environment & Build
- Two isolated conda environments — qgis_stable (development, GPU tests) and qgis_clean (clean release-test installs)
- pixi.toml pins Python 3.12, QGIS, and CUDA 12.4; CMake C++17 with scikit-build-core produce the native wheel
- Distribution: small plugin zip; first launch auto-downloads the matching platform backend wheel