CE-QUAL-R1/CE-THERM-R1 Model

(A Numerical One-Dimensional Model of
Reservoir Water Quality)
MS-DOS
v4.0
March 1993
Yes (PDF)
USACE-WES
CE-QUAL-R1 is mathematical model of water quality that describes the vertical distribution of thermal energy and biological and chemical materials in a reservoir through time.

  The model requires CQR.DAT, an extensive data base including initial conditions, geometric and physical coefficients, biological and chemical rates, and time sequences of hydrometeorological and inflowing water quality concentrations.

CE-THERM-R1 The thermal analysis portion of CE-QUAL-R1 is provided as an independent model, called CE-THERM-R1, to simplify simulation of water budgets and temperature profiles. CE-THERM-R1 includes the variables of temperature, suspended solids, and total dissolved solids. The data set required by CE-THERM-R1 is CQT.DAT

Detailed CE-QUAL-R1/CE-THERM-R1 model installation guide is available.

INTRODUCTION

  The purpose of the windows package is to create a user-friendly environment for which to run the water quality models and utilities. Features such as keyboard and mouse controlled cursor movent, dynamic menu and status bars, interactive windows for prompts and inputs, sophisticated error messages, and on- line-help with searching capabilities, are included for user convenience.

Although still in the testing phase, all error checking has been carefully thought out and incorporated in such a way as to alert the user in an informative manner. However, it is impossible to cover all details 100 percent of the time; therefore, it is essential that any bugs be reported to the producers of this program immediately. Corrections will be made promptly and a new version will be return as soon as possible.

WESWIN

  WESWIN is an interactive window package designed to execute the water quality modeling programs, CE-QUAL-R1 and CE-THERM-R1, and the utilities associated with the models provided by the U.S. Army Corps of Engineers. The utilities provided are as follows:

  1. CQRTSM -- preprocessor for CE-QUAL-R1
  2. CQTTSM -- preprocessor of CE-THERM-R1
  3. STSTIC -- statistical analysis
  4. GRAFORM -- data manipulation
  5. FLUX -- (not working at the present)

Each interactive window can be activated by moving the cursor desired option found on the menu bar and pressing enter. Cursor movement is achieved by using the ARROW key that corresponds to the direction of movement. The available options found on the menu bar are as follow:

  1. Execute
  2. Plot
  3. Help
  4. Quit

The execute option activates an interactive window that contains the executable water quality programs and utilities. Before a program is executed, the directory is checked for that program's internal files. These internal files are checked for their presence in the directory. If the internal file is an input file then the file must be present, and if the internal file is an output file then the file must NOT be present because the fortran programs will not overwrite output files. If the output file is present then the user has the option to rename or delete the file. An output file, if renamed, will be renamed using the extension OLD. At the present time, the program will terminate on input file errors. Future revisions of the internal file check program will support more intelligent subroutines in which a messages will be echoed to the screen informing the user of which water quality programs should be executed to produce a particular input file.

The plotting option runs WESPLOT, an interactive plotting program which assists the user in comparing the predicted and observed values. The help option activates a topic index window that allows the user to select a topic in which help is needed. After the help document is displayed the user can scroll up or down the page one line at a time using the ARROW keys. The PAGE UP and PAGE DOWN keys will toggle to a new screen of text. The HOME key sets the document to the first page and the END key will move to the last page of text. At any time, the user may use ALT-S to re-activate the topic index window.

Anytime an interactive window is open, a status bar that supports that window will appear at the bottom of the screen. The status bar does more than list the available commands associated with the open window. If user is using a mouse, then placing the mouse on the status bar command and clicking the left button will initiate that particular command.

PREPROCESSORS

  Data set preprocessors have been developed for both CE-QUAL-R1 and CE-THERM-R1 water quality models. The preprocessor for CE-QUAL-R1 data sets will be referred to as "CQRTSM," and the preprocessor for CE-THERM-R1 data sets will be referred to as "CQTTSM." Each preprocessor is designed to check the sequence of records required and whether each field of data on each record is the correct type of variable value expected by the models. Secondly, certain variable values and coefficients are compared with established ranges of values to see if the values fall within preestablished limitations.

Before attempting to run either preprocessor, it is recommended that the user review Appendixes C and D. Appendix C provides a dot diagram for CE-QUAL-R1 and CE-THERM-R1 data sets. These diagrams indicate precisely which records are required for any particular option the user may choose. It is correct to assume that the data set for any particular option will not include all of the records indicated in the listings for either model. The sequence in which the records appear in the dot diagram is, however, the sequencing required by the models for the data sets. The preprocessors will flag as an error any deviation from the expected sequence of required records in either model. In addition, Appendix D presents detailed information concerning the data set structure for CE-QUAL-R1 and CE-THERM-R1. A complete listing of all of the records required by any of the options available for CE-QUAL-R1 and CE-THERM-R1 is provided. The variable name for each item of data that should appear in each field of each record is also shown.

In order to make efficient use of the preprocessor, certain data set conventions must be adopted.

  1. ach record must begin with the appropriate record label.
  2. Fields representing integer data must NOT contain a decimal point.
  3. Fields representing real data must contain a decimal point.
  4. No, or zero, flow from a port must be recorded as a "0."

The preprocessors have two parts. Part I of the preprocessor is a type and sequence analysis of the data set. The preprocessor searches for missing records and incorrect data. It checks the sequence of records to verify that all required records for the particular option selected are included in the data set in the proper order. Each field of data on each successive record is compared with model expectations to verify that real data occur where real data are expected and integer data occur where integer data are expected. Error messages are produced when record labels or fields of data deviate from expected types in the model.

