WRDS Library [Home]
Digital Library Publications Videos Card Catalog

Chapter IV
Description of WIRSOS

This chapter contains a description of how the WIRSOS model operates and how the model functions were separated into individual subroutines. Each section of the program is discussed and the function each subroutine performs is described.

INTRODUCTION

SEPARATION INTO SUBROUTINES
When this project started, WIRSOS consisted of a single 3200 line program with two small subroutines and two functions. The 3200 line format, combined with the complex nature of the model, made the program difficult to understand. For example, if a section of the program was changed, great care had to be taken to ensure that the whole program was not affected; and foresight was necessary to confirm that the proper section was being changed. In short, the program was difficult to understand and even more difficult to modify.

The problem was reduced by dividing the program into separate, interactive subroutines that perform the functions of the original program. The purpose of each section of the program is easier to understand, and the effect of changing a section of the program (on the rest of the model) is easier to determine. The model is more efficient since it no longer has to search the entire program to find the section it needs. Instead it calls the proper subroutine for each function performed. Splitting the program into subroutines also allowed the programmer to become familiar with all aspects of the WIRSOS model before altering the program. The modular format created by the subroutines also facilitated the addition of new subroutines when enhancing the model.

The original program was separated into a main program and twenty-six subroutines. With the two subroutines and two functions defined by the original program, the model had thirty- one separate modules. Later, twenty additional subroutines were developed to enhance the program, so that the final model now consists of fifty-one separate modules. The function of each module will be discussed in this chapter, and the discussion of the modules will combine to describe how the WIRSOS model operates.

While separating the original program into subroutines and in all further development, attempts were made to reduce the number of GO TO statements by replacing them with IF-THEN-ELSE statements. Additional documentation (comment lines) were also placed in the Fortran code to make the program easier to understand. To make the program easier to modify, the lines of code between a DO statement and its CONTINUE statement were indented to make it easier to recognize a DO-loop. Lines of code between an IF statement and its ENDIF or ELSE statements were also indented to separate an IF block from the rest of the program. This should make the program easier to understand when making any modifications in the future.

PREVIOUS MODIFICATIONS
WIRSOS has been in use for over ten years, and during that time, the program has been modified to fit the different needs of the various modelers. It was necessary to study these modifications and attempt to incorporate some of the better changes into the current model. As discussed above, considerable work was done to separate WIRSOS into subroutines. Whenever possible, the modifications to WIRSOS were added as a separate subroutine. If the modification was not significant enough to form its own subroutine, existing subroutines that handle the same information were altered to include the modification. Every change made by previous model users was not incorporated into the current model. When two or more model users made similar changes, the changes were combined to form a single modification, or the modification that performed the function best was added.

CURRENT MODIFICATIONS
All modifications to WIRSOS were developed as separate subroutines whenever possible. A considerable effort was made to not change existing input data file formats, or alter them as little as possible.

WIRSOS5.FC

WIRSOS5.FC declares all the variables that are used by the model. Variables that are arrays, that are integers but do not begin with a proper integer character, that are real but do not begin with a proper real character, that represent character sequences, and that are transferred between the main program and the subroutines are declared in the WIRSOS5.FC. The variables that are transferred between the main program and the subroutines are declared in common statements. This allows the computer to assign a location in its memory to these variables, and to access that location from any subroutine that has the same common statement. The common statement saves computer memory and reduces the size of the call statements needed to access a subroutine. WIRSOS5.FC is then included in the main program and most of the subroutines. By including WIRSOS5.FC, the size of each subroutine is reduced.

WIRSOSS

INTRODUCTION
WIRSOS5 is the main program; it is the framework from which all functions are performed. It directs the flow of the program and keeps track of where the model is at any time.

All the variables that are passed between the subprograms are initialized in WIRSOS5.FC. The number of days in a month are assigned for each month and entered into an array. The names of the months are also entered into an array and the value used to convert cfs to acrefeet is set.

After the variables are initialized, the program enters an interactive user interface. The user interface allows the model user to declare the input file names, the output file names, and the run control information for the model. The main program then opens the output files used to store information produced during a model run. The information written to the output files is discussed later.

The program is written in FORTRAN 77 and has been compiled with Microsoft Fortran Version 5.0. All system calls are compatible with this compiler.

TIME AND DATE
The original WIRSOS program contained a function that read the time and date from the computer operating system. This function was system dependent and did not work after the program was written for use on personal computers (PC). When operating WIRSOS, some model users have modified the original PC version of the program to call the time and date from their computer operating system. once the time and date were read, they were written to the output files with the rest of the header information. The current model calls the time and date, and writes that information to the output files.

A header is written to the output files declaring the time, the date, and what information each file contains. The block of programming that writes the header, the time, and the date to the output files is located in HEAD. HEAD is called by the main program after the output files are opened.

INPUT DATA
The subroutines that read data from the data input files are called by the main program. The data in these files are used, but not changed by the model. The subroutines called include DELAY, STATION, RESDATA, and RESAREA, each of which will be defined later in this chapter. The subroutine that determines the percent of the permitted reservoir volume that each reservoir right controls (RRBALNC) is also called. The main program then opens the large data files associated with instream flow, diversion, and reservoir rights.

The default names for the WIRSOS input data files begin with the prefix 'Inp' followed by the file number. The file numbers are: `1' for the stations data; `2' for runoff data; `3' for instream flow rights data; `4' for diversion rights data; `7' for delay tables data; `14' for area versus capacity data; `15' for reservoir data; `16' for reservoir rights data; `17' for junior project rights data; `20' for efficiency table data; and `21' for run control information for the interactive user interface.

The principal operation of the model begins when the subroutine FLOW is called. FLOW reads the runoff data from the runoff data file (Inp 2). Runoff data must be entered for each year simulated by the model and two years of data are active in the model during a simulation year. The model needs two years of data to be able to add return flows to the system for up to twelve months after the time of diversion. FLOW reads the second year of data and allows the main program to transfer the second year data to the first year array. The subroutine FLOW can then be called again without erasing the first years data. After each year is simulated the model goes to the beginning of the next year and transfers the data in the second year array to the first year array before reading the next year of runoff data. Therefore, a year of flow data is not inadvertently erased before the it is used by the model. Before WIRSOS was rewritten, the program had separate sections to read in the first and second years of runoff data.

DATA CHECKING
After the input data has been entered and the rights data bases opened, the diversion rights, instream flow rights, junior project rights, reservoir rights, and station data files are checked to determine if the data was entered in the proper sequence. The station data file is checked to make sure upstream stations were entered before downstream stations. The others data files were checked to make sure senior rights were entered before junior rights and that upstream rights are entered before downstream rights for rights that have the same priority date. These files are checked by PRICHK, IFRCHK, RSVCHK, and STACHK. In addition, the junior project rights file is checked by JPRCHK to make sure all the JPR's are physically downstream from their associated reservoir.

MODEL PROGRESS REPORTING
The main program next enters the loop where the primary functions are performed. The program performs water accounting for a river system on a monthly basis, hence the main loop counts from one to twelve to correspond to the months of the year. At the start of each month of simulation (the beginning of the main loop), the program writes the month and year of model operation to the screen. In this manner the modeler knows how far the model has progressed during the current simulation. Figure 1 is a simplified flow chart of the WIRSOS model (See Appendix A for a list of where more complete information can be obtained).

MAIN LOOP
After the loop is initiated, the program writes a header to the main output file, sets water available for diversion equal to the flow in the river, sets the number of rights not met to zero, and calls RESRLSE. RESRLSE calculates the power and non- project releases from reservoirs. The main program then calls the subroutines ISFLWR, RESRITE, and DIVERS to read the rights from the instream flow, reservoir, and diversion files. After the rights are read, the main program compares their priority dates. Priority is established according to when a right was filed. The right with the earliest filing date has the highest priority. In the case of two rights with the same priority date, diversions have the highest priority, reservoirs have the second highest priority, and instream flows have the lowest priority. If two rights are the same type of right and have the same priority date, the upstream right will be processed first.

