Last updated 05/24/97 - GISHydro97 CD Version
Ferdi Hellweger

BALANCE - Map Based Surface Water Quality Model

TABLE OF CONTENTS

1. INTRODUCTION

The Corpus Christi Bay estuary system is currently being studied under the Corpus Christi Bay National Estuary Program (CCBNEP). As part of the program a research project entitled Estimation of Total Constituent Loadings to the Corpus Christi Bay System is conducted at The University of Texas at Austin. Besides estimating total constituent loadings to the bay system the project includes the calculation of a constituent mass balance in the bay system. For that calculation software is needed. The software developed for this purpose is documented here.

BALANCE is a map based surface water quality model. The system runs inside a GIS environment and computes a constituent mass balance for surface water segments, plotting mass fluxes and loads as it goes. The system uses an explicit finite differences algorithm. BALANCE is written in ArcView's Avenue programming language.

For a quick start on BALANCE try the BALANCE Salinity Modeling Exercise on this CD or simple run the program on the sample data described later on this page. All the data files are included on the CD.

2. METHODOLOGY

The system computes a constituent mass balance using an explicit finite differences algorithm. The Avenue code for the main computation program is available on Internet . The simplified procedure for each time step is described below.

Variables

Procedure

3. SYSTEM INPUT

The required input data consist of a line and a polygon ARC/INFO coverage or shape file. The two data sets need to be topologically connected. The polygons need to be numbered with the universe polygon being assigned the number 1. The attribute table of the line coverage (or shape file) needs to contain fields indicating the number of the left and right polygon (lpoly#, rpoly#).

Several attributes need to be specified for the lines and polygons. A utility is available to assign and modify those attributes. If the fields are not present in the attribute tables the system will create them. Specifically the following attributes need to be specified:

Line attributes

Polygon attributes

4. SYSTEM OUTPUT

The system output consist of the mass balance terms of the last time step. That data is stored in the attribute table of the polygon and line coverages (or shape files). The following data is stored:

Line attribute table:

Polygon attribute table:

5. USING THE SYSTEM

Note: If you are new to ArcView you might want to do the exercise entitled Introduction to ArcView.

Note: If you are new to BALANCE you might want to use the Simple Bay sample data to get started. That data was used to create the figures in this section.

The system is in the form of an ArcView project which can be opened in ArcView like a file. In addition to the project you will need to load the data. Once the View with the data is active you will see a few buttons (C, P, B, M, I) appear at the top left of the ArcView window. Those buttons control BALANCE. Alternatively, you can control BALANCE from the 'Balance' pull-down menu. Figure 1 illustrates.




Figure 1. Typical Screen.

5.a. Configuring Units

The system supports SI, English and Generic units. To configure the units click on the configuration (C) button. Figure 2 shows the configuration menu.




Figure 2. Configuration Menu.

Click on 'Units' to bring up the units configuration menu and choose the desired system of units. Figure 3 shows the units configuration menu and Table 1 lists the details of each of the units systems.




Figure 3. Units Configuration Menu. 

------------------------------------------------------------------
System   Load     Conc.  Decay  Volume  Area  Flow   Bulk Disp.
         (w)      (s)    (k)    (v)     (a)   (q)    (ep)

SI       kg/day   mg/L   1/day  m^3     m^2   m^3/s  m^3/s

English  lbs/day  mg/L   1/day  ft^3    ft^2  cfs    cfs

Generic  M/T      M/V    1/T    V       A     V/T    V/T
------------------------------------------------------------------

Table 1. Unit Systems.

5.b. Entering/Modifying Attribute Data

The attribute data used by BALANCE is attached to the lines and polygons. To modify the attributes of a feature make the modify attributes tool active by clicking on the (M) button. Then make the corresponding theme active by clicking on it in the View's legend. Clicking on features brings up the feature attribute modification windows. Figure 4 shows the attribute modification window for an interior line and Figure 5 shows the attribute modification window for a boundary line. Note that flows are specified as positive or negative. A black vector is plotted on the line in the positive direction to serve as a reference to the user. Figure 6 shows the attribute modification window for a polygon.




Figure 4. Interior Line Attribute Modification Window.




Figure 5. Boundary Line Attribute Modification Window.




Figure 6. Polygon Attribute Modification Window.

5.c. Computing Mass Balance

To compute the constituent mass balance activate the line and polygon themes by clicking on them in the View's legend. Then click on the (B) button. You will need to specify run control parameters as shown in Figure 7. Run control parameters are described further in Tables 2 and 3.




Figure 7. Run Control Parameter Input Window. 

---------------------------------------------------------------------------------
Parameter               Description

Delta t                 Time step used.

Converge delta s        If the maximum change in concentration from one time step
                        to the next is smaller than this value the system assumes
                        steady state is reached and stops the computation.

Diverge delta s         If the maximum change in concentration from one time step
                        to the next is larger than this value the system assumes
                        unstable conditions and stops the computation.

Max t                   Maximum time for the computation.

User Observation Level  Specifies the amount of information conveyed to the user
                        during computation.  See Table 3.
---------------------------------------------------------------------------------

Table 2. Run Control Parameters. 

---------------------------------------------------------------------------------
Level  Description

  0    Not used yet.

  1    The ArcView status bar is updated periodically.  Information displayed
       includes time, maximum change in concentration from last step and percent
       of maximum time.

  2    In addition to 1, the legend is updated periodically.  This is useful if,
       for example, the polygons are colored based on concentration.

  3    In addition to 2, the mass balance terms are plotted (see the section on
       plotting the results).

  4    In addition to 3, the system pauses after every time step and displays the
       time and maximum change in concentration from last step.
---------------------------------------------------------------------------------

Table 3. User Observation Levels.

The computation can stop for four different reasons:

  1. BALANCE converged (Converge delta s).
  2. BALANCE diverged (Diverge delta s).
  3. BALANCE time limit reached (Max t).
  4. BALANCE stopped by user (user clicked on 'Stop' button).

The system will display the reason for stopping as well as the time and maximum change in concentration in the last time step as shown in Figure 8.




Figure 8. Run End Message.

5.d. Examining Results

The results of the mass balance computation are written to the attribute tables of the data sets. To examine the results for a feature make the information tool active by clicking on the (I) button. Then make the corresponding theme active by clicking on it in the View's legend. Clicking on features brings up the feature information screen. Line and polygon information screens are shown in Figures 9 and 10, respectively.




Figure 9. Line Information Message.




Figure 10. Polygon Information Message.

5.e. Plotting Results

The system has a plot utility which can plot mass fluxes and loads. This utility is invoked by clicking on the plot (P) button. Note that the themes for which the mass balance terms are to be plotted have to be active. If, for example, only the line theme is active, only the mass fluxes (not the load points) will be plotted.

Plotting is completely user configurable. To configure plotting click on the configuration (C) button and choose 'Plot Parameters'. The plot parameter configuration menu is shown in Figure 11. Following that is a detailed description of all the sub menus




Figure 11. Plot Parameter Modification Menu.

Flux Vectors

Specifies what flux vectors to plot. See Figure 12.




Figure 12. Flux Vector Configuration Window.

Flux Vector Locations

Specifies the locations for the flux vectors as a fraction of the line. See Figure 13.




Figure 13. Flux Vector Locations Configuration Window.

Flux Vector Scales

Specifies the plotting scale for the flux vectors. The user specifies the magnitude which will be plotted at 1/10th of the View window size. If the user specifies 0 the maximum magnitude will be plotted at 1/10th of the View window size. Note that the maximum magnitude changes from time step to time step, which means that if the user specifies 0 the plotting scale changes during the computation (only applicable for user observation level greater than 2). See Figure 14.




Figure 14. Flux Vector Scales Configuration Window.

Flux Vector Colors

Specifies what colors to use for flux vector plotting. The user can specify black, blue, cyan, gray, green, magenta, red, white and yellow. See Figure 15.




Figure 15. Flux Vector Colors Configuration Window.

Load Points

Specifies what load points to plot. See Figure 16.




Figure 16. Load Points Configuration Window.

Load Point Locations

Specifies the plotting locations for the load points. The load points are plotted on a circle around the centroid of the polygon. The user specifies the location of the load point plot on that circle by specifying the angle from the north direction. See Figure 17.




Figure 17. Load Point Locations Configuration Window.

Load Point Scale

Specifies the plotting scale for the load points. The user specifies the magnitude which will be plotted at 1/10th of the View window size. If the user specifies 0 the maximum magnitude will be plotted at 1/10th the View window size. Note that the maximum magnitude changes from time step to time step, which means that if the user specifies 0 the plotting scale changes during the computation (only applicable for user observation level greater than 2). See Figure 18.




Figure 18. Load Point Scale Configuration Window.

load Point Colors

Specifies what colors to use for load point plotting. The user can specify black, blue, cyan, gray, green, magenta, red, white and yellow. See Figure 19.




Figure 19. Load Point Colors Configuration Window.

6. GETTING THE SYSTEM

The system is in the form of an ArcView project. That project can be opened with ArcView like a file. The project as well as the sample data is located on the CD and can be downloaded via anonymous ftp as well.

Note: If you are new to ftp you might want to read the page entitled Getting Data From CRWR's Anonymous FTP Site.

Address: ftp.crwr.utexas.edu
Login: anonymous
Password: your e-mail address
Directory: /pub/crwr/gishydro/balance
Transfer Mode: binary
Files:
Program: balance.apr
Simple Bay Sample Data: baynode.shp,.shx,.dbf, bayline.shp,.shx,.dbf, baypoly.shp,.shx,.dbf
Simple River Sample Data: rivnode.shp,.shx,.dbf, rivline.shp,.shx,.dbf, rivpoly.shp,.shx,.dbf
Corpus Christi Bay System Sample Data: ccbmnode.shp,.shx,.dbf, ccbmline.shp,.shx,.dbf, ccbmpoly.shp,.shx,.dbf

Attention PC CD Users:
The files on the CD are read-only. To run the exercise you will need to copy the files to the hard drive of your computer or another location where you have write permission. When doing so it is best to use the DOS XCOPY command (rather than drag-and-drop in Windows). Using this command will make sure the files are not marked as read-only after you copied them. Follow these steps to copy data from the CD:

  1. Go to DOS.
  2. Go to the CD drive.
  3. Change to the module directory (i.e. terrain, prepro)
  4. Type: xcopy gisfiles destination_path /E

7. SAMPLE DATA

Three sample data sets can be downloaded with the system. The sample data sets consist of node, line and polygon shape files. Note that allthough node shape files are not used by BALANCE, they provide a good way to locate the endpoints of lines. All data sets are ready to run with attribute data already entered.

7.a. Simple Bay

The Simple Bay sample data is based on Sample Problem 3.5 (c), Thomann and Mueller, Principles of Surface Water Quality Modeling and Control, 1987. The bay consists of two segments as shown in Figure 20. The upper segment receives inflow and is subject to diversion flow (5 x inflow). The boundaries between the two segments and to the ocean are diffusive. There is decay. The lower segment is connected to the ocean which has a constituent concentration of 1 mg/L.

Due to the large flow diversion there is a net inflow into the bay from the ocean, causing advective mass transport into the bay. Advective mass transport is indicated by green vectors. The net advective load is indicated by the green squares in the segments. There is also diffusion from the ocean into the bay. The diffusive mass transport and net diffusive loads are indicated by the blue vectors and squares, respectively. The decay load is indicated by the yellow squares. The resulting concentrations for the upper and lower segments are 0.2016 mg/L and 0.3457 mg/L, respectively. Those concentrations are consistent with the analytical solution.




Figure 20. Bay Sample Data.

Other Information:

Suggested Run Control Parameters:

7.b. Simple River

The Simple River sample data represents a river divided into 10 segments as shown in Figure 21. Flow is from left to right. All inter-segment boundaries are diffusive. There is no decay. There is a background concentration in the river. There is a point source waste input into the fifth segment.

There is advective mass transport in the direction of flow as indicated with the green vectors. The green vectors upstream of the point source are due to the background concentration. There is diffusive transport in the upstream direction source due to the concentration gradient. Diffusive mass transport is indicated with the blue vectors.




Figure 21. River Sample Data.

Other Information:

Suggested Run Control Parameters:

7.c. Corpus Christi Bay System

The Corpus Christi Bay System sample data consists of 23 segments as shown in Figure 22. The constituent modeled is salinity. There is inflow at several locations. All inter-segment boundaries are diffusive. There are diffusive boundaries to the ocean as well as to bay systems to the north and south. Note that this data was developed to test BALANCE. The segmentation and all attribute data are only very rough ballpark estimates.

There is advective mass transport in the direction of flow as indicated with the green vectors. There is dispersive transport as indicated with the blue vectors. The results compare well with the analytical solution.




Figure 22. Corpus Christi Bay Sample Data.

Other Information:

Suggested Run Control Parameters:

8. DEVELOPER'S CORNER

This section is designed for people who want to take a closer look at BALANCE. This includes students wanting to learn more about Avenue programming and developers working on their own modified version of BALANCE. The section consists of two parts. The first part lists and describes the standard programs. The second part is designated to Pro version utilities. Pro version utilities are used to prepare input data for BALANCE. Please e-mail Ferdi if you have a program that could be helpful to others.

8.a. Standard BALANCE Programs

The standard BALANCE system consists of 11 Avenue scripts. Following is a listing of them in alphabetical order. A short description is given and the source code is provided. More detailed description is provided in the code with comments.

Info Message Utility (balabout)

Mass Balance Program (balance)

Flux Vector Drawing Utility (balar)

Load Point Drawing Utility (balcir)

General Configuration Utility (balcon)

Plotting Configuration Utility (balconp)

Units Configuration Utility (balconu)

Information Tool (balinfo)

Modification Tool (balmod)

Plotting Program (balplot)

8.b. BALANCE Pro Version Utilities

This section lists Avenue utility programs designed to work with BALANCE. This area is currently being researched and will be updated as utilities are developed.

Bulk Dispersion Coefficient Utility (calcep)

Area Utility (calcarea)

Volume Utility (calcvol)

Attribute Edit Utility (editatt)

Grid Pick Utility (pickgrid)

8.c. BALANCE Nonpoint Source Pollution Utilities

This section lists Avenue utility programs designed to work with BALANCE. These programs are for preparing nonpoint source pollution inputs to BALANCE.

AGREE: DEM Surface Reconditioning System (agree)

Runoff grid calculator (concgrid)

Concentration grid calculator (concgrid)

Weighted flow accumulation grid calculator (wfacgrid)

Sink Dig Utility (connect)

Nonpoint Source Load Utility (pickload)

9. KNOWN BUGS

This section lists known bugs that are being worked on. Please e-mail Ferdi if you know of a bug that is not listed here.

English Units System - Boundary Conditions

10. BALANCE APPLICATIONS

This section lists web pages of BALANCE applications. Please e-mail Ferdi if you know of a resource that should be listed here.

These materials may be used for study, research, and education, but please credit the authors and the Center for Research in Water Resources, The University of Texas at Austin. All commercial rights reserved. Copyright 1997 Center for Research in Water Resources.