Validation Method: Comparing the Engine with QUAL2Kw's Own Output
The engine is an independent Python port of the QUAL2Kw 5.1 solver (the Excel/VBA and Fortran model by Pelletier and Chapra). It is checked the only way that proves the port is right: by running calibrated QUAL2Kw workbooks through it and comparing the result with the output sheets that QUAL2Kw wrote into those same workbooks. Field data are not used here: they test a model's calibration, not whether the solver is implemented correctly.
Pipeline
Reference Workbooks
15 calibrated models from 14 workbooks, all of them Colombian rivers and urban drainage channels from consulting and river-basin studies. They have 3 to 279 reaches and cover the classic QUAL2Kw 5.1 layout, the newer HTS/STS layout and a dendritic (multi-branch) workbook; five of them use sediment diagenesis (both options), and between them they exercise trapezoidal Manning channels and rating curves. Their outputs were written by QUAL2Kw itself (its VBA solver or the Fortran qual2kw5.exe driven by the workbook), so they are the numbers a reviewer would compare against. The list is on the Model Comparisons page.
What Is Compared
- Water quality, daily mean (WQ Output): the 15 QUAL2Kw output columns, from conductivity to pH.
- Daily minimum and maximum (WQ Min, WQ Max): dissolved oxygen and pH.
- Temperature (Temperature Output): daily mean.
- Hydraulics (Hydraulics Summary): flow, depth, area, velocity, reaeration rate and slope. The width column is not scored, because QUAL2Kw builds disagree on whether they print the top or the bottom width.
Engine and workbook rows are matched by distance along the river. The headwater row is left out, since both simply repeat the input there.
Tolerance
A value passes when it is within 5% relative difference of the QUAL2Kw value or within a fixed absolute band. The band stops a percentage from failing a value that is practically zero (1 μg/L against 2 μg/L is 100% apart but meaningless). pH and temperature are judged on the absolute band only.
Absolute bands
| Variable | Band |
|---|---|
| Dissolved oxygen | 0.1 mg/L |
| Slow and fast CBOD, detritus | 0.05 mg/L |
| Organic N, ammonium, nitrate | 5 μg/L |
| Organic and inorganic P | 1 μg/L |
| Phytoplankton | 0.5 μgA/L |
| Inorganic suspended solids | 0.1 mg/L |
| Alkalinity | 0.5 mg CaCO3/L |
| Conductivity | 1 μmhos |
| Pathogens | none (5% only) |
| pH (absolute band only) | 0.05 |
| Temperature (absolute band only) | 0.2 °C |
Import Round Trip
Each workbook's daily means are also scored after going through the site's workbook importer (workbook to wizard state, then to the engine), which is the path a user takes. All 15 models reproduce at the same level on that path too. The dendritic workbook was first split into one file per branch: the importer does not read dendritic workbooks directly yet.
Known Limits
- The hyporheic biofilm kinetics (Level 1 and 2) and the surface transient storage zone of the HTS/STS build are not simulated: no reference workbook exercises them. The engine warns when a model switches the transient storage zone on.
- Integration is explicit Euler only: a workbook set to Runge-Kutta or an adaptive step runs with Euler.
- Run time goes from seconds to a few minutes per reference model. The server stops a run at 300 seconds, which large models with a fine time step and sediment diagenesis can exceed.
- Auto-calibration searches with a faster daily-mean approximation and then runs the faithful solver once, so only its final result is exact.
The comparison is part of the engine's test suite: four of the workbooks are kept as regression tests.