Hydrologic Simulation with Arc Hydro libHydro and Model Builder by yxx13897

VIEWS: 183 PAGES: 15

									Hydrologic Simulation with Arc Hydro, libHydro, and
                  Model Builder



                       Tim Whitaker

           Center for Research in Water Resources

                University of Texas at Austin



                       May 14, 2003
                                    1 Introduction
The ArcGIS Hydro data model (Arc Hydro) provides a structure for storing and
preprocessing GIS data for use in hydrologic simulation models. While Arc Hydro does
not perform any actual simulations, the products of Arc Hydro can be linked to
simulation processes through ArcGIS 9's Model Builder technology. This paper
demonstrates how to use Model Builder to link Arc Hydro data with simulation processes
from the HEC's library of subroutines known as libHydro.

This paper is divided into five chapters. The first chapter provides an introduction to the
research. The second chapter provides background information, including scope of work
and study area description. The third chapter describes the methodology used in this
research. The fourth chapter presents results, while the fifth chapter draws conclusions
based on those results.
2 Background
2.1 Arc Hydro
Arc Hydro is a water resources data model that provides a structure for storing geospatial
and temporal data, which facilitates the linkage of that data with hydrologic simulation
models. Arc Hydro is designed to work with the ESRI ArcGIS family of products.

This research utilizes Arc Hydro to provide an association between geospatial features
and time series data. Each feature in Arc Hydro is indexed with a unique identifier called
the HydroID. Each time series record contains a FeatureID, which points to the HydroID
of the feature associated with that time series record. All time series records are stored in
a table called TimeSeries. In addition to the FeatureID, these records have an attribute
called TSTypeID. The TSTypeID groups a particular set of time series records into a
certain type. For example, all rainfall time series data could be assigned a TSTypeID of
7, while streamflow time series could have a TSTypeID of 9.

Thus, if searching for rainfall data associated with a Watershed feature with a HydroID of
256, the TimeSeries table could be queried for data with TSTypeID = 7 and FeatureID =
256. Or if all rainfall data are desired, then the TimeSeries table could simply be queried
for data with TSTypeID = 7.

These types of queries are used in this research to identify time series for a given set of
features. More information on Arc Hydro can be found at the Arc Hydro Online Support
System, http://www.crwr.utexas.edu/giswr/hydro/ArcHOSS/model/index.cfm.

2.2 LibHydro
The US Army Corps of Engineers Hydrologic Engineering Center (HEC) has produced
hydrologic and hydraulic simulation models for several decades. These models typically
consist of graphical user interfaces that send inputs from the user to a set of procedures
for performing the simulations. The HEC has organized those procedures into a library
of functions called libHydro. With libHydro, the same routines for determining
precipitation excess, calculating runoff, routing hydrographs, etc., can be called from any
program. Thus, an application developed by an end user can take advantage of
simulation routines that have been proven through decades of use.

The functions in libHydro are stored in a DLL (dynamic linked library). A DLL is not a
file that can be run on its own. Rather, a DLL is called from an existing application. A
graduate student named Masatsugu Takematsu at the University of Texas at Austin has
created a methodology and Visual Basic module for calling the functions in libHydro.
This research uses that module to access libHydro. More information on libHydro and
the functions that may be called from it are available at Takematsu's website,
http://civilu.ce.utexas.edu/stu/takamam/lh_home.htm.
2.3 ArcToolbox
The ArcGIS 9 ArcToolbox allows the user to create custom tools in addition to the
standard tools provided with ArcGIS. These tools can be created as script tools or model
tools.

Script Tools
Script tools send geospatial inputs to a custom script that performs a task outside of the
functionality provided by standard ArcGIS tools. The scripts may be written in a variety
of scripting languages (e.g. Python, VBScript) and are stored on disk. The ArcToolbox
script tool contains a link to the script, as well as input/output parameter definition for the
script (i.e., what goes into the script, and what comes out of the script). The script tool
retrieves geospatial inputs and then sends those inputs to the script where processing
takes place. When the script is finished, it sends an output back to the script tool.