Depending on which right is in priority, the main program calls one of three subroutines to assess the availability of water to satisfy the right. These subroutines are ISFLWA, RESADJS, and DIVEVAL. In the case of project rights that call on a reservoir to satisfy all or part of their demand, the main program can call JPREVAL, JPRIVER, and PROJRITE depending on the status of the reservoir and the type of project right. Each program that makes a diversion through a canal calls RETFLW to calculate the flows returning to the river system from a diversion. The model continues processing water rights until all rights have been properly addressed. Figure 2 is a simplified flow chart for the main loop of the program.


Figure 1 Simplified flow chart for WIRSOS5.

Depending on the options the model user selects, the program can call RESMIN to determine the release required to meet the minimum release from a reservoir, MINRSRL to release water from a reservoir to meet the minimum release, and OVERSUP to store an extreme supply of water in the reservoirs. Before leaving the main loop, the main program calls EVAPR to calculate an average evaporation from the reservoirs for that month and EOM to write the end of the month reservoir data to temporary output files.


Figure 2 Flow chart of WIRSOS5 main loop.

MODEL REPORTING
After the main loop, the main program calls EOY to write the end of the year flow data to the output files. If the final year or data was processed, the program calls TWELVE to sort the rights called out files (Tape 12 and Tape 13) by permit number, month, and year, EOR to write the end of the model run reservoir status to an output file (Tape 18), and TOR to write end of model run reservoir rights status to an output file (Tape 19). (When a right is called out, it means that the demand for that right was not satisfied.) After TOR, the model run is over and the program stops.

OUTPUT FILES

Tape 5
Tape 5 is an "echo" of the information provided by the model user during the interactive user interface. This file can later be used as the batch file (Inp 21) that contains the information needed to run the model.

Tape 6
Tape 6 provides an "echo" of the Input data files if the Input data is being "debugged". The information "echoed" is the delay tables, the efficiency tables, the station data, the reservoir data, the reservoir area data, the "virgin" flow data, and the diversion data if JPRIVER is called.

Tape 8
Tape 8 contains the "virgin" flow in cfs at every station. The flows are reported by month for every year simulated.

Tape 9
Tape 9 contains the flow in cfs at every station after all the diversions have been made. The flows are reported by month for every year simulated.

Tape 10
Tape 10 contains the water available in cfs for diversion at every station after all the diversions have been made. The flows are reported by month for every year simulated.

Tape 11
The information reported to Tape 11 is more complicated than the information reported to the other output files. Tape 11 accepts a label declaring the type of right called out and whether the right was fully or partially called out. Table I lists the labels and offers a brief description of what each label indicates. After the label, the station, the permit, the priority date, the percent called out, and the station name where the right is located are written to Tape 11. Finally, there are several messages that can be written to Tape 11 depending on the reason the right was called out. Table II lists the callout messages, the variables used by the messages, and the situation for which each message would be written to Tape 11.

Tapes 12 and 13
The information written to Tapes 12 and 13 includes: the number of months in the simulation since the program started; the permit number of the right called out (diversion rights for Tape 12 and instream flow rights for Tape 13); the percent of the right called out (calculated by dividing the amount not met by the amount required); and the station where the right is located.

Tapes 12A and 13A
Tapes 12A and 13A are Tapes 12 and 13 sorted by permit number, month, and year.

HEAD
HEAD is a subroutine that writes the header, time, and date for each run to the output files. These files include Tape 8, Tape 9, Tape 10, Tape 11, Tape 18, Tape 19, Tape 12A, and Tape 13A.

REPEATED PROGRAMS

Repeated programs are subroutines that are called from other subroutines, or functions that are performed more than once.

Table I Tape 11 Call-Out Labels


LABEL           EXPLANATION

IFR NOT MET     INSTREAM FLOW RIGHT NOT MET FROM RIVER

NO DIVERSION    NO DIVERSION POSSIBLE FROM RIVER

PART DIVERSN    DIVERSION PARTIALLY MET FROM RIVER

NO PROJ RIV     NO SENIOR PROJECT RIGHT POSSIBLE FROM THE RIVER DURING A SPILL CONDITION

PART PROJ RIV   PARTIAL SENIOR PROJECT RIGHT FROM THE RIVER DURING A SPILL CONDITION

NO PROJ RES     NO SENIOR PROJECT RIGHT POSSIBLE FROM RESERVOIR

PART PROJ RES   PARTIAL SENIOR PROJECT RIGHT FROM RESERVOIR STORAGE

NO RES STOR     NO STORAGE IN THE RESERVOIR FROM THE RIVER

PART RES STOR   PARTIAL STORAGE FOR THE RESERVOIR RIGHT

NO JPR NOSP     NO JUNIOR PROJECT RIGHT MET FROM RESERVOIR WHEN THE RESERVOIR IS NOT SPILLING

PART JPR NOSP   JUNIOR PROJECT RIGHT PARTIALLY MET FROM STORAGE WHEN THE RESERVOIR IS NOT SPILLING

NO JPR RIV      JUNIOR PROJECT RIGHT NOT MET FROM THE RIVER WHEN THE RESERVOIR IS NOT SPILLING

PART JPR RIV    JUNIOR PROJECT RIGHT PARTIALLY MET FROM RIVER WHEN THE RESERVOIR IS NOT SPILLING

NO PJ 2ND RES   NO SENIOR PROJECT RIGHT POSSIBLE FROM THE SECOND RESERVOIR

PT PJ 2ND RES   PARTIAL SENIOR PROJECT RIGHT POSSIBLE FROM THE SECOND RESERVOIR

NO 2ND JPR NS   NO JUNIOR PROJECT RIGHT MET FROM SECOND RESERVOIR WHEN THE RESERVOIR IS NOT SPILLING

PT 2ND JPR NS   PARTIAL JUNIOR PROJECT RIGHT FROM SECOND RESERVOIR WHEN THE RESERVOIR IS NOT SPILLING

WT X LIM PJ 1   A WATER EXCHANGE WITH A PROJECT RIGHT NOT PHYSICALLY DOWNSTREAM FROM ITS RESERVOIR WAS LIMITED

WT X LIM PJ 2   A WATER EXCHANGE WITH A PROJECT RIGHT NOT PHYSICALLY DOWNSTREAM FROM ITS SECOND RESERVOIR WAS LIMITED

Table II Tape 11 Call-Out Messages

[AMOUNT] REQ [AMOUNT] AVAIL AT STA [STATION]

    WHEN A RIGHT IS PARTIALLY SATISFIED WITH FLOW FROM THE 
    RIVER, IT DECLARES THE AMOUNT REQUIRED BY THE RIGHT AND 
    THE AMOUNT AVAILABLE FOR DIVERSION AND THE STATION AT 
    WHICH THE FLOW IS AVAILABLE.

[AMOUNT] REQ [AMOUNT] AVAIL AT RES [RESERVOIR]

    WHEN A PROJECT RIGHT IS PARTIALLY SATISFIED BY RESERVOIR 
    STORAGE, IT DECLARES THE AMOUNT REQUIRED BY THE PROJECT 
    RIGHT AND THE AMOUNT AVAILABLE FROM THE RESERVOIR AND THE 
    CODE THAT IDENTIFIES THE RESERVOIR CALLED.

