Moving a QUAL2K / QUAL2Kw Excel Model to the Web Engine

QUAL2K and QUAL2Kw ship as Microsoft Excel workbooks with VBA macros and a Fortran executable. That setup needs Windows and Excel with macros enabled, and large models can be slow or crash inside VBA. The Hydrolitica engine is an independent Python port of the QUAL2Kw 5.1 solver that runs in the browser: you can open an existing workbook directly, with no manual re-entry.

Figure 1: From a QUAL2Kw workbook to results in the browser

Import in One Step

Open the engine with the import dialog (or use Import QUAL2Kw workbook in the engine toolbar) and pick your .xls, .xlsx or .xlsm file. The workbook is read in your browser; only the cell values of the input sheets are sent to the engine, so large workbooks (tens of MB) are fine.
Read the import report. It lists what was carried over and warns about anything that was not (see the table below).
Review the wizard cards, then Run. Compare the results with the workbook's own WQ Output, WQ Min, WQ Max and Temperature Output sheets if you want to check the port yourself.

Supported layouts: classic QUAL2Kw 5.1 and the newer HTS/STS layout. Dendritic (multi-branch) xQUAL2Kw workbooks cannot be imported directly yet. In our September 2026 validation run the engine reproduced the output sheets of 15 calibrated models within 5% (or a small absolute band), and the daily means held after passing each workbook through this importer. See Validation results.

Excel/VBA vs the Web Engine

QUAL2Kw workbook vs Hydrolitica engine

Topic	QUAL2Kw workbook	Hydrolitica engine
Platform	Windows with Excel and macros enabled	Any modern browser (Windows, macOS, Linux, Chromebook)
Getting a model in	Cell editing across many sheets	Import the workbook, or the 14-step guided wizard, or JSON / CSV
Solver	VBA and the Fortran qual2kw5.exe	Python port of the QUAL2Kw 5.1 solver (explicit Euler), run in the cloud
Run time	Depends on the PC and the model	From seconds to a few minutes; the limit is 300 seconds per run
Calibration	Manual, or the workbook genetic algorithm	Auto-calibration of 18 kinetic rates against observed data (free account)
State variables	17 water-quality states plus temperature	The same 17 plus temperature, pH computed at every step
Outputs	Output sheets and charts	Daily mean, minimum and maximum per reach; charts, CSV and PDF report
Saving	The .xlsm file	Cloud save with an account, plus JSON / CSV export

What the Importer Maps

Workbook sheet to wizard card

Workbook sheet	Wizard card	Notes
QUAL2K	1. Project Setup	Name, date, time zone, time step and simulation options (read by label, so both layouts work)
Reach	2. Reach Definition	Geometry, Manning's n or rating curves, weirs, elevations, coordinates
Headwater	3. Headwater	Flow, temperature and water quality
Point Sources	4. Point Sources	Location, inflow or abstraction, concentrations
Diffuse Sources	5. Diffuse Sources	Location range, flow, concentrations
Rates	6. Kinetic Rates	Read by section and label, as the VBA reads them
Reach Rates	7. Reach Rates	Per-reach overrides, every column
Light and Heat	8. Light & Heat	Solar, long-wave and wind options
Meteorology sheets	9. Meteorology	Air and dew-point temperature, wind, cloud, shade
Initial conditions	12. Initial Conditions	Starting values, bottom algae

What is not imported

Point-source loads that vary through the day are imported as their daily mean (the wizard has no diel point-source form). The import report says so when it happens.
Observed data (the WQ Data sheet) is not imported: enter the calibration targets in the Observed Data card.
Custom VBA added to a workbook is not run; only the standard QUAL2Kw calculations are.
The integration method: the engine always integrates with explicit Euler, so a workbook set to Runge-Kutta or an adaptive step runs with Euler.
The hyporheic biofilm kinetics and the surface transient storage zone (HTS/STS build) are not simulated; the engine warns when a model switches the transient storage zone on.
Dendritic (multi-branch) xQUAL2Kw workbooks: split them into one workbook per branch first.
A workbook without reach latitude and longitude runs with the sun at 0 degrees, 0 degrees, exactly as QUAL2Kw does; the engine warns.

Common Issues

Issue	Cause	Solution
Run stops at 300 seconds	Large model with a small time step, especially with sediment diagenesis	Use a larger calculation step or split the river
Solar warning after import	No latitude / longitude on the reaches	Add coordinates in Project Setup or on the reaches
DO saturation too high	Elevation left at 0 m	Enter the reach elevations
Import report lists diel point sources	The workbook varies loads through the day	Check whether the daily mean is acceptable for your study

If the problem is the Excel workbook itself (Error 53, a stop at ChDir ThisWorkbook.Path, "is aborted!" or blocked macros), see QUAL2K and QUAL2Kw errors and how to fix them.