Scripts give the user the flexibility to create as simple or complex of a geoprocessing task
as desired. Other DLLs and applications can be called from a script, before finally
returning control back to the script tool and ArcToolbox.

Model Builder
Model Builder is a system in ArcToolbox that allows geoprocessing tasks to be chained
together in a single model. An ArcToolbox model consists of a set of processes. Each
process contains a tool, input data, and output from the tool. The output from one tool
becomes the input the next tool in the chain.

Any standard ArcGIS tool may be placed into a model. In addition, script tools may also
be placed into a model. This research uses Model Builder to chain together two
hydrologic processes from libHydro: the calculation of precipitation excess and the
production of a runoff hydrograph. Each process is accessed through a script tool.


2.4 Study Area
The Llano River basin is located in central Texas, approximately 100 miles northwest of
the capital city of Austin. The basin encompasses roughly 4465 square miles, and is
divided into 74 Watersheds for this study.
Figure 2.1 Llano Rive r Basin Waters heds and Streams

2.5 Scope of Work
The purpose of this research was to prove the concept that Arc Hydro data could be
linked with hydrologic simulation processes through Model Builder. In particular, this
research addresses the following objectives:

      Develop a script tool to call the Loss Initial Constant method in libHydro for
       calculating precipitation excess.
      Develop a script tool to call the Snyder Unit Hydrograph method in libHydro for
       calculating a runoff hydrograph.
      Develop a model that chains the previous two script tools together to calculate
       runoff for a set of watersheds, given a set of precipitation data and hydrologic
       properties about those watersheds.
3 Methodology
3.1 Script Tools
Script tools were used to bridge the gap between GIS data and libHydro functions. A
script tool was created for each libHydro function to be called. The script tool sends
geospatial inputs to a script, which then calls a DLL called MBLibHydro. This DLL
manages the querying of time series data for each feature and the calling of libHydro
functions from the libHydro DLL.




Figure 3.1 Connecting Geospatial Data with libHydro through a Script Tool

The implementation of this procedure in ArcToolbox thus requires the following
components:

      A script tool to accept geospatial inputs and send them to a script
      A script on disk to receive inputs and call a DLL to manage process execution
      A DLL to control process execution and call the appropriate functions from
       libHydro.dll
      libHydro.dll, which contains the HEC hydrologic simulation functions

The design for script tools in this research follows the same general structure. Each tool
requires a feature class as input. The feature class must contain fields providing certain
parameters for the tools. For instance, the calculation of precipitation excess using the
initial and constant loss method requires an initial loss value for each feature. The
TSTypeIDs associated with certain time series must also be provided. In the case of
precipitation excess, a TSTypeID must be provided for both the precipitation time series
and the precipitation excess time series (which will be created by the tool).
3.2 Model Tool
Script tools may be chained together in an ArcToolbox model, provided that the tools
produce an output. The script tools in this research produce two Boolean outputs:
Success and Abort. These variables are used to determine if execution should continue,
in the case that the tools are participating with other tools in Model Builder. If Success =
True, then execution continues. If Abort = True, then execution may halt, or some other
action may be taken.

To set up two script tools in a chain, both tools are placed in a model. Then a
precondition property is set on the second tool, with the property being the state of the
Success output from the first tool. Thus, if the first tool's operation was successful, the
workflow in the model will continue to the second tool.
4 Results
A toolbox called libHydro was created for this research. This toolbox includes three
toolsets: Lossrates, Models, and Unitgraph. The toolbox may be expanded to include the
other functions in libHydro, as well as models based on those functions.

4.1 Script Tools
The Lossrates toolset contains a tool called Loss Initial Constant. This tool calculates
precipitation excess using the loss initial constant method provided in the libHydro DLL.




Figure 4.1 Loss Initial Constant Tool

The tool receives a feature class and field names for parameters as input, as well as a time
interval and TSTypeIDs for the precipitation and precipitation excess time series.