[AMOUNT] REQ [AMOUNT] RSRIT AVAIL [RESERVOIR]-[RIGHT]

    WHEN A PROJECT RIGHT IS PARTIALLY SATISFIED BY RESERVOIR 
    RIGHT STORAGE, IT DECLARES THE AMOUNT REQUIRED BY THE 
    PROJECT RIGHT AND THE AMOUNT AVAILABLE FROM THE RESERVOIR 
    RIGHT AND THE CODE THAT IDENTIFIES THE RESERVOIR AND THE 
    RESERVOIR RIGHT CALLED.

[AMOUNT] REQ OUTFLOW [AMOUNT] OUTFLOW RES [RESERVOIR]

    WHEN THE REMAINING OUTLET CAPACITY OF A RESERVOIR IS LESS 
    THAN THE AMOUNT REQUIRED TO SATISFY A PROJECT RIGHT, IT 
    DECLARES THE AMOUNT REQUIRED THE FLOW AVAILABLE AND THE 
    CODE THAT IDENTIFIES THE RESERVOIR CALLED.

[AMOUNT] REQ OUTFLOW AT MAX - RES [RESERVOIR]

    WHEN THE FLOW CAPACITY OF A RESERVOIR IS AT ITS MAXIMUM 
    AND THE RESERVOIR CAN NOT RELEASE WATER TO SATISFY A 
    PROJECT RIGHT, IT DECLARES THE AMOUNT REQUIRED AND THE 
    CODE THAT IDENTIFIES THE RESERVOIR CALLED.

SEN DS [RIGHT] NOT FULLY MET AT [STATION]

    WHEN A SENIOR DOWNSTREAM RIGHT HAS NOT BEEN FULLY 
    SATISFIED, DECLARES THE TYPE OF RIGHT (DIV FOR DIVERSION, 
    IFR FOR INSTREAM FLOW, RES FOR RESERVOIRS) AND THE 
    STATION WHERE THE SENIOR RIGHT IS LOCATED.

FLOW ADJUSTMENTS
Adjusting or checking the flow at every downstream station is done by several sections of the program. To adjust the flow at every station downstream, a program checks the stream order of the next station in the station array. Figure 3 demonstrates station numbers and stream orders. If the stream orders equals the current stream order, the flow in the stream flow is adjusted.

Furthermore, if the stream order from the next station is equal to the current stream order minus one, the stream order is set equal to the current stream order minus one and the flow is adjusted at the downstream station. Eventually, the stream order equals one, which is the order for the main stream in the model, and the flow will only be adjusted on the main branch. In this manner, WIRSOS only adjusts the flow at stations physically downstream from the current station (i.e. those with equal or lesser stream orders).

CHECK
CHECK is a subroutine that was written to check if any downstream rights have not been fully satisfied. CHECK is called from RESADJS, DIVEVAL, JPRIVER, and PROJRITE. If a senior instream flow, diversion, or reservoir right was not satisfied, the subroutine checks to see if the senior right is downstream from the current right. If the senior right is downstream, a message is written to Tape 11 and a flag is set. When CHECK returns control of the program to the calling subroutine, that subroutine checks the flag set by CHECK. If the flag is true, the calling subroutine increments the counter for rights called out, enters the station for the current right into an array, and exits to the main program since the current right cannot be processed.


Figure 3 Stations and stream order river schematic.

RETMON
RETMON is called when a right cannot be met due to water availability. For a given diversion amount, RETMON calculates the return flow and adds that return flow to the available water for the current month. The subroutine then tries to satisfy the requested diversion. If the diversion still can not be met, the amount required is reduced to the smallest amount available downstream from the diversion station. The return flow for this amount is then calculated and added to the water available downstream. The program then tries again to satisfy the diversion. The process is repeated until the amount requested can be satisfied. In this manner, a diversion has the right to its own return flow. Table III shows this process for an imaginary right.

The station where availability controls the diversion amount is defined as the control station to be passed to the calling subroutine and RETMON returns control to the calling program.

RETFLW
RETFLW distributes the return flow according to the type of return flow delay used. The subroutine finds the station and stream order in the station array, and then finds the delay table for the current return flow code. The return flow code indicates how the return flow table is used. The values in the return flow table are the percentages of the total return flow that will be distributed each month. The twelve values in each table must sum to equal 100.

