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 legacy Excel/VBA spreadsheet with a modern web interface and a cloud-hosted Python simulation engine, while maintaining numerical equivalence with the original model.
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
- Steady-state simulation of 15 water quality constituents including DO, CBOD (fast and slow), nitrogen species, phosphorus, pathogens, and ISS
- 24-hour diel simulation with hourly time-stepping for temperature, light, 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, and user-specified
- Point sources and diffuse sources with mass-balance mixing at reach boundaries
- Auto-calibration using genetic algorithm optimization against observed field data
- CSV and JSON import/export for interoperability with Excel and other tools
Supported Constituents
15 Water Quality State Variables
| 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 3.12 | QUAL2K simulation with NumPy-free math |
| Data | JSON / CSV | Portable data interchange formats |
Design Principles
- Numerical equivalence \u2014 the Python engine produces results within 1% of the legacy Excel model for all validated test cases
- Zero installation \u2014 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 \u2014 every formula is documented in this guide with references to the original QUAL2K technical documentation
- Data portability \u2014 all inputs and outputs can be exported as JSON or CSV for use in external tools