GIS in Water Resources, Fall 2002

 

Lib Hydro Modeling in Arc Hydro

 

by Masatsugu Takamatsu

Takamatsu@mail.utexas.edu

 

 

1.     Introduction

2.     Objectives

3.     Using Lib Hydro in Arc Map

4.     Lib Hydro Modeling in Arc Hydro

5.     Conclusions and Future works

6.     References

7.     Acknowledgements

Appendix A, B, C

 

1.    Introduction
In 2002, Center for Research in Water Resources in University of Texas at Austin (CRWR) completed to develop Arc GIS Hydro Data Model called “Arc Hydro” and published it. Arc Hydro model is a geospatial and temporal data model for water resources and consists of five hydrological concepts (Drainage, Hydrography, Network, Channel, and Time Series) and each of them is connected with each other systematically. Although Arc Hydro has a data structure that supports hydrological simulation models, it is not itself a simulation model.

On the other hand, the Hydrologic Engineering Center of the U.S. Army Corps of Engineering has developed several hydrological models called “HEC” series since 1960s and these models have widely used in the world. And in 1995 the Hydrological Engineering Center isolated several FORTRAN subroutines that perform particular hydrological subroutines, and collected together in Dynamic Link Library (DLL) files called “Lib Hydro” to make it possible to use these subroutines through other programs.

In brief, Arc Hydro is a hydrological data model and Lib Hydro is a collection of hydrological subroutines. So if these two models are combined, it becomes possible to do some basic hydrological analyses with Arc Hydro time series data. So in this project, I have tried to combine Arc Hydro and Lib Hydro for the hydrological analysis.

 

2.      Objectives
Based on these backgrounds written in Introductions, I set two objectives in this project.

l         　　 ●Understand and explain how to use the Lib Hydro subroutines in Arc GIS environment

l         　　 ●Develop a tool for combining of Arc Hydro data model and Lib Hydro subroutine

 

3.     Using Lib Hydro in Arc Map
Based on the project objectives, the process to use a Lib Hydro subroutine in Arc Map is explained in this chapter. I chose “EarthDistance” among several subroutines in Lib Hydro to test and explain how to use them in ArcMap. “EarthDistance” is one of the subroutines in Lib Hydro to estimate the distance between 2 points on the earth.

This chapter contains 1) What is Lib Hydro?, 2) Loading “EarthDistance” in Visual Basic, and 3) Using “EarthDsitance” in Arc Map.


What is Lib Hydro
As is written in the Introduction, Lib Hydro is a collection of hydrological subroutines and these subroutines are classified into eight categories shown in Table 3.1. These subroutines are written in FORTRAN and most of them conform to the FORTRAN 77 standard, with selected extensions that conform to the FORTRAN 90 standard.        

Table 3.1 Lib Hydro contains subroutines in the following categories

 

Category

Number of subroutines

 

Precipitation

3

 

Loss Rates

7

 

Unit Hydrographs

19

 

Base Flow

1

 

Routing Method

6

 

Utility Subroutines

25

 

Error Handling

7

 

SI / English Unit Conversions

7

Lib Hydro is available in its DLL format (Lib Hydro.dll) and can be called by any program languages that you are familiar with. In this project, Visual Basic is used to call Lib Hydro functions, because also ArcGIS can be customized by Visual Basic.


Loading a Lib Hydro function in Visual Basic
In this section, the process to load a Lib Hydro subroutine is explained. As an example, “EarthDistance”, one of the Lib Hydro utility subroutines, is chosen for explaining the process. The fprocess to call “EarthDistance” in Visual Basic is following.

1)     Make a form for the input values

2)     Code the form and the module

3)     Place the Lib Hydro.dll in proper folder

4)     Run the project

“EarthDistance” has 5 variables including four input variables and one output variable. Table 3.2 shows the definition and the declaration types of these variables. Any other details about “EarthDistance” in Lib Hydro User Manual are shown in Appendix A.

Table 3.2 the definition of the variables in “EarthDistance”

Name of the

 variables

Input

/ output

Definition

Declaration type in Fortran

Declaration type in VB

Lat1

Input

Latitude for first points, radians

Double Precision

Double

Long1

Input

Longitude for first point, radians

Double Precision

Double

Lat2

Input

Latitude for second point, radians

Double Precision

Double

Long2

Input

Longitude for second point, radians

Double Precision

Double

Distance

Output

Distance along the surface of the earth between the two points, km

Double Precision

Double

 

3.2.1 Making a form for the input
As shown in Table 3.2, four values of input variables are needed to run the “EarthDistance”. So a form for inputting these variables is created in Visual Basic (Figure 3.1). Although the units of all four input variables are radians, decimal degrees are more general unit for specifying the point location on the earth. So I chose decimal degree as the unit of the input form and made them to include the unit conversion process into the program to call “EarthDistance”.

 

3.2.2 Coding the form and the modules
After creating an input form, you need to code how it works. I attached a sample program to call “EarthDistance” in Appendix B. This program includes the following processes, form loading, variables declaration, unit conversion from decimal degree to radians, calling subroutines, and the coding for output message box.

