Introduction to WRAP

CE 394K.2 Surface Water Hydrology
University of Texas at Austin - Spring, 1999

Prepared by
Brad Hudgens and David Maidment

Table of Contents

Why WRAP? -- Goals of the Exercise

The intent of this exercise is to familiarize you with water availability modeling using the Water Rights Analysis Package (WRAP).  By the end of the exercise, you will be able to :

Where is WRAP? -- Obtaining the Program and the Data

WRAP and the files needed for this exercise are available on the LRC server.  In windows explorer, go to network neighborhood\civil3\LRC\Class\Maidment\gishydro99\wrapintro.  Copy all of the files to your working directory.  You'll need a few Mb of space (5-10 should be fine).  You should have the following files : These files can be downloaded in a single zip file:

What is WRAP?

The Water Rights Analysis Package (WRAP) was developed at Texas A&M by Dr. Ralph Wurbs and David Dunn.  It is currently being used to make water rights reliability assessments in all Texas river basins with the exception of the Rio Grande.  Several versions of WRAP have been produced and it continues to evolve to meet the requirements of the Senate Bill 1 modeling project.  For this exercise we'll use the November 1998 version.

The WRAP modeling package is a set of Fortran programs :  RECORDS, WRAP-SIM, and TABLES.  RECORDS is a preprocessor that can be used to develop naturalized streamflows at control points with unknown flow records, given the naturalized streamflows at known points, such as gages.  WRAP-SIM is the actual simulation model.  TABLES is a postprocessor used to organize the voluminous model output into user-specified formats.

* = optional file

Dr. Wurbs built the model, so let's let him describe it :

"WRAP is a tool for assessing water availability for a river basin, or multiple-basin region, under a priority-based allocation system, such as the Texas water rights system.  The simulation model is designed for evaluating capabilities for meeting existing and proposed water rights requirements and determining the unappropriated streamflows available for additional new permit applicants.  WRAP-SIM performs sequential monthly water volume accounting computations associated with meeting water management /use requirements during a specified hydrologic period-of-analysis.  Constant annual water use targets, which vary seasonally over the 12 months of the year, are combined with sequences of naturalized streamflows and reservoir evaporation rates representing basin hydrology.  Water rights requirements include diversions, reservoir storage, instream flow needs, return flows, and hydroelectric power generation.  The postprocessor program TABLES provides capabilities for organizing and summarizing WRAP-SIM simulation results by a variety of user-specified tables and reliability indices.  The public-domain software package is generalized for application to any river basin, with input files being developed for the particular river/reservoir/use system of concern".  (Wurbs, 1998)
A river basin system is represented in WRAP by the following components : The type of use (e.g. municipal, industrial, agricultural) is used to break down the annual diversion amount into monthly targets.  To do this, the user defines monthly distribution factors for each type of water right.  These water rights apply only to diversion of surface waters.  Texas has no water rights system for pumping of groundwater.  The priority date is the date the water right was first obtained.  The appropriations doctrine upon which Texas water law is based says, "first in time is first in right," which means that the water right with the earliest priority date has the highest ranking among all water rights if a water shortage means that not all the rights can be satisfied from existing water supplies.  Conversely, the water right with the most recent priority date has the lowest ranking and will be the first water right to be cut off if supply is limiting.
Important!  RECORDS, WRAP-SIM, and TABLES all use text input files.  These files must be formatted correctly or they'll cause incorrect output or hang up the programs.  When you need to make changes to the input files in the exercises below, be sure to follow the field formatting.  Within the fields, entries are right-justified, except for titles and comments.  If one of the programs does hang up, remember that you can use Ctrl-C to interrupt execution in DOS.

How to WRAP.

In this exercise, we'll apply WRAP to a basin model.  The Sulphur river basin is located in northeast Texas.

Here are the Middle and South Sulphur Rivers above USGS gage 7342500 near Cooper, Texas :

