MAP-BASED SURFACE FLOW SIMULATION MODEL

Zichuan Ye, David R. Maidment, Francisco Olivera, Seann Reed, Daene C. McKinney
Center for Research in Water Resources
The University of Texas at Austin
ye@nile.crwr.utexas.edu

Table of contents

  • 1. Model Installation
  • 2. Model Description
  • 3. Performing Tasks under SFlowSim

    1. Model Installation

    To run the installation program, insert the Disk marked SFlowSim into drive a: and from C:\ prompt, type in:

    A:NGSETUP C:

    Where C:\ is the target drive on which the program will be installed. If the program is to be installed onto D:, then you should first move yourself to D: drive and from D:\ prompt, type in:

    A:NGSETUP D:

    Under default situation, NGSETUP program will copy the files onto C:\ drive and put all the project related files/coverages into C:\NGFLOW directory. If the directory does not exist, the setup program will create the directory. Upon the successful installation, the setup program will clean up all the unnecessary files it creates.

    If the programs are installed into C:\NGFLOW, a user can immediately start ArcView to load the project NGFLOW.APR that contains the map-based surface flow simulation model. If the model programs are installed into a directory other than C:\NGFLOW, e.g. C:\USERS\DEFAULT\NGFLOW, the user will need to load START.APR project. START.APR will prompt for the user to enter the path to the directory where NGFLOW.APR project is located. START.APR will then correct the path for NGFLOW.APR and load the project. The START.APR is acquired from ESRI with some minor modification to fit the project needs.

    2. Model Description

    2.1. GENERAL DESCRIPTION

    This map-based surface flow simulation model is contained in the NGFLOW.APR project. Figure 1 shows the view containing the themes upon which the simulation model is constructed. The themes contained in the Niger-View and their functions are discussed below.

    Figure 1. The view containing the base maps of the simulation model

    2.2 THE MAPS OF THE SIMULATION MODEL

    Listed below are the coverages representing the base maps upon which the surface flow simulation model is constructed.

    1. Drunoff - Point coverage representing the locations of daily runoff gage stations
    2. Mrunoff - Point coverage representing the locations of monthly runoff gage stations
    3. Dams.shp - Point coverage representing locations of dams and reservoirs
    4. Ngbasin.lbl - Label points of Ngbasin.ply. This coverage is needed for the construction of the map-based groundwater simulation model (GFlowSim).
    5. Flowchk.shp - Point coverage representing the locations where the flow interpolation will be computed
    6. Ngbasin.lin - An arc coverage representing the boundary lines of subwatershed polygons (Ngbasin.ply). This coverage is needed for the construction of the groundwater simulation model (GFlowSim)
    7. Ngriver.shp - An arc coverage representing the river stream network. This line coverage is essential for the construction of the map-based surface flow simulation model (SFlowSim)
    8. Ngbasin.ply - A polygon coverage representing the subwatershed of the river basin for surface flow simulation model and representing cells for the groundwater simulation model. This coverage is essential for the construction of both surface flow simulation model and groundwater flow simulation model.
    9. NGout - An arc coverage representing the outline of the whole river basin.

    2.3. MODEL'S GRAPHICAL USER INTERFACE

    The graphical user interface of the simulation model (SFlowSim) is designed to provide an easy access to the simulation model and model related programs. A user can use these graphical interfaces to activate the simulation model, modify the model conditions, add flow check points, flow diversion points, or add dam/reservoir objects. This section describes the functions associated with each user interface.

    2.3.1. View Menu

    Two menu sections, SFwModel and GFwModel are added to the standard ViewMenuBar GUI provided by the ArcView. SFwModel menu is created to run the surface flow simulation model and its related programs while GFwModel menu is created to run the groundwater flow simulation model and its related programs. Figure 2 shows the menu items contained in SFwModel and GFwModel menu.

    Figure 2. Menu items of SFwModel and GFwModel

    SFwModel contains ten menu items and these items are divided into the simulation model, utility and preprocessor sections. The utility section is shared by the groundwater simulation model and post-processors of surface flow simulation model. The functions of the menu items contained in each section are described below, with the title of the program it activates put in [ ].

    These five pre-processor programs (pre-1 to pre-5) need to be run in the same sequence as they are presented in the SFwModel ViewMenu.

    GFwModel contains 4 menu items and these items are divided into simulation mode and preprocessor sections. The functions of the menu items are described below, with the title of the program it activates put in [ ].

    All the pre-processor programs should only be run once to set up the map-based models unless the base maps of the model is modified.

    2.3.2. View Button Bar

    Four buttons are added to the standard ViewButtonBar GUI provided by the ArcView. The functions and programs associated with these buttons are explained below (immediately following each icon is the icon name given by ArcView's icon manager).

    - PennantGreen, interpolates flow rates to the points given by FlowChk.shp coverage [SFsegmt.pst].

    - Pen, writes selected or all the scripts contained in the project’s SEd to a designated location of a disk [wrtfiles.utl].

    - Cut, cuts selected portion of the active coverages and sends them to a new view to create a clipped model for either detailed study of the region or for model parameter fitting [clipmdl.utl].

    - Dog, runs interactive-optimization programs to search for the parameters that give the best fit between observed-flow-time-series and simulation model generated flow-time-series[Optimize.ave]. The best fit is defined either by least sum of square errors or least sum of mass differences. When running the model, at least one coverage theme must be active and at least one feature of the coverage has to be selected, because the parameters to be fitted are those of the active coverages and selected features.

    2.3.3. View Tool Bar

    Four buttons are added to the standard view button bar GUI provided by the ArcView. The functions and programs associated with these buttons are explained below.

    - Execute, runs all the programs available to SEd of the project [Main.utl - associated with apply event]. When the tool is selected, the program, Main.utl is loaded and activated when mouse is clicked at the cursor sensitive area of the active view. The last program run by the Main.utl is the default program to be run. If the user wants to run other programs, select NO option, and a pop-up menu will appear with a list of programs for the user to choice. The selected program will then run with the cursor position taken into consideration.

    - PennantRed, creates dam, reservoir, flow diversion, or flow-check point objects on a location selected by the program user. Programs associated with click and apply events are listed below.

    - Icon12, plots either the longitudinal flow profile along a user selected river stream or flow time-series (PFlow(t), FFlow(t), TFlow(t), or SurpFlow(t)), at a user selected location. Programs associated with click and apply events are listed below.

    - AlingBottom, plots flow vectors on groundwater simulation cell’s boundaries or plot time series of head(t), dh(t), spr(t), pmp(t), etc., of a cell at a user selected location. Programs associated with click and apply events are described below.

    2.4. MODEL PROGRAMS

    This map-based surface flow simulation model contains a total of 46 programs. Some of these programs are the essential programs for model construction and model simulation, and some of these programs are merely written to speed up routine spatial data processing. This section describes these programs and their functions. The number in the bracket following the program indicates the number of lines of the program code

    (1) chkftab.utl[34] - checks the data structures and shape type of a feature attribute table.

    (2) chktbl.utl[35] - checks the data structures of a value attribute table.

    (3) clipmdl.utl[184] - clips off a selected portion of the active coverage and sends them to a new view to create a clipped model for either detailed study of the region or for model parameter fitting.

    (4) Damrt.ave[208] - simulates dam/reservoir operation. This program is called by SFlowSim.prc when HASDAM attribute of a river line object is non-zero.

    (5) GFcntpnt.utl[132] - computes the center location of each arc on a selected line coverage and creates a point coverage showing all the central points based on the computation results. The program also computes and create line coverage showing the arcs normal to the original line coverage with each normal vector originates at the center of each line on the original line coverage.

    (6) GFlnfld.pre[291] - computes and fills in the states of each boundary lines of the existing cells for the groundwater simulation model.

    (7) GFlowSim.prc[916] - simulates groundwater flow. This is the main program of the map- based groundwater flow simulation model.

    (8) GFmdfld.pre[79] - appending fields to the standard polygon/arc coverage to create cells and cell boundary line objects for the map-based groundwater simulation model.

    (9) GFplyfld.pre[51] - computes and fills in the states of the existing cell objects for the groundwater simulation model.

    (10) GFptflx.pst[266] - plots flux on the cell boundaries, water levels on the cells or both for a user selected simulation time step or of final results of the groundwater simulation model. This is a post processor program of GFlowSim.

    (11) GFpthead.pst[141] - plots time series of water levels (head(t), dh(t), pmp(t)) of a user selected location. This is a post processor program of GFlowSim.

    (12) GFRplot.pst[36] - runs either [GFpthead.pst] or [GFptflx.pst] based on the user’s selection.

    (13) GFsetplt.pst[17] - provides user with options of plotting groundwater flow time series of a location or groundwater flux/water level of a designated time step and passed user’s selection to [GFRplot.pst]

    (14) IDextply.pst[88] - identifies the external boundaries of the groundwater simulation model. This program is used mainly on the clipped portion of the river basin to form a clipped-groundwater simulation model.

    (15) Iflw2pnt.utl[341] - interpolates flow rates to the points given by a point coverage.

    (16) Inifdfd.utl[58] - initializes a field of a table with the values of a field of another table based on the user selected key fields on both tables. These two key fields can have different field name, but their values need to have one-to-one relation.

    (17) Iniflda.utl[159] - sets all records of a user selected field to a single or multiple values.

    (18) Iniflds.utl[82] - sets selected records of a user selected field to a single or multiple values.

    (19) Initbl.utl[134] - sets all records of whole table or mutiple user selected fields to a single value.

    (20) Main.utl[46] - runs a user selected program.

    (21) MKarrow.utl[61] - makes an arrow head on a line coverage. This program is downloaded from ESRI user network with some minor modification.

    (22) Optimize.ave[855] - this is an interactive-optimization program used to search for the parameters that give the best fit between observed-flow-time-series and simulation model generated flow-time-series. The best fit is defined either by least sum of squre errors or least sum of mass differences. When running the model, at least one coverage theme must be active and at least one feature of the coverage has to be selected, because the parameters to be fitted are those of the active coverages and selected features. This program needs to call SFlowSim.prc repeatively to simulate the surface flow for each parameter change.

    (23) Rchktbl.utl[25] - Runs either [chkftab.utl] or [chktab.utl] based on the user’s selection.

    (24) Rinifld.utl[31] - Runs one of the four programs, [Iniflda.utl], [Iniflds.utl], [Initbl.utl], or [Inifdfd.utl] based on the user’s choice.

    (25) SFAdddam.pst[270] - creates a dam/reservoir object and puts it to the location designated by the user. The program also creates a time-series table associated with the dam object to record the simulation results of dam operation.

    (26) SFaddpt.pst[54] - creates a flow check point and puts it to a location designated by the user.

    (27) SFchklin.utl[85] - retrieves all the vertex points used to form a line and put the points shape into flowchk.shp file.

    (28) SFchkout.pre[156] - searches and identifies the head sections and outlet sections of a river basin.

    (29) SFclsset.pst[131] - gets user’s choice regarding the type point objects, dam, flow-check, or flow-diversion, to create and passes on the user’s selection to [SFRaddpt.pst].

    (30) SFDflow.pst[52] - creates a flow diversion points and put a mark on the map to indicate its location.

    (31) SFlowSim.prc[1244] - simulates surface flows on a river stream network based on the local flow time series defined on the subwatershed polygons. This is the major program of this map-based surface flow simulation model. This model can be activated by [Main.utl] from a tool-bar, SFlowSim on the SFwModel view menu, or called by [Optimize.ave], the interactive-optimization program. SFlowSim.prc can detect from which source it is activated and act accordingly. For example, when it is activated by from the ViewToolBar, the program will takes the cursors location into consideration, and as a result, it provides the user with choices of either simulates the whole river basin or the portion of the river basin that is above the user selected point (cursor location). When it is activated by from the view-menu, it can only simulate the river basin. When it is called by the optimization program, it will skip over all the codes that requires user interaction so that the simulation program can run uninterruptedly.

    (32) SFmdfld.pre[160] - appends fields to attribute tables of the arc/polygon coverage created by the river delineation procedure to create river and watershed objects.

    (33) SFmg1ln.pre[361] - merges multiple segments contained by a single subwatershed (polygon) into one single river section so that the relation between river section and subwatershed polygon is one-to-one [SFmg1ln.pre].

    (34) SFRaddpt.pst[39] runs one of the three programs, [SFaddpt.pst], [SFDFlow.pst], or [SFaddDam.pst], based on the user’s selection.

    (35) SFRplot.pst[36] - runs one of the two programs, [GFptflx.pst] or [GFpthead.pst], based on the value of the object-tag passed on to it from [GFsetplt.pst].

    (36) SFSegmt.pst[333] - linearly interpolates the flow rates to the user selected location.

    (37) SFsetplt.pst[17] - gets the choice from a user on which type of curve to plot and pass on the selection to [SFRplot.pst] through the form of object-tag.

    (38) SFsortr.pre[531] - sorts nodes and vertexes of river line coverage to create the river stream network [SFsortR.pre]. After sorting, the direction of From-Node to To-Node of a river section is always pointing to the downstream direction and the vertex with index 0 is at the From-Node of the arc.

    (39) SFsp2pf.121[84] - computes local generated flow based on the moisture surplus defined on the subwatershed polygons.

    (40) SFsplit.pre[532] - cleans the splits of the river sections so that "Y" shaped streams do not occur within a subwatershed [SFsplit.pre].

    (41) SFthmplt.pst[97] - plots spatial variation of a selected attribute based on its values at a selected time step.

    (42) SFtmplt.pst[134] - plots time series of a selected attribute at a selected location.

    (43) SFtrplt.pst[402] - plots flow rate changes along a user selected river stream.

    (44) tbaddrec.utl[69] - appending records to a time-series data table. The number of records is given by the user.

    (45) Wrtfiles.utl[85] - writes either selected or all the scripts contained in the project’s SEd to a designated location of a disk

    (46) Wrtprogs.utl[71] - writes an Avenue codes that can be later run to create the template of a time-series database.

    {46 FilesWrittenTo c:\ngflow\dosave at 1996:03:05-02:43:25 WithATotalOf 9259 lines}

    3. Performing Tasks under SFlowSim

    This section gives a brief description of the procedures to perform tasks using SFlowSim, the map-based surface flow simulation model.

    3.1. SURFACE FLOW SIMULATION

    The map-based surface flow simulation model is designed to simulate surface flow runoff based on the precipitation or soil moisture contents defined on the subwatersheds of a river basin. The running the simulation model will generates three flow time series, PFlow(t) associated with a subwatershed polygon representing the flow contribution of the polygon, FFlow(t), and TFlow(t) associated with From-Node and To-Node of a river arc representing the flow rates on the river arc at these two locations. Two procedures can be used to run the simulation model.

    3.2. CREATING DAM/FLOWCHK/DIVERSION OBJECTS

    The simulation model can simulate the effect of dams and flow diversions on the river flow. The simulation model can also interpolate the flow rate to any user selected point (flowchk) on a river arc. The procedure used to create a Dam/FlowChk/Diversion object and add it to the map is:

    3.3. INTERPOLATE THE FLOW RATES TO FLOWCHK POINTS

    This program interpolates the flow rates at all user selected points contained in FLOWCHK.SHP theme. To activate the program, a user can click on the (GreenFlag) on the ViewButtonBar.

    3.4. PLOT SURFACE FLOW PROFILES

    To plot the flow distribution, click on the ViewToolBar. Options for either plotting flow distribution along a selected stream or flow time series at a location will be prompted. If longitudinal flow profile is selected, a user can then click any location on the river stream network to plot the longitudinal flow profile along the river selected stream between the selected point and the outlet. If flow time series plot is selected, when user clicks at a location, the user is prompted to select if FFlow(t), TFlow(t), PFlow(t), or SurpFlow(t) will be plotted.

    3.5. PLOT GROUNDWATER FLOW RELATED ITEMS

    To make a plot, click on the ViewToolBar. Options for either plotting flux/head level distributions on groundwater cells at a given time or time distributions of water levels, water levels variations, etc., at a location will be prompted. After making selection, the user will then need to click on the basin map to activate the program and follow the instructions on the screen. For the Niger river model, groundwater model exist on under a portion of river basin.

    3.6. CREATE A CLIPPED-MODEL

    From time to time, it is necessary to perform a more detailed studies of a specific portion of a river basin. This map-based surface flow model allows part of a river basin to be clipped to form a separate model for more detailed studies. Niger river basin will be used as an example to describe how to create a workable clipped model.

    3.7. INTERACTIVE MODEL PARAMETER OPTIMIZATION

    The interactive optimization model is created to search for the model parameters that produce flow time series that best fit the historically observed time series in terms of sum of root mean square errors (SRMSE) and mass conservation (MASS). The results of the optimization are shown in two tables, optplot.dbf, and target.dbf, and four charts, optrmse.cht, optmass.cht, errfit.cht, and massfit.cht. Optplot.dbf contains sum of mean square errors, mass errors, and parameters of each simulation run activated by the optimization program. target.dbf contains the target time series (historic flow time series), two time series produced by the simulation that give the minimum (SRMSE) and (MASS). Four chart are the plots based on the data contained in these two tables. The procedures of running the interactive-optimization model are given below:

    3.8. MAP-BASED GROUNDWATER MODEL

    The map-based groundwater model (GFlowSim) is created to account for groundwater flows incorperation with the map-based surface flow simulation model (SFlowSim). The groundwater model usually uses the same subwatershed as its cells and cell boundaries. The groundwater model can cover the same area of the whole rvier basin or several seperate groundwater models can coexist under one single large river basin to simulate seperate groundwater systems. For the Niger River Basin Model presented, only one groundwater model is created to simulate the Iullmed aquifer system. The region that the groundwater model covers can be seen by making Ngbasin.lin active and quering with the condition of [ Hasgrd=1 and Isbnd=1]. The procedure to run the groundwater model is: (from ViewMenuBar)

    GFlwModel->GFlowSim and the follows the instructions provided by the program.

    3.9. WRITING SCRIPTS CONTAINED IN THE PROJECT TO DISK

    This program is written to facilitate writing all or selected script programs to a designated location at a computer disk. To activate the program, click on the ViewButtonBar and follows the instructions on the screen.

    3.10. CREATING TIME SERIES DATABASE TEMPLATE

    This program [Wrtprogs.utl] is written to create the template (class) of a time-series database. To run the program, click on the ViewToolBar followed by clicking at the View window. Select [Wrtprogs.utl] as the running program from the program list provided. Then select the theme that time series data is associated with and the key field that contains unique feature ID of the theme e.g. Cover_, or Cover_ID. The program will then write another program name [Atmp.ave] and running program [Atmp.ave] will create the time series database template needed.

    3.11. OTHER PROGRAMS

    This map-based simulation model also provide utility programs to perform various simulation model related tasks. These tasks includes checking data structure, field types of a value attribute table or feature attribute table, disintegrating a line into points, appending records to an existing database table, and flux line integration. More information about the utility programs can be found on section two of this document.