Next, it is necessary to code module for calling “EarthDistance” in Lib Hydro.dll. In this process you need to declare the subroutine itself and all variables used in the subroutine. The sample program is also attached in the Appendix B. So the VISUAL BASIC project should have both forms and modules as shown in Figure 3.2. Figure 3.2 shows the project window of the VISUAL BASIC program to call “EarthDistance”.

 

 

3.2.3 Putting the Lib Hydro.dll in proper folder.
As I mentioned in Section 3.2.1, the program for input form includes the process to call a Lib Hydro subroutine. So you need to specify the place to put the Lib Hydro.dll in the program and put it in the place where you specify.

 

3.2.4 Running the project
After compiling and debugging the program, you may success to call Lib Hydro subroutine. Here I will show the result of “EarthDistance” program. For example, I calculated the distance of the half round of the earth on the equator (Fig 3.3). So I input the following values into the input form (Fig 3.4).

(LatA, LongA) = (0, 0)

(LatB, LongB) = (0, 180)

The calculation result is 20011km and it can be verified by the following equation.

L = 6370 * 2π / 2 = 20011 (km)

 

 

 

3.3 Using Lib Hydro subroutines in ArcMap
To use Lib Hydro subroutines in ArcMap, it is necessary to 1) create a new DLL file and 2) register and add the DLL file to the ArcMap. In this chapter, these processes are explained by using “EarthDistance”.

 

3.3.1 Creating a new DLLE
ESRI object library (Arc Objects) is the development platform for ArcGIS applications such as ArcMap, ArcCatalog etc. Using ESRI Object Library, it is possible to customize the ArcGIS applications and modify them to perform specific tasks for users. In this project, by using ESRI Object library, a new DLL file called “EarthDistance” was created in VISUAL BASIC and added to an ArcMap document as a tool button.

The processes to create a new DLL file are following.

1.       Open a new DLL Project in Visual Basic

2.       Add a reference to the ESRI and ArcMap Object Library

3.       Implement the ICommand Interface in the class file

4.       Add VISUAL BASIC code to perform the tool’s subroutine

5.        create the DLL

The details of these processes are written in Timothy Lee Whiticker’s master thesis Chapter 4 (August 2001). So if you need to know the details, please consult it. The sample program for creating EarthDistance.dll is attached in Appendix C. 


3.3.2 Adding the DLL to ArcMap

Once completing to make a new DLL file, the DLL file should be registered for ArcGIS. To register DLLs for ArcGIS, Register_in_menu.reg file is needed to be run. Normally, this Register_in_menu.reg file is located in C://arcgis/arcexe81/ArcObjectsDeveloperKit/Utilities and to be double clicked to be effective.

By doing this, your right click menu will allow you to automatically register and unregister dlls for ArcGIS (Fig 3.6). So EarthDistance.dll was registered for ArcGIS by right click and selecting “Register”. Then, EarthDistance.dll can be loaded to ArcGIS. Add the EarthDistance.dll to ArcMap by clicking on the Tools menu and then selecting Customize > Add from file. Browse to your data folder where the EarthDistance.dll is located and after it loads drag it on the ArcMap toolbar. You will see a command button (Fig 3.7) called EarthDistance as shown below.

 

 

 

 

 

 

 

 


3.3.3 “EarthDistance” in ArcMap
Clicking on the EarthDistance command button (Fin 3.7), a input form for the “EarthDistance” is coming up. Inputting the latitude and longitude of two points, and clicking OK, the program calculates the distance between two points and returns the answer in a message box.

Although “EarthDistance” is a very simple function, it becomes more useful when it is loaded to Arc Map. It is because in Arc Map you can easily get the coordinate of the point by putting cursor onto the point. The input form and the result of the “EarthDistance” calculation is shown in Fig 3.8. In Fig 3.8 the Diagonal length of Austin area is calculated.

 

 






















4. Lib Hydro Modeling in Arc Hydro
Although GIS data models don’t consider temporal information normally, Arc Hydro can handle time series data sets. As we did in the class exercise, hydrological time series data (e.g. precipitation, flow rate, etc.) can be obtained with Arc Hydro tools from data base table or some specific web site. And these time series data sets are very useful for the hydrological modeling because each times series data sets are related or can be related with spatial features in GIS environment. So in this project, I consider how to make use of these Arc Hydro time series datasets for hydrological analysis.

In the previous chapters, I discussed about what Lib Hydro is and How to use Lib Hydro. Based on these discussions and the basic knowledge of Arc Hydro, I will discuss about how Arc Hydro and Lib Hydro can be combined. In my class presentation, I proposed a flowchart to estimate the river runoff from precipitation data sets (Fig 4.1).

As the first step for the Lib Hydro modeling in Arc Hydro, I tried to use one Lib Hydro subroutine called “LossSCSCurveNumber”. “LossSCSCurveNumber” is a subroutine for estimating precipitation excess from precipitation time series data and the Curve Number of the watershed. This subroutine is chosen for the first step of “Lib Hydro Modeling in Arc Hydro” because it is a good example to combine Arc Hydro time series data sets and Lib Hydro hydrological functions.

