QUAL2K Python & Web Wizard: Water Quality Simulation Software
This tool is a React and Python-based alternative to the EPA QUAL2K water quality model. It replaces the Excel/VBA workbook with a web interface and a cloud-hosted Python port of the QUAL2Kw 5.1 solver. Existing QUAL2Kw workbooks (.xls, .xlsx, .xlsm) can be imported directly, and the engine reproduces the output sheets of 15 calibrated QUAL2Kw models within 5% or a fixed absolute band (see Validation results).
QUAL2K System Architecture
The system consists of three layers: a React-based web wizard for data entry, a Firebase Cloud Function that receives the wizard state, and a Python simulation engine that performs the hydraulic and water quality calculations. Results are returned to the browser for display and export.
QUAL2K Simulation Capabilities
- Time-stepping simulation: an explicit Euler time step over a repeating daily cycle, as in QUAL2Kw, reporting the daily mean, minimum and maximum per reach
- Water quality: DO, CBOD (fast and slow), nitrogen species, phosphorus, phytoplankton and bottom algae, detritus, pathogens, ISS, alkalinity, with pH solved at every step
- Heat balance for water and sediment temperature from solar, long-wave, wind and meteorological forcing
- Manning's equation hydraulics with Newton-Raphson iterative depth solver for trapezoidal cross-sections
- Arrhenius temperature correction on all first-order kinetic rates
- Multiple reaeration formulas: O'Connor-Dobbins, Churchill, Owens-Gibbs, Tsivoglou-Neal, Thackston-Dawson and user-specified
- Point sources and diffuse sources with mass-balance mixing at reach boundaries
- Auto-calibration of 18 kinetic rates against observed field data (differential evolution, with a genetic algorithm as fallback)
- QUAL2Kw workbook import (.xls, .xlsx, .xlsm) plus CSV and JSON import/export
Supported Constituents
Water quality columns in the results (temperature and pH are reported too)
| Index | Constituent | Units | Process |
|---|---|---|---|
| 0 | Conductivity | μmhos | Conservative |
| 1 | Inorganic Suspended Solids (ISS) | mg/L | Settling |
| 2 | Dissolved Oxygen (DO) | mg/L | Reaeration, oxidation, SOD |
| 3 | Slow CBOD | mg/L | Slow oxidation, hydrolysis source |
| 4 | Fast CBOD | mg/L | Oxidation, hydrolysis from slow |
| 5 | Organic Nitrogen | μg/L | Hydrolysis, settling |
| 6 | Ammonium (NH₄) | μg/L | Nitrification |
| 7 | Nitrate (NO₃) | μg/L | Denitrification, nitrification source |
| 8 | Organic Phosphorus | μg/L | Hydrolysis, settling |
| 9 | Inorganic Phosphorus | μg/L | Settling |
| 10 | Phytoplankton | μg Chl-a/L | Growth, respiration, death |
| 11 | Detritus | mg/L | Dissolution, settling |
| 12 | Pathogens | cfu/100mL | Die-off, settling |
| 13 | Generic | user | User-defined decay |
| 14 | Alkalinity | mg CaCO₃/L | Conservative |
Technology Stack
| Component | Technology | Purpose |
|---|---|---|
| Frontend | React 19 + Vite | Multi-step wizard UI with state management |
| Styling | Vanilla CSS | Dark/light theme with design tokens |
| Auth | Firebase Authentication | Google Sign-In for user access |
| Hosting | Firebase Hosting | CDN-backed static site delivery |
| Backend | Firebase Cloud Functions (2nd gen) | Serverless Python execution |
| Engine | Python with NumPy and SciPy | QUAL2Kw 5.1 solver port and auto-calibration |
| Data | JSON / CSV | Portable data interchange formats |
Design Principles
- Measured fidelity - the engine reproduces the output sheets of 15 calibrated QUAL2Kw models within 5% or a fixed absolute band (pH 0.05, temperature 0.2 °C)
- Zero installation - runs entirely in the browser with cloud computation; no software installation, no VBA macros, no OS restrictions. See Getting Started to begin your first simulation
- Transparent math - every formula is documented in this guide with references to the original QUAL2K technical documentation
- Data portability - all inputs and outputs can be exported as JSON or CSV for use in external tools