NOTE: Part I does not provide any information concerning the size or reasonableness of any particular entry in the data set.

Part I ceases its search for errors when 20 errors have been accumulated. This feature was installed as a safeguard since the omission of a single expected record could make an otherwise correct data set appear error ridden. All errors noted by Part I must be corrected in the data set before Part II will execute.

Part II compares certain variable values and coefficients against arbitrarily established ranges or values based on experience in working with the model. The execution of Part II involves comparing certain selected variable values and coefficients against preestablished ranges or values. Output from this part of the preprocessor is informational in nature and requires judgments on the part of the user as to the need to alter data set values.

Additional information about the preprocessors may be obtain from the user's manual, pages 375-383.

GRAFORM

  Two utilities, WESPLOT and STSTIC, which are subsequently explained, need only a small fraction of the in-pool data generated and saved, on file, by the models (see FILES record, Part IV). The Data Manipulation utility, referred to as "GRAFORM," chooses from that file only data which correspond to dates when measured data are available, and stores them in a manner suitable for the Plotting and Statistics utilities.

Two files are needed for this utility. The first file, PLTWC.DAT, contains data generated by CE-QUAL-R1. The file (PLTWC) is named in field 2 of the FILES record with the extension (.DAT) added to the name by the program during execution. The second file, GRAIN5.DAT, is a user created file that contains the sampling periods. Information on creating this file can be found in the user's manual on pages 384-385.

STSTIC

  This utility allows the user to obtain a statistical analysis of model predictions when compared to field-measured values. Statistics include the following:

  1. reliability index (Leggett and Williams 1981);
  2. paired t-test for means (Sokal and Rohlf 1969);
  3. normalized mean error (Gordon 1981, see also Wlosinski 1982); and
  4. coefficients for the linear regression equation for plotting observed versus predicted values (Thomann 1980).

Mean values for observed and predicted data are also given. The statistics are calculated for each variable over all depths for which data were collected, as well as for each variable over depths and times.

Information on these statistics is presented in Wlosinski (1984). The reliability index has been found, in past studies, to be a good statistic for comparisons because its value does not depend on whether the observed or predicted value is greater. Also, because it is scale variant, results from different variables can be aggregated and compared. The value of the reliability index would be 1.0 in the case of perfect production. If all comparisons are an average of one-half order of magnitude apart, the value of the reliability index would be 5.0.

Because the value of the index is based on the order of magnitude difference between measured and predicted values, results may be misleading if zero values are entered for measured data. CE-QUAL-R1 does not allow zero values to be predicted for certain variables. Instead, a small positive value, at or below normal detection limits, is maintained. This same positive value should be used if measured data are reported as zero. Table 40 contains these small positive values. The file containing the field-measured data is the same file used for the Plotting utility.

To execute the statistical package, three files are needed. The first file, VER.DAT, is a user created file which contains the observed values for a given constitute and given date (see pages 389-391 in the user's manual). The second file, GRAOTP.DAT, is created by the Data Manipulation utility, GRAFORM. STSWICH.DAT, the third file, is a one-line file that contains information on the variables that the statistics will be preformed.

WESPLOT

  WESPLOT is an interactive graphics program which enables the user to compare a set of measured data to the same set of predicted values that are produced by CE-QUAL-R1 or CE-THERM-R1. WESPLOT requires several files in order to execute properly. The first file is FILE15.DAT which contains information that specifies the variables and dates that are to be plotted. FILE15 is a user prepared data file and the file format can be obtained from the user's manual, pages 386-389. The second file, GRAOTP.DAT, contains simulation data supplied by the Data Manipulation utility. GRAOTP.DAT is created by GRAFORM.EXE using data created by the modeling programs. VER.DAT is the third file and it contains field-measured values. VER.DAT is a user prepared data file and information concerning the this file can be found on pages 389-390 in the user's manual.

WESPLOT begins execution by prompting the user for the procedure in which to select the maximum X and Y values. These maximum values make comparing each graph easier. The two procedures are as follows:

  1. User selected - the user is prompted for the maximum Y and the maximum X.
  2. Program selected - the program will read GRAOTP.DAT and VER.DAT and from these files determine the maximum values.

Once the maximum values have been determined the program will use these values for each plot. To change these values will require exiting the program.

Next the program will prompt the user for the display option. The five options are as follows:

  1. Print four plots per page to the screen.
  2. Print one plot per page to the screen.
  3. Print four plots per page to the printer.
  4. Print one plot per page to the printer.
  5. Print all the plot (four per page) to the printer.

Finally, the program will read FILE15.DAT and display the plotting constitute and dates to an interactive window (unless option 5 is selected). The user must then select the set they wish to plot.

NOTE: If option 2 is selected then the BACKSPACE key will cycle backward through the dates and the ESC key will exit.

FILE15

  FILE15.DAT is a user created file that is used by WESPLOT. Information in the user's manual on pages 387-389 explain the proper file format.

File Size Download
CE-QUAL-R1/CE-THERM-R1 model installation guide  
CE-QUAL-R1/CE-THERM-R1 models 1.17 MB
CE-THERM-R1 Sample Datafile (CQT.DAT) with annotations  
CE-QUAL-R1/CE-THERM-R1 User's Manual 26.9 MB