QUAL2Kw

(version 5.1)

A modeling framework for simulating

river and stream water quality

by
Greg Pelletier, Steve Chapra, and Hua Tao

Department of Ecology
P.O. BOX 47710
Olympia, Washington 98504-7710
e-mail: gpel461@ecy.wa.gov

GETTING STARTED

Installation is required for many water-quality models. This is not the case for QUAL2Kw because
the model is packaged as an Excel Workbook. The program is written in Excel's macro language:
Visual Basic for Applications or VBA. An optional Fortran executable version of the model is also
available to run. The Excel Workbook's worksheets and charts are used to enter data and display
results. Consequently, you merely have to open the Workbook to begin modeling. The following
are the recommended step-by-step instructions on how to obtain your first model run.

Step 1: Unzip the model files to any folder on the hard drive on your PC. When you extract the zip
archive to a drive or folder on your hard drive, a new subfolder in that drive or folder will be
created with the files for QUAL2Kw. For example, if you unzipped to your C:\ drive, then a
subfolder named C:\qual2kw will be created if it does not exist, and the QUAL2Kw files will be in a
subfolder of the qual2kw folder. The qual2kw5.xls and qual2kw5.exe files may be copied to any
working folder on any drive of your computer. Both files must be present together in the same
working folder for the Fortran executable to run. Copies of .xls file may be given any name. The
qual2kw5.exe may not be re-named if you want to run the Fortran executable version from the
.xls file.

Step 2: Open Excel and make sure that your macro security level is set to medium or low. This
can be done using the menu commands: Tools/Macro/Security. Make certain that either the
Medium or Low radio button is selected.

Step 3: Open qual2kw5.xls. When you do this, the Macro Security Dialogue Box will be displayed
if you selected medium security in step 2. Click on the Enable Macros button.

Step 4: Click on either the 'Run VBA' or 'Run Fortran' button. QUAL2K will begin to execute. Both
of these yield identical results except that the Fortran version runs much faster because it is a
compiled executable program. You can follow the progress of the execution on the status bar that
is shown in the bottom left corner of the worksheet. If the Fortran version is run then a DOS
window will open to show the progress during the integration.

If the program runs properly, the ‘Rates’ sheet will be displayed at the end of the run. If it does not
work properly, three possibilities exist:

First, you may be using an old version of Microsoft Office. Although Excel is downwardly
compatible for some earlier versions, Q2K will not work with very old versions.

Second, your computer may not have enough RAM to run the model. The amount of RAM
needed depends on the model application (e.g. number of reaches, calculation time step, etc.). A
minimum RAM of 256 Mb for Windows 98, or 512 Mb with Windows XP is recommended for
small applications, and more is probably needed for larger applications.
Third, you may have made a mistake in implementing the preceding steps. A common mistake is
to make a copy the .xls file in a working folder and forget to also copy the qual2kw5.exe file to the
same working folder (the Fortran executable will not run unless it is the same working folder as
the .xls file)

Step 5: On the QUAL2K Worksheet click on the Open Old File button. Browse to get to the
working directory. You should see that a new file has been created with the name that was
specified in B9. Click on the Cancel button to return to Q2K.

Note that every time that Q2K is run, a data file will be created with the file name specified in cell
B9 on the QUAL2K Worksheet. The program automatically affixes the extension “.q2k” to the file
name. Since this will overwrite the file, make certain to change the file name when you perform a
new application if you don’t want to overwrite the file. A .q2k file may be opened by clicking on the
'Open File' button on the QUAL2K Worksheet. This feature allows you the option to save the
inputs for many different simulations without having to save the .xls for every model run.

OVERVIEW

The computer code used to implement the calculations for QUAL2K is written in Visual Basic for
Applications (VBA). A Fortran executable is also available as an option. Excel serves as the user
interface.

Color is used to signify whether information is to be input by the user or output by the program:

 Pale Blue designates variable and parameter values that are to be entered by the user.
 Pale Yellow designates data that the user enters. This data are then displayed on graphs
generated by Q2K.
 Pale Green designates output values generated by Q2K when the model is run.
 Tan color designates user input parameter values for automatic calibration with the
genetic algorithm. These values are not saved or replaced when a .q2k file is written or
opened.
 Dark solid colors are used for labels and should not be changed.

All worksheets include three buttons:

 Open Old Files. When this button is clicked, the file browser will automatically open to
allow you to access a data file from a previous model run. All QUAL2Kw data files have
the extension “.q2k”. Opening a .q2k file will replace the values in the pale blue and pale
yellow cells of the Worksheets with values that are stored in the .q2k file.
 Run VBA. This button causes Q2K to execute the VBA version of the model and to
create a data file that holds the input values. The data file can then be accessed later
using the Open Old File button.
 Run Fortran. This button causes Q2K to execute Fortran version of the model and to
create a data file that holds the input values. The data file can then be accessed later
using the Open Old File button. The Fortran and VBA versions give identical results
except the Fortran version runs much faster because it is a compiled executable
program.

The ‘Rates’ Worksheet includes an additional button:

 Run Auto-cal. This button causes Q2K to perform an automatic calibration using a
genetic algorithm. The original copy of the qual2kw5.xls in the zip file is an example
application of the automatic calibration for Boulder Creek.
FILES INCLUDED IN qual2kw5.zip:

- readme.rtf is this file with basic info about getting started

- qual2kw5.xls is the Excel Workbook file for application of the QUAL2Kw model to any
steady-flow simulation period in a stream or river. This is the file that is used for
input/output and running the QUAL2Kw model for a single simulation period. The
example application is a simulation of Boulder Creek for 21-Aug-1987.
- xqual2kw5.xls is an Excel Workbook file for simultaneous calibration of up to four
synoptic surveys or branches. The xQUAL2Kw file allows for simultaneous manual or
automatic calibration with synoptic survey data from multiple simulation periods or
branches using the same kinetic rate parameters. To simulate a branching network of
streams, the tributary branch should be input in the first sheet, and the receiving branch
or mainstem in the following sheet(s), and formulas should be entered in the appropriate
input locations of the receiving branch or mainstem to link the output of predicted water
quality in the tributary branch for input as a point source in the receiving branch or
mainstem. Inputs and outputs are similar as for the qual2kw5.xls Workbook except that
the Worksheets are numbered (1), (2), (3), or (4) for one, two, three, or four surveys or
branches. All surveys or branches share the same ‘Rates’ Worksheet. The example
application is a simultaneous automatic calibration of two surveys of the Wenatchee
River conducted in August and September 2002.
- qual2kw5.exe is the Fortran executable. This file must be located in the same working
directory as the qual2kw5.xls and xqual2kw5.xls files.
- bc_1987-08-21.q2k is a sample input file for Boulder Creek
- qual2kw5_theory.doc is a Word document of the model theory and documentation
- qual2kw5_usermanual.doc is a Word document of user instructions for interpreting the
input and output Worksheets of the qual2kw5.xls file
- pelletier_et_al_2006.pdf, kannel_et_al_2007.pdf, and turner_et_al_2009.pdf are
copies of various journal articles describing the use of QUAL2Kw.