The red points are the control points (8 of them) that we'll use to model this basin.  The most downstream control point, A10, is the USGS gage.  The model includes 13 water rights (that is, thirteen separate diversions, some of which belong to the same water right number) and 5 reservoirs in this watershed.   The large reservoir, modeled as control point A40, is Lake Chapman, which began impounding water in 1991.  Water from this basin and from Lake Chapman is currently permitted primarily for water supply to cities in the area, and as far away as Irving, TX.  Here's a breakdown of the water rights in this watershed:
Water Right Control Point Permittee
4800 A20 City of Cooper
4395 A30 City of Cooper
4799 A40 City of Irving
4798 A40 North Texas MWD
4797 A40 Sulphur River MWD
4797 A40 City of Commerce
4795 A70 City of Wolfe City
4796 A80 Webb Hill Country Club
Notice that not all control points are water rights.  A10 is the USGS gage, and control points A50 and A60 are points where return flows from several nearby towns are put into the system.  Return flows may represent outflows from water treatment and industrial processes or they may also be used to input increased flows in areas that use groundwater as water supply, then return it to the surface.

1. Using RECORDS to distribute naturalized streamflows

Naturalized streamflows are flows computed from historical data with the influences of human activity removed.  Speaking mathematically :
Naturalized streamflow    =    Historical streamflow
                                        +    Diversions
                                        -    Return flows
                                        +    Reservoir depletions
                                        +/- Changes in runoff due to changes in land use
Note that while other models may be helpful in preparing naturalized streamflows (e.g. reservoir simulation models), these calculations require a lot of old-fashioned research and work before even beginning to use a water availability model such as WRAP.  In our basin, the naturalized flows for the years 1940-1996 have been determined by the contractors on the TNRCC Water Availability Modeling Program, R.J. Brandes and Associates, in the case of the Sulphur basin.

RECORDS develops WRAP hydrology records (streamflows and evaporation rates) at specified control points based on given records at other control points.  Several options are available for methods of distributing naturalized streamflows from known to unknown points :

At CRWR, we use GIS to determine the drainage area, mean precipitation, and curve number for each control point in a basin model.  This data becomes one of the input files for RECORDS so that the modified NRCS method can be used to distribute flows.  So, let's run RECORDS to prepare the hydrology input for our basin.  First, let's get familiar with the input files.  Four files are needed, they are :
1.  Counter (CT) Records and Control Point (CP) Records, "CTCP.txt"
Our file looks like this :

CT 8 7 8 1 57 0


CP A70 A60 0 0 5

CP A10 OUT 0 0 0 A70

CP A20 A10 0 0 5 A70

CP A30 A10 0 0 5 A70

CP A40 A10 0 0 5 A70

CP A50 A40 0 0 5 A70

CP A60 A40 0 0 5 A70

CP A80 A60 0 0 5 A70

The CT record identifies how many records are present in each input file.  Here it says, in order, 8 control points, 7 flow diversion records, 8 watershed parameter records, 1 control point with evaporation records, 57 years of hydrologic data, and the last "0" is a switch controlling the use of the multiplication factors in the CP records.