Table III Example diversion utilizing return flows.


     Example of Computing "Normal Diversion" Amount
     When River Flow is Greater than Available Flow*

                          DIVER
    Differ           (Permit #N1961)          AVWRET
    0.1513                2.0000              0.0487
    0.1312                1.7987              1.8487
    0.1113                1.6175              1.6675
    0.0968                1.4545              1.5045
    0.0821                1.3078              1.3578
    0.0689                1.1757              1.1068
    0.0570                1.0568              0.9998
    0.0463                0.9498              0.9035
    0.0366                0.8538              0.8169
    0.0280                0.7669              0.7389
    0.0202                0.6889              0.6687
    0.0130                0.6187              0.6055
    0.0068                0.5555              0.5487
    0.0012                0.4987              0.4975
   -0.0040                0.4475              0.4515

Permit #N1961 can divert 0.4475 CFS DIFFER = DIVER - AVWRET AVWRET = (AVAIL + RET) DIVER = Diversion Amount, Initially set to 2.0 CFS for N1961 Right. AVAIL = Minimum Downstream Flow Available for Diversion. EFFIECIENCY = 10% RET = DIVER * Amount Returned in Current Month (100% * (1-Efficiency) RET (Initial) = (2.0) * (0.9) = 1.8 CFS * Also Applies to Off-Channel Storage Reservoirs

A delay code of 0-50 indicates that the return flow is returned to the stream system for the next twelve months starting with the current month as depicted in Figure 4a. The remaining a delay code (51-99) indicate that the first value is the percentage to be returned for the month of January, and the second value is the percentage returned for the month of February. Every column corresponds to a month as depicted in Figure 4b, and the program reads the value for the current month in determining the return flow for that month. The program returns the proper percentage of the return flow for the next eleven months. The return flows are returned to stations downstream from the diversion station, this can include stations on another branch of the river or to a station on another diversion ditch. Figure 5 shows a water right schematic with return flow depicted.

Delay       1    2    3    4    5    6    7    8    9    10   11   12
Number     ----------------------------------------------------------- = 100%
11         59   27    4    2    1    1    1    1    1     1    1    1
Figure 4a Non-month specific delay table.

Delay      Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov  Dec 
Number     ---------------------------------------------------------- = 100%
11          1    1    1    1    1    1   13   35   32   11    2    1
Figure 4b Month specific delay table.

RESCHK
There are three factors that can limit the amount of water that a project right can draw from a reservoir. These are the amount of water available from the reservoir, the flow capacity of the reservoir, and the amount of water available from a particular reservoir right if the project right is tied to a particular reservoir right. If a project right is tied to a particular reservoir right, that becomes the controlling factor, not the amount available from reservoir storage. RESCHK determines which of the three is the controlling factor and if that factor will limit the amount of water the project right is allowed to withdraw. If the project right is called out, RESCHK writes a message to Tape 11 declaring the type of right called out and the factor that limited the reservoir release. The program also sets a flag that is read by the calling program. This flag indicates to the calling program whether the right was called out, and if it was called out, what reservoir release factor limited the right.


Figure 5 Water rights schematic.

LIMAVL
LIMAVL writes a message to Tape 11 if a diversion, instream flow, or reservoir right is called out because of a lack of water available for diversion. The calling program passes the label declaring the type of right not satisfied, the diversion station, the permit number, the priority date, the percent called out, the diversion station name, the amount requested, the amount available, and the controlling station (the station where the availability is the least) to LIMAVL. Given this information LIMAVL writes a call out message to Tape 11.

PAGE11
PAGE11 writes the column headers to the output file Tape 11.

CVMGM
CVMGM is a function called by the subroutine RESRLSE. CVMGM returns the lesser of two values. The remaining reservoir capacity and the maximum vacant capacity declared in the reservoir data file are the two factors that can limit the amount of water a reservoir can store in a given year. These two values and the quantity of the vacant capacity subtracted from the remaining capacity are passed as arguments to CVMGM. CVMGM initially sets the amount that can be stored for the water year to the vacant capacity. If the vacant capacity subtracted from the remaining capacity is less than zero, the amount that can stored for the water year is set to the remaining capacity.

CVMGT
CVMGT is a function called by RIVDIS and AVLDIS. CVMGT returns one of two values depending on whether the logical argument passed to is true or false. The flow or the availability in the river at a station, the amount to be removed or added at that station, and a logical argument are passed to CVMGT. CVMGT checks the logical argument. If it is true, the current station is physically downstream from the releasing or diverting station. The water is then added or removed from the current station. Otherwise the current station is not downstream from the releasing or diverting station and no adjustment is necessary.

RIVDIS
RIVDIS adds/removes any water discharged/diverted to/from the river flow array. The calling program passes the starting station number, the ending station number, the stream order of the discharge/diversion station, and the amount added/removed to/from the stream. The program then checks to find all downstream stations between the starting station and the ending station, and adjusts the flow at those stations.

AVLDIS
AVLDIS adds/removes any water discharged/diverted to/from an availability array. The calling program passes the availability array, the starting station number, the ending station number, the stream order of the discharge/diversion station, and the amount added/removed to/from the stream. The program then checks to find all downstream stations between the starting station and the ending station, and adjusts the availability at those stations.

RRDIS
If a project right is not tied to a reservoir right, RRDIS removes the water released to satisfy the project right from the most senior reservoir right. However, if the most senior right does not have enough water left to satisfy the project right, RRDIS removes what it can from the most senior right and the rest is removed from the next most senior right. This is repeated until the water has been removed from the rights or until all (up to four) of the reservoir right accounts associated with a reservoir are empty.

SCNDRESV
This subroutine tries to satisfy the remainder of a project right from a second reservoir. The program calculates the water available from reservoir storage, the flow available from the reservoir, and the water available from a reservoir right if the project right is tied to a particular right. RESCHK is then called to determine if the remaining project right can be met. After RESCHK, the amount of the right that was satisfied is determined, the remaining right is set, any water released is added to the project releases for that reservoir, the water released is removed from current reservoir storage, the reservoir rights are adjusted (either according to the right called or by RRDIS), and the water is distributed to all stations between the reservoir and the project right diversion station by RIVDIS. This subroutine is similar to JPREVAL.

USER INTERFACE

With the original WIRSOS model, every Input and output file had a distinct name; and any deviation from these names would prevent the model from running. In addition, the run control input file contained the name or header that described each run, the number of runoff stations, and whether reservoirs were to be modeled. The information in the run control input file was changed for each separate model run. To make the model more flexible, a previous model user created an interactive user interface for the model. This interface is composed of four sections: the interactive user interface run control; the input data file names; the output file names; and the model run information. In addition to adding the interface to WIRSOS, each section was developed into its own subroutine. As more modifications were completed, the amount of information entered from the user interactive interface increased. Figure 6 is a simplified flow chart of the interactive user interface.

Two new features were added to the existing interface. First, the user can create a file (Inp 21) that contains all the user interface information. The model can read the information from this file and the data is not entered from the screen. By answering a series of questions, the user can specify what information is to be read from the file and what information is entered from the screen.

Second, the information requested by the user interface is written to a file (Tape 5). This file can be used to run the model in batch mode.


Figure 6 Flow chart of interactive user interface.

An option common to each interactive input section is that a screen is then presented that displays the information that was just entered. The user is given the option of changing any incorrect names. The interface was modified to allow the model user to choose the data that is wrong and to change that data. Before this modification, the model user had to re-enter all the data in a section. The model user can also choose to re-enter all the data by choosing zero. In addition, the modeler must answer all queries with on of the requested responses or the model will re-ask the question.

HEADER
HEADER is the subroutine that controls the interactive user interface. The user is directed to chose how they want to enter the run control data and what to name the echo file (Tape 5). If the model is being run in batch mode HEADER reads the input file names, the output file names, and the run control information from the batch file (Inp 21). The subroutine then directs the modeler to decide which information read from the batch file is used in the current simulation. HEADER next calls the subroutines INPUT, OUTPUT, and MDLRUN. The last option given to the model user is whether to build the data debugging file (Tape 6). If the debugging file is built, the run control information is written to this file.

INPUT and OUTPUT
The default file names for the input data files and the output data files are given in Table IV and Table V. Before the interactive user interface, the input and output data files had to be in the same directory as the WIRSOS program for the model to operate.

The interactive user interface now allows the model user to call the data files anything, and to place those files in any directory on any drive. If the model user is entering the input or output data file names from the screen, they are prompted to enter the names of the input or output data files. However, the model can leave the input or output files named according to the 'Inpl and 'Tape' scheme shown in Figure 7 and Figure 8 since they are the default names used in the program. The input file names are read by the subroutine INPUT and the output file names are read by the subroutine OUTPUT.

EFFICIENCY TABLES. While reading the input file names, the modeler is given the option to enter a file name for the efficiency tables. If an efficiency file is read, a flag is set that tells the rest of the program to use monthly efficiencies.

RIGHTS CALLED OUT MODIFICATION. The modeler is given the option to modify the diversion rights called out file (Tape 12) and the instream flow rights called out file (Tape 13) during the output file name section of the interactive user interface. If the files are to be modified, the modeler is asked for the name of the files created (Tape 12a and Tape 13a by default). Later, after the model has simulated each year of operation, the main program calls the subroutine TWELVE that converts the output file format.

Table IV Default input file names.


INP1    Station data.

INP2    Runoff data.

INP3    Instream flow data.

INP4    Diversion data.

INP7    Delay tables.

INP14   Area versus Capacity data.

INP15   Reservoir data.

INP16   Reservoir rights data.

INP17   Junior project rights data.

INP20   Efficiency tables.

MDLRUN
The interactive user interface reads the header that described the model run, the number of stations where runoff data is entered,, the first year to be simulated, whether reservoirs were to be modeled during the simulation, whether the model is to be run on a calendar versus a water year, whether to reset the reservoir rights to zero at the beginning of the water year or to the previous years reservoir rights account, and whether to store an extreme supply of water in the reservoirs. What the user interface does is allow the modeler to enter this information from the screen, or to modify the information if it has been read from a file.

Table V Default output file names.


TAPE8      "Virgin" river flows.

TAPE9      Final river flows.

TAPE10     Water availability in the river.

TAPE11     Rights "called-out" report.

TAPE12     Diversion rights called-out.

TAPE13     Instream flow rights called-out.

TAPE18     Final reservoir report.

TAPE19     Final reservoir rights report.

TAPE12A    Diversion rights called-out sorted by permit and year.

TAPE13A    Instream flow rights called-out sorted by permit and year.

FIRST YEAR OF SIMULATION. Another option that has been added is the ability to define the first year of model simulation. If the user knows that the runoff data represents data beginning in 1945, 1945 is entered as the first year of the model run. The model then prints the year of operation to the output files. Before this option was added, the program printed year 1, year 2, year 3, year N to the output files. If the user does not know the first year of model operation, a value of 1 should be entered to indicate to the program that it is the first year of data. The first year of model simulation is part of the model run information section of the interactive user interface.

CALENDAR YEAR. A problem created when the program was modified by several previous model users, was the type of year used to operate the model. The original program operated on a water year which begins in October. The first month of data in the input files corresponds to October (i.e. October is the first month of the year). All year-to-date storage or diversion amounts are reset to zero and all reservoir flags are reset to false at the first of October. However, in a few of the later versions of WIRSOS, the model was modified to operate on a calendar year (January is the first month of the year). All year-to-date storage, diversion amounts, and reservoir flags are still reset at the first of October, but the first month in the data files correspond to January. This creates a problem since the runoff in January is not the same as October and the diversion amounts are different for January and October. Also, when the program uses the number of days in a month to convert acre-feet to cfs, the flow values will be changed since every month does not have the same number of days.

To eliminate the need to convert all the calendar year files to a water year, the modeler is given the option of choosing the type of year to be used by the model. This option is part of the model run information presented with the interactive user interface. If a modeler wants to run the model on a calendar year, they choose this option at the start of a model run. The days in a month and the month names arrays are then set to represent a calendar year. Otherwise, the two arrays are set to represent a water year.

READING MODEL RUN INPUT DATA

DELAY
The subroutine DELAY opens the delay table Input file (Inp 7) and reads the delay codes and the monthly return flow tables from that file. There can be up to 99 return flow delay types in the delay file, and each delay has a table of twelve values that correspond to the twelve months of the year. Each value is the percentage of the return flow, from a diversion, that is returned to the river system at its return station for a month of the year. The values entered as return flow percentages must sum to 100%.

EFFNCY
Efficiency indicates how much of the water diverted from the river system is used by the water right holder. The portion not used is returned to the system by the subroutine RETFLW as discussed previously. The standard method to determine efficiencies is to enter a single value that is the average efficiency of the water rights. Figure 7 is an example of how crop consumptive use could be used to calculate efficiency and Table VI shows a distribution of losses and return flows.

A few agencies require efficiencies to be determined for each month that the right diverts water. The subroutine EFFNCY was written to read a table of monthly efficiency values from an Input file (Inp 20). This file is organized like the delay table file and the first value read is the efficiency code, and the following twelve values are the monthly efficiency values. There can be up to 99 efficiency tables read from the monthly efficiency file.


Figure 7 Crop consumptive use vs. diversion rate.

To use the monthly efficiency table, the Input data file formats in the diversion data bases do not have to be changed. When the model reads an efficiency value for a diversion, it reads it as a real number. If monthly efficiencies are being used, the program converts the efficiency value to an integer efficiency code. The efficiency code is then checked to see if it corresponds to one of the efficiency codes read from the monthly efficiency file. If the value does not correspond to an efficiency code, the program operation is terminated. If the value does correspond to an efficiency code, the program uses the efficiency value that corresponds to the current month to determine the total amount of water returning to the river from the current month's diversion. If monthly efficiencies are not being used, the program uses the efficiency value read to determine the total amount of water returning to the system from the current month's diversion. No modification of the diversion data bases is necessary, except to create a table of monthly efficiency values if monthly efficiencies are used.

Table VI Distribution of losses and return flows.

                          Distribution of Losses and Return Flows

                                     Distribution of Non-Recoverable
                                     Losses and Recoverable Return Flow
                                     for an Assumed Headgate Diversion of
                                     100,000 Acre Feet
               Loss expressed as     ------------------------------------
               a percentage of       Non-Recoverable        Recoverable         Total
               --------------------  -----------------   ----------------   ------------------
               Headgate   Indicated           Amount              Amount              Amount
  Function     Diversion  Function   Percent  Acre Ft.   Percent  Acre Ft.  Percent   Acre Ft.

Conveyance 25 Surface 25 30 1.88 70 4.38 100 6.25 Seepage 75 5 0.94 95 17.81 100 18.75 Sub-Total 2.81 22.19 25.00 Evapotranspiration 38 100 100 38.00 0 0.00 100 38.00 On Farm Application 37 Surface 50 15 2.78 85 15.73 100 18.50 Percolation 50 5 0.93 95 17.58 100 18.50 Sub-total 3.70 33.30 37.00 Total Losses 4.65 20.10 24.75 Surface 1.86 35.39 37.25 Seepage and Percolation 38.00 0.00 38.00 Grand Total of Losses 44.51 55.49 100.00 Ditch Headgate Efficiency = Evapotrans/Total Diversion = 38% Farm Headgate Efficiency = Evapotrans/Farm HG Delivery = 51%

STATION
STATION is a subroutine that reads the station numbers, stream orders, and station names/descriptions from the station input file (Inp 1). There can be up to 1000 stations in the station input file. After all the stations have been read into the arrays for station, stream order, and station name, the subroutine sets the number of stations equal to the number of stations read from the input file and each station is assigned a number. This number is used to locate a station or stream order in the station array.

RRBALNC
RRBALNC reads the reservoir rights from the reservoir rights file (Inp 16), and sums the volumes permitted by each right for the reservoir. The volume permitted by each individual right is then divided by total permitted volume. This gives the percent of the total permitted volume that each reservoir right controls. The number of rights associated with each reservoir, the volume controlled by each right, and the total number of reservoir rights are determined in RRBALNC.

RESDATA
RESDATA is a subroutine that reads the reservoir data from the reservoir data file (Inp 15). Each reservoir in this file requires three lines of data. The information read from line one includes the reservoir name, the reservoir station, the reservoir code, the flag that indicates the reservoir is an off-channel storage facility, the flag that indicates whether the reservoir is to be modeled, the minimum reservoir storage volume, the maximum reservoir storage volume, the maximum primary outlet capacity, the initial storage volume, the evaporation rates for twelve months, and the maximum storage that can be diverted during a water year. The information read from line two includes the non-project releases for twelve months, the power release goal month, the power release goal volume, the percent of the beginning volume to assign to each reservoir right, the minimum release from a reservoir, the off-channel storage reservoir diversion station, the off-channel storage reservoir diversion efficiency, the number of off-channel storage reservoir diversion return flow stations, and the off-channel storage reservoir diversion canal capacity. Line three contains the return flow stations, the percent returned at each station, and the delay code of the delay table used at each station.

The non-project releases are the releases made from the reservoir for each month. They are a percent of the water currently available for release from the reservoir. The power release goal volume is the reservoir volume remaining after the power releases are made, and the month set for the program to reach the goal volume is the power goal month.

After reading the data from the Input file, RESDATA sets all flags and initial values on key variables for each reservoir. The flags are the junior project rights processed with the reservoir, the reservoir rights met, the one-fill, and the spill flags. The key variables that are set to zero are the power release for each month, the power required for each month, the index of reservoir rights, the reservoir right year-to-date storage, the monthly storage, the extreme monthly storage, and the total year-to-date storage. The current storage is set to the initial volume. RESDATA then finds the reservoir station in the station array and sets the stream order at the reservoir equal to the stream order of that station. The subroutine finally sets the number of reservoirs equal to the number of the active reservoir with the highest reservoir code.

There are two options for setting the reservoir rights year-to-date during the interactive user interface. First, the model user can choose to set the reservoir rights year-to-date to zero. The reservoir rights year- to-date will then be set to zero at the start of each water year for the rest of the simulation. The second option is to set the reservoir rights year-to-date equal to the previous years reservoir right account.

If the model user chooses to set the reservoir rights year-to-date equal to the previous years account, there are two options for dividing the initial storage among the reservoir rights. First, the modeler can enter up to four values that correspond to the percent of the initial reservoir volume to be assigned to each reservoir right, the sum of these four values must equal 100%. If these values are entered, the program multiplies the value times the beginning volume to establish the initial reservoir rights year-to-date and the initial reservoir rights account. Second, the initial volume can be divided between the reservoir rights according to the percent of the permitted volume that each reservoir right controls (as determined by RRBALNC). This is done by setting the four values for dividing initial storage to zero in the reservoir data input file.

OFF-CHANNEL STORAGE RESERVOIRS. Off-channel storage reservoirs were not handled by the original WIRSOS model. To model an off-channel reservoir, the user had to use diversions and return flows to simulate reservoir operation. To simplify this procedure, the model was modified to allow off-channel storage reservoirs and the subroutine RESDATA was modified to read off-channel reservoir data. RESDATA reads the off-channel storage data from the third line and the end of the second line in the reservoir data input file. RESDATA checks to see if monthly diversion efficiencies are being used during the current run. If monthly diversion efficiencies are being used, the off-channel diversion canal efficiency is converted to an integer efficiency code and the efficiency tables are searched for this value. RESDATA also finds the off-channel storage diversion station for in the station array and sets the stream order at the off-channel diversion station equal to the stream order of that station.

RESAREA
RESAREA reads the area versus capacity information from the reservoir area-capacity input file (Inp 14). The subroutine reads the reservoir code for the reservoir to which the area-capacity information is to be applied. RESAREA then reads the range, the upper capacity limit, the equation type, and the three coefficients used in the area-capacity equations. The range is the number of area-capacity relationships for the reservoir (up to three), and the upper capacity limit is the storage volume in the reservoir at which the program switches to another area-capacity relationship for calculating surface area. The model has a choice of five equations for calculating the surface area of a reservoir based on its current storage capacity, and the equation type directs the program as to which equation to use. The three coefficients are constants that are used in the equations to determine surface area for a given reservoir storage.

FLOW
FLOW reads the runoff data from the runoff data input file (Inp 2) and stores that information in the second year of the river array. As discussed previously, the information is read into the second year array so that the first year of data is not erased, and a separate subroutine is not necessary to read in the initial year of runoff data. Data is then transferred to the first year array as necessary for model operation. The information read is the station where the runoff or flow enters the system and each month's runoff at that station. The subroutine then converts the runoff from acre-feet to cubic feet per second (cfs) and finds the runoff station in the station array. once the runoff station is found, the stream order of the runoff station is determined. After obtaining the stream order, FLOW adds the runoff to every station downstream from the runoff station. When the data from all the runoff stations has been read and the water distributed through the system, the subroutine writes the year's "virgin" flow in the river to the initial flow report (Tape 8). Figure 8 shows how runoff is distributed through a river system by WIRSOS.

DATA CHECKING

JPRCHK
JPRCHK checks the rights in the junior project rights input data file to determine if all rights are physically downstream from their associated reservoir. The subroutine reads a single junior project right and checks if that right is downstream from its reservoir. A right is downstream if its station number is greater than the reservoirs station number and the stream order of the right is less than or equal to the stream order at the reservoir station. JPRCHK also checks if the right is downstream from the second reservoir if the right calls on two reservoirs. If a junior project right is not downstream from its reservoir an error message is printed and the program stops.

PRICHK, IFRCHK, and RSVCHK
These subroutines determine if the rights in the junior project rights, diversion, instream flow, and reservoir rights data input files have been entered in the proper sequence. These subroutines read two rights from the same data base and compares their priority dates to determine if the first right is older than the second right. They also checks if two rights have the same priority date. If two rights have the same priority date, the subroutines determine if the upstream right is first in the data base. If the two rights read are fine, the next operation is to read the next right and compare it with the second right already read into the subroutine. If the rights read are not entered in the proper sequence, the subroutines write an error message to the screen and the program stops. PRICHK checks the junior project and diversion data files, IFRCHK checks the instream flow data file, and RSVCHK checks the reservoir rights data file.

STACHK
STACHK determines if the stations were entered correctly in the station data file. Station are entered from the lowest station number (the station furthest upstream) to the highest station number (the station furthest downstream). If the stations are not entered in this order, an error message is printed to the screen and the program operation stops.

MAIN BODY OF THE PROGRAM

RESRLSE
RESRLSE calculates the power and non-project releases from each reservoir. If it is the beginning of the water year, the subroutine also resets the reservoir fill flag and the reservoir spill flag; clears the reservoir rights year-to-date and the total year-to-date storage accounts; and the reservoir rights flag is reset to 'NO'; the reservoir rights index is set to zero or to the previous water years reservoir right's account (depending on the option chosen during the interactive user interface. If the reservoir is being modeled in the current model run, the non-project and power releases are calculated. The power release required for the current month is compared with the outlet flow capacity of the reservoir and the water available from reservoir storage. The water released for power is then equal to the lesser of the following parameters: the power release requested, the outlet flow capacity of the reservoir, or the water available from reservoir storage. The water released for power is then subtracted from reservoir storage and the outlet flow capacity of the reservoir is reduced.

Non-project releases are calculated (non-project releases are a percentage of the available reservoir volume). The non- project releases are then compared with the outlet flow capacity of the reservoir and the available reservoir volume. The lesser of the non-project release requested, the outlet flow capacity of the reservoir, and the available reservoir volume is the amount released to the river system. The power and non-project releases are removed from the current reservoir storage and the amount release is added to the river array at all downstream stations downstream by RIVDIS and AVLDIS. The water released is also removed from the reservoir rights accounts. The amount removed from each reservoir right account is obtained by multiplying the release by the reservoir rights account divided by the current storage. Therefore, the percent of the current reservoir storage that each reservoir right controls is the percent of the release that is removed from each right.

ISFLWR
ISFLWR reads the instream flow rights from the instream flow rights data input file (Inp 3). The information read is the instream flow station, the instream flow permit number, the instream flow priority date, and the instream flow required for each month of the year. For the program to be able to compare the priority dates of each type of right, the priority date is converted from a month-day-year to a year-month-day format. This conversion is done in ISFLWR. If the last right has been read from the instream flow data file, ISFLWR sets the instream flow flag to true. This flag signals the main program not to process any more instream flow rights. The priority date is set to 99999999 after the last right is read. This causes the instream flow rights to have the lowest priority possible in the system so no other right will be injured.

RESRITE
RESRITE reads the reservoir rights from the reservoir rights data input file (Inp 16). The information read is the reservoir station, the reservoir permit number, the reservoir priority date, the reservoir code, the storage volume permitted, and whether it is the last right associated with this reservoir. The subroutine then converts the priority date from a month-day- year to a year-month-day format to make it possible to compare the date with the priority date from the instream flow and diversion rights. If the last right has been read from the reservoir right data file, RESRITE sets the reservoir rights flag to true. This flag signals the main program.not to process any more reservoir rights. The priority date is set to 99999999 after the last right is read. This causes the reservoir rights to have the lowest priority possible in the system so no other right will be injured.

DIVERS
DIVERS reads the diversion rights from the diversion rights data input file (Inp 4). The information read is the diversion flag, the reservoir right from which the diversion draws, the diversion station, the diversion type, the diversion efficiency, the diversion permit number, the diversion priority date, the number of return flow stations,, the diversion amount required for each month of the year, the return stations, the percent of the total return amount to return at that station, the return delay code, the flag that indicates whether water is drawn from a second reservoir, the second reservoirs code number, and the reservoir right from which to draw the water. The program then checks to see if monthly diversion efficiencies are being used. If monthly diversion efficiencies are being used, the diversion efficiency is converted to an integer efficiency code and the efficiency tables are searched for this value. If the efficiency code is not found in the efficiency tables an error message is written to the screen and program operation is stopped. The subroutine then converts the priority date from a month-day-year to a year-month-day format to make it possible to compare the date with the priority dates from the instream flow and reservoir rights. If the last right has been read from the diversion data file, DIVER sets the diversion flag to true. This flag signals the main program not to process any more diversion rights. The priority date is set to 99999999 after the last right is read. This causes the diversion rights to have the lowest priority possible in the system so no other right will be injured.

ISFLWA
If the amount of instream flow required is greater than zero, ISFLWA tries to satisfy the instream flow right. The instream flow station is first located in the station array. The flow required is then adjusted by subtracting the difference between the river flow and the water available from the flow required to satisfy the right. The water available in the river at that station is checked. If there is not enough water available to satisfy the instream flow right, the available water is assigned to the instream flow right, messages are written to rights called out files (Tape 11 and Tape 13), and the available water at the station is set to zero. However, if there is enough water available to satisfy the instream flow right, the water required is removed from the water available at the instream flow station.

RESADJS
RESADJS sets the diversion station equal to the reservoir station (or the reservoir diversion station for off-channel storage reservoir) and designates the stream order to that station as the stream order for the current reservoir. Next, the reservoir rights index (the counter of the number of reservoir rights processed for the current reservoir this month) is incremented by one and the code for the current reservoir right is set equal to the reservoir right index. If the reservoir has been filled once during the current water year, the subroutine returns control of the model to the main program. Otherwise, the subroutine calculates the remaining right. This calculation consists of subtracting the reservoir right's year- to-date storage (the amount already stored by the reservoir right in the current water year) from the reservoir right (the amount the law allows a reservoir right to store in a water year). The remaining right is then compared with the remaining vacant capacity (maximum reservoir storage allowed in a year minus the amount stored in the reservoir during the current water year) and the remaining reservoir capacity (the maximum reservoir capacity minus the water currently stored in the reservoir). The lesser of these three is the amount that can be diverted to the reservoir during the current month. The program also checks to see if the diversion capacity for an off-channel storage reservoir will limit the amount stored in the reservoir during the current month.

If the amount the reservoir is allowed to divert is greater than zero, RESADJS checks to see if any senior downstream diversion, instream flow, or reservoir rights were not satisfied. If any senior downstream rights were not satisfied, CHECK writes a message to Tape 11 stating that the current right was not met because a senior downstream right was not satisfied. If all senior downstream rights were satisfied, the subroutine finds the station downstream from the reservoir with the least amount of water available for diversion. This becomes the amount of water that can be stored in the reservoir during the current month.

Off-channel storage reservoirs have the right to the return flows from their diversion canals. If there is not enough water available to satisfy an off-channel storage right, RETMON is called to add the return flows from the diversion canal to the river downstream from the diversion station.

If the amount the reservoir is allowed to divert is greater than the water available for diversion (including no water available for diversion), the available water is stored in the reservoir, a message is written to Tape 11, and a flag (read by CHECK) indicating that a reservoir right was not completely satisfied is set.

The subroutine also sets a flag for the parameter that limited storage by the reservoir right. The flag consists of a code for the limiting parameter. The codes are shown in Table VII.

Table VII Factor that limited reservoir storage codes.


CODE LIMITING FACTOR
  1. The reservoir has previously been filled during the current water year.
  2. The remaining reservoir right has been satisfied.
  3. The remaining vacant capacity is less than the remaining right.
  4. The remaining reservoir capacity is less than the remaining right.
  5. The off-channel storage diversion canal capacity is less than the remaining right.
  6. A senior downstream right has been called out.
  7. The flow available for diversion is less than the remaining right.

If the reservoir was filled, a spill condition exists for the remainder of the month and a flag is set indicating that the reservoir was filled this water year. The amount of water stored in the reservoir during the month is added to the current storage, the year-to-date storage, the monthly storage, the reservoir right account, and the reservoir right year-to-date storage arrays. RESADJS next checks to see if the reservoir right was satisfied during the current month and flag is set to signal this condition to the main program. The amount of water stored in the reservoir is then removed from the water available for diversion downstream from the reservoir station (RIVDIS and AVLDIS). Additionally, for an off-channel storage reservoir, RETFLW is called to add the return flows from the diversion canal to the river downstream from the diversion station.

JPREVAL
JPREVAL is the part of the WIRSOS model that reads junior project rights and tries to satisfy those rights with water from their associated reservoir. Junior project rights are only processed by JPREVAL if a spill condition exists at the reservoir (spill conditions are processed by the subroutine PROJRITE). If the last reservoir right associated with the reservoir was processed, JPREVAL reads the first right associated with the current reservoir (each project right is evaluated separately according to priority date).

Similar to other sections of the model, the subroutine must find the junior project right station in the station array. The diversion efficiency is also converted to an integer efficiency code and found in the efficiency table if monthly efficiencies are being used. The water available from reservoir storage is calculated by subtracting the minimum reservoir volume from the current reservoir storage. The flow capacity available from the reservoir is calculated by subtracting the flow in the river below the reservoir station from the maximum flow capacity of the outlet works. If a junior project right is associated with a reservoir right, the amount available in that reservoir right's account is the limiting diversion amount. If either the remaining flow capacity or the water available from the reservoir (or reservoir right) restrict the reservoir's ability to satisfy the junior project right, a message will be written to Tape 11 by RESCHK. if the junior project right is allowed to draw on two reservoirs, JPREVAL calls SCNDRESV to satisfy the unsatisfied portion of the right. Any water released from the reservoir for the junior project right is added to the flow in the river between the reservoir station and the junior project right station by RIVDIS and the amount released is added to the project releases for that reservoir. JPREVAL calls RETFLW to return the water (diverted to the right but not consumed) to the river system.

JPRIVER
JPRIVER evaluates junior project rights read as regular diversions. Junior project rights have a priority date junior to the most junior reservoir right on the reservoir with which they are associated. If a junior project right was not completely satisfied by its reservoir, JPRIVER tries to satisfy the remainder of the junior right with natural flow from the river. JPRIVER first finds the diversion station in the station array. After the station is found, the subroutine checks to see if there is any water available for diversion at the diversion station. If no water is available for diversion, a message is written to Tape 11 by LIMAVL. If there is water available for diversion, the program calls CHECK to see if any senior downstream diversion, instream flow, or reservoir rights were not satisfied. If a senior downstream water right was not satisfied, a message is written to Tape 11. Assuming that there is water available for diversion at the diversion station and all senior downstream rights were satisfied, the maximum amount of water available at each station downstream from the diversion station is determined. The minimum water available downstream becomes the amount available for diversion at the current station. The subroutine checks to see if the amount available for diversion is greater than zero (writing a message to Tape 11 if it is not) and removes the amount diverted from the water available downstream (RIVDIS and AVLDIS). If the right remains unsatisfied a message is written to Tape 11 by LIMAVL. The return flows are calculated and returned to the system by the subroutine RETFLW.

DIVEVAL
DIVEVAL processes "normal" diversions. "Normal" diversions are not associated with a reservoir and receive their water from direct flow. The subroutine performs the same function as described under the subroutine JPRIVER with one exception. The exception is that DIVEVAL calls RETMON to add the return flow for the current month to the river. RETMON is called if there is not enough flow available downstream to satisfy the right. DIVEVAL then rechecks to see if there is enough water downstream to satisfy the right. Otherwise, the two subroutines are the same. RETFLW is called to return excess water to the river.

PROJRITE
PROJRITE processes senior project rights and junior project rights treated as senior water rights when a reservoir is full and spilling water. PROJRITE starts by trying to fill the junior project right from the available flow in the river. The procedure followed is the same as that described under the subroutine JPRIVER. PROJRITE then calls DIVCHK to determine if a water exchange is necessary and the size of the water exchange. PROJRITE then tries to fill the remaining right from its reservoir as described under the subroutine JPREVAL. RETFLW is called to return excess water to the river.

DIVCHK
DIVCHK determines if a project right entered in the diversion data base is physically downstream from its associated reservoir. If the right is not downstream from its reservoir, DIVCHK calculates a water exchange between the river and the reservoir. The subroutine determines the water available between the diversion station and the first station downstream from the reservoir and the diversion station. The water available is the maximum amount that the right can divert. The amount diverted by the right is released from the reservoir to replace the water removed from the stream. DIVCHK also does this for rights calling on two reservoirs.

RESMIN
RESMIN takes the minimum release from a reservoir input by the modeler and compares it to the flow in the river at the station above the reservoir station. Whichever of these is the least, is the flow that must be released from the reservoir. RESMIN then subtracts the flow in the river at the station below the reservoir station from this amount to obtain the amount of water that must be released from reservoir storage to satisfy the minimum release from the reservoir.

MINRSRL
Once RESMIN has determined the amount of water needed to satisfy the minimum release requirement from a reservoir, MINRSRL checks to see if the water is available from reservoir storage. If the water is available (or partially available), the water released is removed from current storage, the water is removed from the reservoir right accounts according to the percent of the current storage each reservoir right controls, the water released is added to the non-project reservoir releases, and the water is distributed to all stations downstream from the reservoir station by RIVDIS.

OVERSUP
OVERSUP determines if there is an extreme supply of water for the current month and what reservoirs are capable of storing that water. The program initializes three temporary arrays: one for the reservoir codes, one for the active reservoir flag, and one for the availability. The program then removes any inactive reservoirs from consideration and sorts the active reservoirs by station number (the reservoir furthest upstream is considered fist). OVERSUP checks each reservoir to see how much reservoir capacity it has and how much water is available to be stored. The amount available for storage is removed from the temporary availability array and added to the total amount available for storage. During this process any reservoir that is not capable of storing water is flagged inactive in the temporary activity array.

Inactive reservoirs are removed and the active reservoirs are again sorted by station number. To determine the amount stored in each reservoir the total storage is divided by the number of active reservoirs. The program then tries to store that amount in each active reservoir. A reservoir may not be able to store its allotted amount depending on the remaining reservoir capacity and the water available for storage. The remaining diversion capacity can also limit further reservoir storage for off-channel storage reservoirs. If any reservoir can not take its storage, that reservoir is flagged as inactive. Any water not stored by a reservoir remains in the total amount to be stored. The water stored is added to the current storage, the year-to-date storage, the monthly storage, the reservoir rights year-to-date, the reservoir right's account, the flag of reservoir rights met, the spill flag, the fill flag, and the extreme monthly storage are adjusted. Water is added to the reservoir rights accounts according to the amount of permitted reservoir storage that each reservoir right controls defined in RRBALNC. If the reservoir is an off-channel storage facility, the return flows are calculated and returned to the system. If there is any water remaining in the total amount to be stored, the program returns to the section that removes any inactive reservoirs and sorts the active reservoirs. This is repeated up to the total number of reservoirs.

EVAPR
For each active reservoir the user can define three storage ranges in the reservoir area input file (Inp 14). For each storage range, there is a different area versus capacity relationship. EVAPR sorts the number of ranges defined by the model user, and for each range it calls the subroutine EVAPSUB. After the areas for the initial storage and the final storage for the month are calculated by EVAPSUB, the two reservoir areas are averaged and used to calculate the evaporation from the reservoir for that month. The evaporation from a reservoir is removed from the current storage in that reservoir. The evaporation is removed from the reservoir rights account according to the amount of the current storage that each reservoir right controls.

EVAPSUB
EVAPSUB is one of the subroutines that was developed with the original program. EVAPSUB selects one of five equations that define an area versus capacity relationship. The equations are selected according to the equation type specified for the given storage range in the reservoir area-capacity curve data file. EVAPSUB returns an area for a given storage volume. The area is used to calculate evaporation.

EOM
EOM is called after each month of river system simulation. For each active reservoir, the subroutine writes the reservoir name, the monthly reservoir storage, the flow in the river at the reservoir station, the water required for power releases, the actual water released for power, the water required for non- project releases, the actual water released for non-project demands, the water released for project rights, the evaporation from the reservoir, the extreme supply stored during the month, and the current storage to a temporary output file (Tape 22). For each active reservoir, the subroutine also writes the reservoir number, the reservoir right number, the end-of-month reservoir right's account, the year-to-date reservoir right met, and a code (set in RESADJS) that indicates what limited reservoir storage at the reservoir rights priority date to a temporary output file (Tape 23).

The variables that track monthly project releases and monthly storage are reset to zero. The flag that indicates that a reservoir is spilling is reset and the flag that indicates that junior project rights have been processed with the reservoir is also reset.

The subroutine calculates the water required for power releases. Before calculating the power required and the power release, EOM checks to see if a power goal month has been set. If one has not been set, the power required and the power release are set to zero. However, if a goal month has been set, the subroutine sets the power required and the power release for the months remaining between the current month and the goal month. The power release goal is set by subtracting the power goal volume from the current storage in the reservoir. If the goal month is less than or equal to the current month, the goal month is reset to the same month as the goal month but for the next year. The number of months to reach the goal volume is calculated by counting the number of months between the current month and the goal month. The power release and the power required are computed by dividing the power release goal by the number of months until the power release goal month, provided that the power release goal is greater than zero.

END-OF-YEAR OUTPUT

EOY
The subroutine EOY writes to two output files at the end of each year of river system simulation after all rights have been addr essed. The first output file (Tape 9) records the water flowing (cfs) in the river system at every station for each month and the total flow (acre-feet) at every station for the year. The second output file (Tape 10) records the water available (cfs) in the river system at every station for each month and the total flow (acre-feet) available at every station for the year.

END-OF-RUN OUTPUT

TWELVE
When WIRSOS is run it creates two output files (Tape 12 and Tape 13). These files contain a list of the diversion and instream flow rights called out. Each right called out during a month is written to these files along with the percent called out and the station where the right is located. These files are then sorted by month, year, and permit number and written to a new file to make them easier to analyze. The restructuring of these output files was not performed by WIRSOS, but was done by a program that was executed after a model run. For simpler model operation and to consolidate model operations, a subroutine that performs this function was written.

TWELVE reads one month of data from the output file. The percent called out is then stored in an array location corresponding to the current month. Each permit is assigned its own array to contain the percent called out each month. Another month of data is then read from the output file. The program checks to see if any of the rights were called out during the months previously read. If the right was previously read, the percent called out is stored in the array address corresponding to the current month and one of the duplicate rights is deleted. otherwise, the percent called out is stored in the array for the new right. This is repeated until every right that was called out during the current year is read and checked for repetition. The program then sorts the rights according to an alpha-numeric priority. The lowest right number or right character is stored first in the rights called-out array. Once the rights are sorted, a header containing the year and the months of the year is written to the new output file. The permit numbers, the percent called out each month, and the station where the right is located are written to an output file. The process is repeated until every year of the model simulation is processed.

EOR
This subroutine is executed at the end of a model run after all the years have been simulated. EOR reads the information from the file written to during the subroutine EOM (Tape 22) and rewrites the data to another output file (Tape 18). In the process, the information is sorted by reservoir, month, and year. Tape 18 consists of a report of the status of each active reservoir at the end of each month for every year simulated by the model. The subroutine also creates headers and captions for the output file, so that the information is easier to understand.

TOR
This subroutine is executed at the end of a model run after all the years have been simulated. TOR reads the reservoir right information from the file written to during the subroutine EOM (Tape 23) and rewrites the data to another output file (Tape 19). In the process, the information is sorted by reservoir, reservoir right, month, and year. Tape 19 consists of a report of the status of each active reservoir and the rights associated with the reservoir at the end of each month for every year simulated by the model. The subroutine also creates headers and captions for the output file, so that the information is easier to understand.


Stroup, 1993 Table of Contents
Theses List
Water Resources Data System Library | Water Resources Data System Homepage