The tool was run for the Watersheds in the Llano basin. Results for one of those
Watersheds are shown below.
                         Excess with Loss Initial Constant Method

                0.16
                0.14
                0.12
   Height(mm)




                 0.1
                                                                                                                                                  Precipitation
                0.08
                                                                                                                                                  Excess
                0.06
                0.04
                0.02
                  0
                                             1:00 AM
                                                       2:00 AM
                                                                 3:00 AM
                                                                           4:00 AM
                                                                                     5:00 AM
                                                                                               6:00 AM
                                                                                                         7:00 AM
                                                                                                                   8:00 AM
                                                                                                                             9:00 AM
                       11:00 PM
                                  12:00 AM




                                                                                                                                       10:00 AM
                                                                               time


Figure 4.2 Precipitation Excess Calculated with Loss Initial Constant Method

The Unitgraph toolset contains a tool called UnitgraphSnyder. This tool calculates a
runoff hydrograph using a Snyder unit hydrograph and a time series precipitation excess.
Figure 4.3 UnitgraphSnyder Tool

The tool receives a feature class and field names for parameters as input, as well as a time
interval and TSTypeIDs for the precipitation excess and runoff time series.

The tool was run for the Watersheds in the Llano basin. Results for one of those
Watersheds are shown below.

                                        Rainfall and Runoff Time Series
                        0.16                                                                1.6
                        0.14                                                                1.4
                                                                       Precipitation
   Precipitation (mm)




                        0.12                                                                1.2
                                                                                                  Runoff(cms)




                                                                       Runoff
                         0.1                                                                1
                        0.08                                                                0.8
                        0.06                                                                0.6
                        0.04                                                                0.4
                        0.02                                                                0.2
                          0                                                                  0
                         9:36 PM   12:00 AM   2:24 AM   4:48 AM   7:12 AM   9:36 AM    12:00 PM
                                                         Time


Figure 4.4 Runoff Time Series Calculated from Snyder Unit Hydrograph and
Precipitation Excess
4.2 Model
In the Models toolset, a model called Precip to Runoff Snyder was created. This model
chains together the Loss Initial Constant and UnitgraphSnyder tools in sequence to
calculate runoff hydrographs for a set of Watershed features. The model uses the
precondition property of Success from the Loss Initial Constant tool to determine if the
UnitgraphSnyder tool should be executed. When run, this model produced the same
results as when running the script tools individually.




Figure 4.5 Model Builde r Diagram of Precip to Runoff Snyder Model

Figure 4.5 shows the model builder diagram of this model. Note that the Watershed
feature classes and Excess TypeID serve as inputs to both script tools. Also note that the
UnitgraphSnyder tool only executes if the Success precondition property is set to True
after execution of the Loss Initial Constant tool.
5 Conclusions
With Model Builder and Arc Hydro, complete hydrologic simulations can be created and
executed from with the ArcGIS environment. By chaining together more processes from
libHydro, much (if not all) of the simulation capabilities provided by HEC software can
be captured within the Model Builder framework. Scripts and script tools can be used as
bridges between the GIS and other simulation models as well. Thus a fully integrated
hydrologic information system can be created that incorporates a GIS, Arc Hydro, and a
variety of simulation models.
Appendix: Source Code
A1 Loss Initial Constant Script
'***********************************************************************
***
'Description: This vbs file calls libHydro LossInitialConstant function
'Created by: Tim Whiteaker
'Created: 3/30/03
'Inputs: Feature class name
'Output: Updates TimeSeries table with Excess values (in same database as
'     feature class)
'Notes: Requires MBlibHydro.dll to be registered on your computer
'    MBlibHydro.dll must be in same location as libHydro.dll
'Updated: 4/14/03
'***********************************************************************
***

'Create GeoProcessing object
Set gp = WScript.CreateObject("esriCore.GPDispatch.1")