The CP records define the connectivity and flow distribution methods among the control points.  These records show: the control point, the next downstream control point (or OUT if it's an outlet), a multiplication factor for the inflow values (a "0" means to default to a value of 1), a multiplication factor for evaporation rates (a "0" means to default to a value of 1), a switch indicating the use of either total or incremental watershed areas (here the field is left blank meaning total watersheds are used), the "5" indicates that the NRCS flow distribution method is used ("0" means the values are input for the known point), and finally the location of the evaporation records ("A70" means they are copied from the known values given for CP A70).

Go here for a more specific format of this input file.

    1. Flow Distribution Specifications, "FD.txt"
Our version of this file is short and to the point.  We are using the total upstream drainage areas and the modified NRCS method to distribute flows, so there's not much required here.  For each record above we've simply input the unknown point, and the known point (A10) from which we'll be distributing flows. FD   A70     A10                                       0
FD   A20     A10                                       0
FD   A30     A10                                       0
FD   A40     A10                                       0
FD   A50     A10                                       0
FD   A60     A10                                       0
FD   A80     A10                                       0
Go here for a more specific format of this input file.

3.  Watershed Parameters, "WP.txt"
The watershed parameters are provided here:

**   CP    AREA     CN  PRECIP
WP   A70    1.03    72.8    42.0
WP   A10  541.01    69.6    42.8
WP   A20    1.66    71.5    44.0
WP   A30   12.44    69.9    43.0
WP   A40  504.58    69.4    42.7
WP   A50  106.34    69.9    42.4
WP   A60  223.33    69.7    42.2
WP   A80    0.29    70.0    42.0
The area is given in square miles, and the mean annual precipitation is in inches.  The CN value ranges from 0 to 100. The precipitation and CN values are averages over the upstream drainage area from the given control point. David Mason and Brad Hudgens calculate these parameters at CRWR.

Go here for a more specific format of this input file.

4.  Inflow and Evaporation Records, "INEV.txt"
Here you have the naturalized streamflows (IN) and net evaporation rates (EV) for each known point, listed by month for each year of record.  Streamflows are given in acre-ft./month.  Net evaporation rates are defined here as the difference in gross reservoir evaporation minus precipitation, so a positive value indicates a positive net evaporation.  These values are given in ft./month. This is an excerpt from our file :



IN A10 1940 170 2809 2376 44621 26170 22500

IN 0 0 14608 276 586 47 31054 57673

EV A70 1940 0.03 -0.11 0.21 -0.27 -0.11 0.16

EV 0 0 0.23 0.55 0.52 0.28 -0.32 -0.31

IN A10 1941 16241 23605 63490 57131 83575 30013

IN 0 0 9076 2378 809 562 4512 10955

EV A70 1941 0.11 -0.10 0.01 -0.32 0.03 -0.35

EV 0 0 0.18 0.36 0.44 -0.21 0.14 -0.06

What this says is that the naturalized flow at gage A10 in year 1940 is 170 acre-ft/mo in January, 2809 acre-ft/mo in February, , 57673 acre-ft/mo in December. The net evaporation at control point A70 is 0.03 ft/mo in January, -0.11 ft/mo in February, etc. The values for 1941 follow those for 1940, and so on until all data for naturalized flow at point A10 and net evaporation at point A70 have been specified.

Go here for a more specific format of this input file.

Let's run RECORDS on this data.  What you are doing now is determining the evaporation and the estimated naturalized flow at each control point in the basin. Double-click on the Records.exe file (or run it from an MS-DOS window) and answer the prompts.

Important!  Be sure to call your output file, "Chapman1.hyd", this is necessary for the next step.

Your run should look like this :


RECORDS should run very quickly and output the file you specified.  Your output file should look like this :

IN   A70    1940      1.      8.      7.     94.     57.     50.
IN                   33.      1.      2.      1.     67.    120.
IN   A10    1940    170.   2809.   2376.  44621.  26170.  22500.
IN                14608.    276.    586.     47.  31054.  57673.
IN   A20    1940      2.     12.     11.    157.     95.     82.
IN                   55.      2.      4.      1.    111.     200.
IN   A30    1940      5.     69.     58.   1049.    618.    533.
IN                  347.      8.     15.      2.    733.   1353.
IN   A40    1940    138.   2517.  2123.  41056.  24004.  20617.
IN                13343.    230.    505.     33.  28515.  53135.
IN   A50    1940     35.    555.    470.   8728.   5126.   4409.
IN                 2866.     56.    118.     10.   6080.  11275.
IN   A60    1940     62.   1109.    936.  18000.  10531.   9047.
IN                 5859.    103.    224.     15.  12507.  23289.
IN   A80    1940      0.      1.      1.     23.     14.     12.
IN                    8.      0.      0.      0.     16.     30.
EV   A70    1940   0.030  -0.110   0.210  -0.270  -0.110   0.160
EV                 0.230   0.550   0.520   0.280  -0.320  -0.310
EV   A10   -1940     A70
EV   A20   -1940     A70
EV   A30   -1940     A70
EV   A40   -1940     A70
EV   A50   -1940     A70
EV   A60   -1940     A70
EV   A80   -1940     A70
This is the hydrology input file for WRAP-SIM.  Now, all control points have streamflow and evaporation records for each hydrological year.  Notice, that for evaporation rates, we have just copied values from the nearest known point.  The evaporation rates are taken from values computed by the Texas Water Development Board (TWDB) that represent the average value over a 1o X 1o quadrangle.

You can import the text output of the hydrology file (Chapman1.hyd) into Excel by doing the following.  Select the records you want to export in the hydrology file and copy them into a new text file.  Be sure you save this new file as a .txt text file (not a Word document).  Then, in Excel, go to File/Open, and set the "files of type:" window to Text Files.  When you open the file, Excel will start its Text Import Wizard.  In Step 1, choose "Fixed Width."    In Step 2, you can modify the field widths if you like.  Finally, choose the "General" column data format in Step 3, and you're done!

To be turned in. Choose one year from the hydrology file you have created.  Make a chart showing the distribution of streamflows for control points A10 and A40 over the year.  Do the results appear as you would expect?

In 1940, the flow in January at point A10 is 170 acre-ft/mo. Using the NRCS flow redistribution method, show that the corresponding flow in January at point A40 is 138 acre-ft/mo. Compare the flow so determined with the flow which would have been found at point A40 if a simple drainage area ratio had been used to do the flow redistribution from A10 to A40. What % difference is there between the flows at A40 determined by the two methods?

2. Using WRAP-SIM

The WRAP model is built around a monthly water availability balancing routine.  The whole program is structured as follows: In the water right loop, each water right is given its diversion amount as long as streamflow or reservoir storage, not yet appropriated by senior rights, is available.  Reservoir storage is calculated for each month as S2 = S1 + D - R - E.  That is, the end-of-month storage equals the beginning-of-month storage + (D) the net streamflow depletion (inflows minus spills and releases to meet senior downstream water rights) - (R) releases or withdrawals to meet requirements of rights associated with this reservoir - (E) evaporation.  Evaporation is computed as the evaporation rate times the average water surface area over the month.  Since this depends on the storage values at the beginning and end of the month, an iterative solution is required.

Water right seniority is fundamental to the simulation.  The most senior right in the basin meets its diversion target and refills its reservoir storage capacity as if no other water rights existed.

To run the WRAP-SIM program, you need an input file and the basin hydrology records.  We just created the hydrology file for this basin, and luckily for us, an input file has already been prepared for this model.  The input file describes all of the model components and sets the simulation specifications. Take a look at the file "Chapman1.dat"   As with RECORDS, a two-character identifier is used for each type of record.  Types of records in this input file include :
T1, T2, T3 titles or headings
** comments
JG water rights groups for output
JD job control
UC monthly use factors
CP control point information
CI constant monthly inflow or outflow
WR water right
WS  water right reservoir storage
IF instream flow requirement
SV storage/area table volumes
SA storage/area table areas
ED end of data for the basin description
Since we're concerned with water rights analysis, let's focus on the water rights records.  We have thirteen water rights in this model, and the records look like this :

WR  4800     A20     273    480019770103
WR  4395     A30    1518    480019830906
WR 4799M     A40   44820   4799M19651119                         WRCHAP
WR 4799I     A40    9180   CONST19651119                        WRCHAP
WR  4798     A40   54000    479819651119                        WRCHAP
WR 4797AM     A40   26960   4797M19651119                         WRCHAP
WR 4797AI     A40   11560   CONST19651119       2   0.425    WRCHAP
WR 4797BM     A40       0   4797M19651119                         WRCHAP
WR 4797BI     A40       0   CONST19651119                         WRCHAP
WR 4795_1     A70      69    479519251231
WR 4795_2     A70     232    479519570812
WR 4796_1     A80      80    479619680311
WR 4796_2     A80       0    479619830418
Each record tells you, in order, the water right number, the control point, the annual permitted diversion (acre-ft/year), the use type (each use has associated monthly distribution factors for the annual diversion), the priority date (given as YYYYMMDD),  the type of water right (a WRAP definition for how the water right is treated in the model, where a blank indicates type 1), and there may be a return flow factor and a group identifier.

Go here for a more specific record format.

Now lets run the model.  WRAP-SIM works with a common filename, and identifies the different input and output files by their extension.  In this case, we've called the hydrology and data input files "Chapman1.hyd" and "Chapman1.dat", so the output files will all be named "Chapman1"  as well.  Double-click on the Sim.exe file, or run the file from a DOS prompt.  Be sure and specify the full path and filename for the root file "Chapman1", for example "Y:/hudgens/wrap/exercise/chapman1".  The scratch files are used internally by WRAP and I suggest you just send them to your local temp directory.  Your run should look like this:

etc... etc...

WRAP writes a lot of text output, and it's not particularly interesting by itself.  Here's what the raw output for water rights looks like in the first few results from our simulation :

Program SIM    (November 1998 Version)  Output File
     WRAP - SIM  -- RUN 1
     MARCH 1999
  1940    57    12     8    14     5
4795_1      0.0      6.8      2.1    417.0      1.0       1.0      0.0  1940   1
4795_2      0.0     22.9      3.2    823.0      0.0       0.0      0.0  1940   1
4799M      0.0   2917.8    585.6 306943.3    446.6     446.6      0.0  1940   1
4799I      0.0    779.5    585.1 306164.2      0.0       0.0      0.0  1940   1
4798      0.0   3930.8    582.8 302235.7       0.0       0.0      0.0  1940   1
4797AM    0.0  2286.2    581.5 299950.8       0.0       0.0      0.0  1940   1
4797AI      0.0    981.6    580.9 298969.7       0.0       0.0      0.0  1940   1
4797BM    0.0      0.0    580.9 298969.7       0.0       0.0      0.0  1940   1
4797BI      0.0      0.0    580.9 298969.7       0.0       0.0      0.0  1940   1
4796_1      0.0      3.5      0.4     35.2       0.0       0.0      0.0  1940   1
IF4799      0.0    307.6      0.0      0.0       0.0       0.0    307.6  1940   1    307.6      0.0  IF
4800      0.0     21.4      2.0    142.6      2.0       2.0      0.0  1940   1
4796_2      0.0      0.0      0.5     56.0      0.0       0.0      0.0  1940   1
4395      0.0    119.2     19.3   4756.6      5.0       5.0      0.0  1940   1
These records are output for each water right and control point by month.  These water right output records show you : To be turned in.  Who owns the senior water right in this basin?  How does the seniority of this water right affect other users in the basin?


3. Formating Output in TABLES

TABLES is a postprocessor for organizing the WRAP output file into more user-friendly summaries.  It requires a WRAP output file, in some cases the WRAP input file, and a TABLES input file specifying the summaries to be output.  There are four job types executed by TABLES.  Within each job type, there are several records.  Each record specifies a different type of summary or output to be made.

Our interest is mainly in the job type 2 records.  Here are the records of interest to us : The "example.ext" file is an example TABLES input file that includes all of these records.  It looks like this:
2SCP   1   0
2SCP   1   1     A40
2SWR   1   0
2SRE   1   0
2SRE   1   1  CHAPMN
2REL   1   0
2NAT   0   0
2UNA   0   0
2DEP   0   0
2SHT   0   0
2STO   0   0
There are some additional records that add titles and comments, and mark the end-of-file:
TITL titles or headings
COMM add comments
PAGE add header page to the output file
ENDF end of input data file
Note that you must have the ENDF record at the end of the file.

These records are formatted in two ways.

Go here for more specific record formats.

A TABLES input file must have a ".ext" extension on the filename, but it does not have to have the same filename as the WRAP-SIM file you used.  The example tables input file for this exercise, "Example.ext",  includes all of the type two jobs listed above.  To minimize the output, only run one or two jobs at a time, instead of putting all of them in one file as in the example.  By now, you can probably guess how to run TABLES.  Just double-click on the Tab.exe file or run it from a DOS prompt. The Tables input file that presents just the output at point A10 is called example1.txt. The Tables output file is called output1 (this could have been any name). The Wrap output file name is chapman1.out, which you computed in the previous step. The DOS dialog is as follows:


To be turned in.  Run TABLES to determine the naturalized and unappropriated streamflows out of this basin.  To do this, you'll only need the 2NAT and 2UNA records in the tables input file, applied to control point A10, the basin outlet.  What are the average (mean) annual naturalized and unappropriated flows out of the basin? What % of the water is diverted on average? Draw a graph showing the annual volume of water that is appropriated as a function of the annual volume of naturalized flow. Briefly discuss these results. Is the amount of water appropriated in the basin constant from year to year?

Water Availability Planning

The water availability models being constructed under Senate Bill 1 will be used by TNRCC to approve new applications for surface water rights.  In this section you'll look at the effects of increased demand on Chapman reservoir.

Irving, Texas is located between Dallas and Fort Worth.  It presently has a population of about 160,000 but there are 3.2 million people in the Dallas/Ft. Worth metropolitan area and the population is expected to grow rapidly.  Here's a nice photo of Irving, courtesy of the chamber of commerce.  If you look closely I think you can see the gridlocked rush-hour traffic jam just beyond the tree line...

As we've seen above, Irving currently holds rights to 54,000 acre-ft/year of water out of Chapman reservoir.  If the population doubles, an increase of 160,000 persons, could their water demand be met from Chapman reservoir?  Assuming a use rate of 200 gallons per capita per day, that is equivalent to an increased demand of 32MGD or about 36,000 acre-ft/yr.  The file "Chapman2.dat" has this diversion amount entered as a new water right, water right #5000.  The new water right will be the most junior in the basin, with a priority date of March, 1999.  Make a copy of the "Chapman1.hyd" hydrology file and name it as "Chapman2.hyd" and run WRAP-SIM.  The DOS dialog looks like this:

First, lets take a look at the time series of storage levels in Chapman Reservoir. Another Tables input file has been prepared for this called example2.txt. The dialog to run this file is as follows:


Use Notepad to open this file. You'll see a monthly summary of end of period storage in column 3 (EOP Storage).

To be turned in: Make a plot of the End of Period Storage as a function of time. When does the storage go to 0? What does this imply about the supply of water to Irving during this period?

Now, lets examine the impact of adding the new water right to the performance of the other water rights dependant on Chapman Lake. Another Tables input file has been prepared called example3.txt which gives the reliability information for water right locations. Run this file to example the results from both chapman1.out and chapman2.out and compare the resulting reliabilities. The DOS dialog is the same as that shown above, except that you substitute example3.txt for example2.txt, and give new output file names to correspond to your new results, e.g. output3 and output3 corresponding to inputs from chapman1.out and chapman2.out respectively.

To be turned in: By what amount does the addition of the new water right for Irving affect the mean shortage (ac-ft/yr) available to the other users of Chapman Reservoir? Does the addition of this new water right affect the reliability of supply to the other water right holders in the basin apart from those drawing from Chapman Reservoir?

The End.

Sunset near Tucson, AZ

Every exercise must come to an end, and you've finally made it to this one.  Hopefully you've got that sense of completion and feel like you've met the goals we started out with.  If you're working in the LRC it would probably be nice to clean up the working directory.  Until later,


"Documentation of New Features in the November 1998 Version of the Water Rights Analysis Package (WRAP)."  Wurbs, R.A.,  November, 1998.
"Water Rights Analysis Package (WRAP) Model Description and Users Manual."  Dunn, D.D., Wurbs, R.A., October, 1996.


Go to Dr Maidment's Home Page