So in this chapter, I will explain about 1)SCS Curve Number Loss Model, 2) how the Curve Number method works in Arc Hydro.

 






















4.1 SCS Curve Number Loss Model
Soil Conservation Service(SCS) Curve Number(CN) model estimates precipitation excess as a function of cumulative precipitation, soil cover, land use, and antecedent moisture, using the following equation:

 

                                     (1)

  Pe = Accumulated precipitation excess at time t (mm)

  P = Accumulated rainfall depth at time t (mm)

  Ia = the initial abstraction (initial loss) (mm)

  S = potential maximum retention (mm)

 

Ia = 0.2S                                                       (2)

  (Empirical relationship of Ia and S)

                       (3)

  (substitute (2) for (1))

                              (4)

  (for SI Unit)

  CN= Curve number (30 < CN < 100) (-)
Estimating the CN, you can refer to several CN tables proposed by SCS (HEC-HMS technical manual).

 

4.2 Curve Number method in Arc Hydro
Based on the basic knowledge of SCS Curve Number Loss Model (“LossSCSCurveNumber”), I developed a Visual Basic code to combine Arc Hydro time series precipitation data and “LossSCSCurveNumber”. More specifically, the tool can get precipitation data from an attribute table, and calculate the precipitation excess by using subroutine “LossSCSCurveNumber”. In this section I will explain about 1)How precipitation data and the subroutine are combined, and 2)How the  program works in ArcMap, and 3)the result

 

4.2.1 How Precipitation data and the subroutine are combined
In this section, I will explain how precipitation data and the subroutine are combined by using conceptual flowchart(Fig 4.2). At first a Geodatabase should be created for the target watershed. the Geodatabase contains several hydrological information including time series precipitation data, land use data, and Soil type data.

By using land use and soil type data, you may estimate Curve Number (CN). CN can be determined for each land use or soil type. So to estimate the CN value for the target watershed, averaging process is necessary. And this CN calculation process can be done by grid base using ArcGIS Spatial Analyst.

On the other hand, as we did in the “time series” exercise we can get precipitation time series data through data base tables or specific web cite. These raw precipitation time series data should be averaged over space and time because the subroutine “LossSCSCurveNumber” requires the precipitation time series data that represents for the whole watershed. And this process can be done by both Arc Hydro several tools and ArcGIS tools.

Once CN value and the precipitation time series data is estimated for the target waterhsed, it is time to run the “LossSCSCurveNumber”. Strictly speaking, this subroutine requires more variables such as Initial Cumulative Precipitation. And to estimate the values of these variables, the discussion about antecedent precipitation is necessary. But to simplify the Curve Number Method, these discussions are omitted here.












 

 

 

 

 


4.2.2 Programming
Actually, the programming for “LossSCSCurveNumber” was much harder than that of “EarthDistance” because “LossSCSCurveNumber” program contains the process to get values from not only the input box but also an attribute table. So the process of the calculation is more complicated than that of “EarthDistance”. In this section I will explain about how this program works.
As shown in Fig 4.3, the program get some values from ArcGIS attribute table and some values from the Input form. And it calculates the time series precipitation excess and draw a graph of both precipitation and precipitation excess.





And in Fig4.4 the contents of the attribute table are shown. From this table the program counts the number of time steps (16 time steps here), and get the date and precipitation data from the feature classes of “TSDataTime ” and “TSValue_mm” respectively.


4.2.3 Results
By using the program and the precipitation data from 10/12 11pm to 10/13 2PM at San Marcos Basin, the precipitation excess was calculated. Although I didn’t have time to examine CN values and Initial Abstraction, the program works and draw graph properly (Fig 4.5).

I think it is important to consider how the precipitation data should be averaged over time and space. But this time I picked up a point and used the point value of precipitation for the entire basin because of the shortage of time. And I want to take these hydrological considerations account into the developing Lib Hydro tools in the future.



5. Conclusions

n        The combination of Arc Hydro and Lib Hydro will give us more opportunity to do hydrological analysis in GIS environment.

n        Some Lib Hydro functions still have some bugs in its dll format files.

n        A tool to calculate the precipitation excess by Curve Number Method was developed for the project. But this tool should have more consideration of hydrological aspects to estimate the input variables

 


6. References

Chapter 1 Introduction

Arc Hydro GIS for Water Resources, David R. Maidment, June 2002

 

Chapter 3 Using Lib Hydro in ArcMap

Development of Linear Measure Tool using Application Framework, Venkatesh Merwade, GIS in Water Resources Fall 2001 term project

Hydrologic Modeling Using ArcHydro, Fall 2002 GIS in Water Resources (CE394K) class exercise handout, David Maidment, etc.

Chapter 4 Lib Hydro Modeling in Arc Hydro

Arc Hydro GIS for Water Resources, David R. Maidment, June 2002, Chp. 7: Time series

Hydrological Modeling System HEC-HMS Technical Reference Manual March 2000 pp40-42



Acknowledgements

Dr. David Maidment, Center for Research in Water Resources, UT Austin

Venkatesh Merwade, Tim Whiteaker, Sergio Martines , Dr. Jaeyoung Park, and CRWR members