'Retrieve the input parameters
FeatureClass = WScript.arguments.Item(0)
TimeInterval = WScript.arguments.Item(1)
InitLoss = WScript.arguments.Item(2)
ConstLossRate = WScript.arguments.Item(3)
ImpAreaRatio = WScript.arguments.Item(4)
RainfallTypeID = WScript.arguments.Item(5)
ExcessTypeID = WScript.arguments.Item(6)

'Check existence of input data
If FeatureClass <> "#" Then
 If Not gp.Exists(FeatureClass) Then
   Err.Raise 101, , FeatureClass & " not found"
 End If
End If

ErrMsg = ""

Set pLossRates = WScript.CreateObject("MBlibHydro.clsLossRates")
bSuccess = False
on error resume next

bSuccess = pLossRates.GeoLossInitialConstant(CStr(FeatureClass),
CLng(TimeInterval), CStr(InitLoss), CStr(ConstLossRate), CStr(ImpAreaRatio),
CLng(RainfallTypeID), CLng(ExcessTypeID), ErrMsg)
if err.number <> 0 then
  ErrMsg = err.description
end if

If bSuccess Then
' MsgBox "Finished with LossInitialConstant Operation"
  gp.SetParameterAsText 7, "true"
  gp.SetParameterAsText 8, "false"
Else
  If CStr(ErrMsg) <> "" Then
   Err.Raise 42, , CStr(ErrMsg)
  End If
  gp.SetParameterAsText 7, "false"
  gp.SetParameterAsText 8, "true"
End If


A2 Snyder Hydrograph Script
'***********************************************************************
***
'Description: This vbs file calls libHydro Unithydrograph Snyder function
'Created by: Takkan
'Created: 4/11/03
'Inputs: Feature class name
'Output: Updates TimeSeries table with Excess values (in same database as
'     feature class)
'Notes: Requires MBlibHydro.dll to be registered on your computer
'    MBlibHydro.dll must be in same location as libHydro.dll
'Updated: 4/11/03
'***********************************************************************
***

'Create GeoProcessing object
Set gp = WScript.CreateObject("esriCore.GPDispatch.1")

'Retrieve the input parameters
FeatureClass = WScript.arguments.Item(0)
TimeInterval = WScript.arguments.Item(1)
SnyderCp = WScript.arguments.Item(2)
SnyderTp = WScript.arguments.Item(3)
AreaSqKm = WScript.arguments.Item(4)
ExcessTypeID = WScript.arguments.Item(5)
RunoffTypeID = WScript.arguments.Item(6)

'Check existence of input data
If FeatureClass <> "#" Then
 If Not gp.Exists(FeatureClass) Then
   Err.Raise 101, , FeatureClass & " not found"
 End If
End If

ErrMsg = ""

'Set pLossRates = WScript.CreateObject("MBlibHydro.clsLossRate")
'bSuccess = pLossRates.GeoLossInitialConstant(CStr(FeatureC lass),
CLng(TimeInterval), CStr(InitLoss), CStr(ConstLossRate), CStr(ImpAreaRatio),
CLng(RainfallTypeID), CLng(ExcessTypeID), ErrMsg)

set pSnyder = WScript.CreateObject("MBlibhydro.clsHydrographs")
bSuccess = False
on error resume next

bSuccess = pSnyder.GeoConvoluteunitgraph(CStr(FeatureClass), CLng(TimeInterval),
CStr(SnyderCp), _
 CStr(SnyderTp), CStr(AreaSqKm), CLng(ExcessTypeID), CLng(RunoffTypeID),
ErrMsg)

if err.number <> 0 then
  ErrMsg = err.description
end if

If bSuccess Then
' MsgBox "Finished with Convolute Snyder Unit hydrograph Operation"
  gp.SetParameterAsText 7, "true"
  gp.SetParameterAsText 8, "false"
ElseIf CStr(ErrMsg) <> "" Then
  Err.Raise 42, , CStr(ErrMsg)
  gp.SetParameterAsText 7, "false"
  gp.SetParameterAsText 8, "true"
End If

								
To top