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

## BALANCE - Map Based Surface Water Quality Model

### 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

_deltat = time step, [T]
s = concentration, [M/V]
sb = boundary concentration, [M/V]
q = flow, [V/T]
ep = bulk dispersion coefficient, [V/T]
fdi = diffusive mass flux, [M/T]
v = volume, [V]
k = decay rate, [1/T]
wnp = nonpoint source waste load, [M/T]
wat = atmospheric waste load, [M/T]
wot = other waste load, [M/T]
wse = sediment waste load, [M/T]
wdi = net diffusive waste load, [M/T]
wd = decay waste load, [M/T]

Procedure

• For each polygon
wdi = 0

• For each line
• Calculate advective mass transport across the line
• get s from upstream polygon or sb if upstream is a boundary

• Calculate diffusive mass transport across the line
• get sl and sr from adjacent polygons or sb if adjacent is a boundary
fdi = ep * (sl - sr)

• For each polygon
• Compute concentration
• sold = s
wt
= wnp + wat + wot + wse - (k * v * sold) + wad + wdi
snew
= sold + (wt * (_deltat / v))
s = snew

### 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

q = flow
ep = bulk dispersion coefficient
sb = boundary concentration (only for boundary lines)

Polygon attributes

v = volume
k = decay rate
so = initial concentration

### 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:

fdi: diffusive mass transport

Polygon attribute table:

s: concentration

### 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.

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.

```------------------------------------------------------------------
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.

Specifies what load points to plot. See Figure 16.

Figure 16. Load Points Configuration Window.

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.

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.

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.

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:

Files = baynode.shp,.shx,.dbf, bayline.shp,.shx,.dbf, baypoly.shp,.shx,.dbf
Units system = SI
Projection = N/A

Suggested Run Control Parameters:

Delta t [hr] = 20
Converge delta s [mg/L] = 0
Diverge delta s [mg/L] = 10
Max t [hr] = 1000
User Observation Level (0-4) = 3

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:

Files = rivnode.shp,.shx,.dbf, rivline.shp,.shx,.dbf, rivpoly.shp,.shx,.dbf
Units system = SI
Projection = N/A

Suggested Run Control Parameters:

Delta t [hr] = 0.02
Converge delta s [mg/L] = 0
Diverge delta s [mg/L] = 20
Max t [hr] = 0.5
User Observation Level (0-4) = 3

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:

Files = ccbmnode.shp,.shx,.dbf, ccbmline.shp,.shx,.dbf, ccbmpoly.shp,.shx,.dbf
Units system = SI
Projection = Texas State Mapping System (TSMS)

Suggested Run Control Parameters:

Delta t [hr] = 10
Converge delta s [mg/L] = 0
Diverge delta s [mg/L] = 10000
Max t [hr] = 30000
User Observation Level (0-4) = 1

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.

Description: This program is a simple utility. It displays general information (version, date, etc.) about BALANCE.

Mass Balance Program (balance)

Description: This program calculates the actual mass balance.

Source Code: balance.txt

Flux Vector Drawing Utility (balar)

Description: This program creates the actual vector shapes that will be used by balplot to plot flux vectors.

Source Code: balar.txt

Description: This program creates the actual rectangle shapes that will be used by balplot to plot load points.

Source Code: balcir.txt

General Configuration Utility (balcon)

Description: This program is a simple configuration menu. It calls either the Units Configuration or the Plotting Configuration utilities.

Source Code: balcon.txt

Plotting Configuration Utility (balconp)

Description: This program is a menu for modifying plotting parameters, like what is plotted in what colors, etc. This data is stored in global variables.

Source Code: balconp.txt

Units Configuration Utility (balconu)

Description: This program is a menu for choosing a units system.

Source Code: balconu.txt

Information Tool (balinfo)

Description: This program is a tool for viewing mass balance parameters of lines or polygons by clicking on them.

Source Code: balinfo.txt

Modification Tool (balmod)

Description: This program is a tool for modifying mass balance parameters of lines or polygons by clicking on them.

Source Code: balmod.txt

Plotting Program (balplot)

Description: This program plots flux vectors and/or load points.

Source Code: balplot.txt

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)

Description: This program calculates the bulk dispersion coefficient from the dispersion coefficient cross sectional area (or length and depth) and mixing length. The bulk dispersion coefficient is written to the ep field in the polygon attribute table.

Status: Needs check.

Source Code:calcep.txt

Area Utility (calcarea)

Description: This program calculates the area for each segment. The area is written to the a field in the polygon attribute table.

Status: Needs check.

Source Code: calcarea.txt

Volume Utility (calcvol)

Description: This program calculates the volume for each segment from area and depth. The volume is written to the v field in the polygon attribute table.

Status: Needs check.

Source Code: calcvol.txt

Attribute Edit Utility (editatt)

Description: This program is for modifying attribute values. It provides point and click attribute edit capabilities for themes. It is easily customized to modify the desired field in the attribute table.

Status: Done.

Source Code: editatt.txt

Grid Pick Utility (pickgrid)

Description: This program picks up a value from a grid with the cellvalue request for each centroid in a polygon coverage. The value is written to a field chosen by the user in the polygon attribute table.

Status: Done.

Source Code: pickgrid.txt

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)

Description: AGREE is a surface reconditioning system for Digital Elevation Models (DEMs). The system adjusts the surface elevation of the DEM to be consistent with a vector coverage. The vector coverage can be a stream or ridge line coverage. Also check out the AGREE Home Page

Status: Done.

Source Code:agree.txt

Runoff grid calculator (concgrid)

Description: This program calculates a runoff grid from a precipitation theme using the .con request, which is not available in the map calculator.

Status: Done. Could be made more flexible, by letting the user enter the formula.

Source Code:rogrid.txt

Concentration grid calculator (concgrid)

Description: This program calculates a runoff concentration grid from a landuse polygon theme using a specified field in the polygon theme's attribute table. The program uses the .makefromftab request which is not available from the pull-down menus of the Spatial Analyst or Hydrology Extensions.

Status: Done. Could be expanded to work if EMC table is linked to landuse theme.

Source Code:concgrid.txt

Weighted flow accumulation grid calculator (wfacgrid)

Description: This program calculates a weighted flow accumulation grid from a load grid and a flow direction grid using the .flowaccumulation request which is not available from the pull-down menus of the Spatial Analyst or Hydrology Extensions.

Status: Done.

Source Code:wfacgrid.txt

Sink Dig Utility (connect)

Description: This program digs sinks corresponding to polygons into a DEM. To be used together with pickload. Has a problem when the centroid of the polygon is outside the polygon boundary. If such a polygon is detected the user is warned.

Status: Done in ArcView Avenue and ARC/INFO AML. Can the program be modified to handle polygons with centroids outside the polygon boundary?

Source Code: Avenue: connect.txt, AML: connect.aml

Description: This program picks up the nonpoint source load for each polygon from a nonpoint source load (weighted flow accumulation) grid with the cellvalue request. To be used together with connect. The nonpoint source load is written to the wnp field in the polygon attribute table. There is an instability problem at the center of the sink, which is avoided by actually taking the sum of the cellvalues on a 5x5 perimeter. See the code for more information.

Status: Done in ArcView Avenue and ARC/INFO AML.

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

Description: There is a problem with the boundary conditions when using the English units system. The work around is to use SI units for now.
Version: 1.0, 01/11/97
Operating System: DEC Alpha, UNIX System V
Provided by:Andrew Tachovsky

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.