This document describes new features, enhancements, and changes included in RiverWare Version 1.2, released on October 27, 1997.

These changes are new to the executable since the release of RiverWare Version 1.1 on July 7, 1997.

Please direct questions to CADSWES Technical Support at (303) 492-0908 or support@cadswes.colorado.edu

Unlinked Inflow slots of Reservoirs no longer default to zero for timesteps where they do not have user input values. This previous behavior had some undesirable effects on simulation and often caused confusion in the modeling approach. Existing models which rely on Inflow slot default values of zero for dispatching of upper-most reservoirs must be updated to produce the same results under RiverWare 1.2. For both Simulation and Rulebased Simulation, previously defaulted Inflow slots should be explicitly set to “0” for all simulation timesteps.

Models which perform water quality computations will also need to be updated. Water quality constituent Inflow quantities no longer default to zero when the Reservoir Inflow is unlinked. The following slots will now need user input of “0” for all simulation timesteps to produce the same results as previous RiverWare versions:

Exceeding the user-specified maximum iterations when setting a slot value now aborts the simulation run. This occurs when, during iteration, a slot’s value is set too many times. Normally, the iteration is terminated when the new slot value and the old slot value differ by less than the specified convergence value. Previously, when the maximum iterations was exceeded, a diagnostic warning message was posted, the new slot value was not set, and simulation proceeded. Since this could result in a violation of mass balance beyond the limits of the user-specified convergence value, the behavior was eliminated.

The iteration count of a slot is incremented every time a new value is set. There is a different iteration count for each timestep of the simulation and for each series slot of a model. Maximum iterations are set to 20 by default, but may be changed in each series slot’s Configuration menu. Exceeding maximum iterations is rare. Slow convergence of the solution can indicate a modeling problem. The cause of excessive iterations should be determined before arbitrarily increasing the maximum. In certain cases, the problem can also be solved by relaxing the slot’s convergence criteria.

This change applies both to Simulation and Rulebased Simulation. In Rulebased Simulation, however, iteration counting is turned off by default. To enable the checking of maximum iterations in Rulebased Simulation, turn on the Check Iterations checkbox in the Run Control Panel’s View Controller Specific Parameters Dialog. Rulebased slot iteration counters for all slots are reset each time a rule begins to execute.

Listed below are all modifications made to Reservoir Objects.

A new User Method Category called Seepage Calc has been added to all Reservoirs. The new Category is used to account for seepage through and around the face of a dam. There are two User Methods available for selection in this Category: the default No Seepage and Linear Seepage Calc. The default Method performs no computations and instantiates no slots.

The Linear Seepage Calc method calculates dam seepage based on the Pool Elevation of the Reservoir and a set of coefficients. The coefficients are a seepage base elevation, a linear slope coefficient, and a linear intercept coefficient. All three are input into the Seepage Coefficients table slot. The seepage is computed as:

Coefficients may be specified which produce a negative seepage; however, since seepage is not permitted to be less than zero, negative seepage values are automatically reset to zero. Seepage is a Reservoir loss in the mass balance, but is not considered part of any Outflows or Spills. Seepage may be linked to another slot if desired. The Inputs and Outputs for this Method are:

A new User Method, Hydrologic Inflow and Loss, has been added to Level Power Reservoirs and Storage Reservoirs. This Method is selected in the Hydrologic Inflow Calculation Category. The Method allows Hydrologic Inflow and Hydrologic Inflow Adjust to be input by the user. If these slots are not linked, any timesteps which do not have input values default to zero. Hydrologic Inflow Net is then computed as the sum of the Hydrologic Inflow and the Hydrologic Inflow Adjust. All of this behavior occurs during the beginning of run, and is identical to the existing Input Hydrologic Inflow User Method.

The Hydrologic Inflow and Loss Method has special behavior when solving for Inflow using one of the following dispatch methods:

In these cases, the dispatching slot values may force the computation of a negative Inflow. If the dispatch method calculates a negative Inflow, the Hydrologic Inflow and Loss Method is invoked a second time. When the Method is invoked from a dispatch, it sets the Hydrologic Inflow Adjust to the value of the Inflow (a negative value), sets Inflow to zero, and recalculates the Hydrologic Inflow Net. If Hydrologic Inflow Adjust or Hydrologic Inflow Net are user input at this timestep, the run aborts with an error.

Listed below are all modifications made to Power Reservoir Objects.

The Peak Power Calc and Peak Base Power Calc User Methods have two modifications. A warning is no longer posted in the Diagnostics Output Window when the reservoir Pool Elevation is too low to generate power. The low Pool Elevation is not considered a modeling or system error. The Method accurately models this case, and simulation is unaffected.

The second modification concerns the minimum and maximum Operating Head. Previously, these values were set in the Min and Max fields of the Operating Head slot’s Configuration Dialog. This resulted in a warning message every time these criteria were violated. Since violation of the minimum or maximum Operating Head is common and acceptable for these Methods, the values are not the true minimum and maximum for the slot itself. These values are in fact Method parameters, and are now set on the Min and Max Operating Head slot. The new table slot has two rows, the first for minimum Operating Head, and the second for maximum Operating Head.

Listed below are all modifications made to Storage Reservoirs.

A new User Method, called Cubic Bank Storage Calc, has been added to the Bank Storage Calc Category of Storage Reservoirs. This Method has been developed to duplicate historical reservoir loss calculations for Brantley Reservoir. The calculated Change in Bank Storage is the volume of “net overall loss” including seepage, bank storage, and other unaccounted losses. Empirical coefficients are used to calculate a flow loss according to the following equation:

where y is the Reservoir flow loss, a and b are specific constants, and x is the current reservoir Pool Elevation. A different set of equation constants are used depending on whether the Reservoir Pool Elevation is rising or falling during the current timestep. The coefficients corresponding to rising and falling elevations are specified in the Cubic Bank Storage Rising Coeffs table and the Cubic Bank Storage Falling Coeffs table, respectively. If the Pool Elevation remains constant over the timestep, the coefficients corresponding to the last Pool Elevation change are used. If the Pool Elevation is constant during the first timestep(s) of the simulation, the falling coefficients table is used by default. Finally, the computed flow loss is converted to a volume loss for the timestep.

Due to many changes in the Rulebased Simulation Controller and Rule Processor over the past several releases, an overview is included at the end of these release notes. See the overview for a complete picture of the current Rulesbased Simulation logic.

The Rulebased Simulation controller now keeps track of Rule execution iterations. The iteration count is used to interrupt a run if a Rule executes more than 50 times in a single timestep. Previously, there was no way to interrupt infinite loops in the iteration between Rules and Simulation.

Checking of dispatch conditions is now delayed until all of a Rule’s slot assignments have been made. Previously, objects checked their dispatch conditions whenever a dispatching slot value was set. For Rules which only set a single slot, this created no ambiguity. For Rules which set multiple slots, however, this allowed objects to be placed on the dispatch queue even if the Rule had other slots yet to be set on this object. In some cases, the slots remaining to be set would have forced a different dispatch method to be selected. To alleviate any ambiguity, dispatch conditions are no longer checked until all of a Rule’s slot assignments have been made.

Errors generated during Rule execution calls to Simulation functions no longer abort the run. Errors are now returned to the Rule Processor for interpretation. Previously, any error generated in a Simulation engineering function which was called during the execution of a Rule automatically posted a message and aborted the run (the Simulation Controller still behaves this way). The Rule Processor, however, now catches simulation errors and terminates the executing rule instead. The rule does not continue, and no slot assignments are made. The rule may re-fire at a later time.

RiverWare Tcl procedures which invoke methods on the Engineering Objects are prevented from aborting the run. Since these functions solve hypothetical problems for the rules only and do not set slots, their failure should only impact the currently executing rule. All Tcl procedures, however, will continue to abort the run if fundamental errors are detected (incomplete arguments, invalid dates/times, etc.). The effects of errors in each of the currently defined Tcl procedures included in RiverWare are as follows:

The average Pool Elevation over the current timestep is now used to determine the maximum Release and Spill for C_getMaxOutflowGiven<Inflow/Storage/HW> Custom Tcl Routines. Previously, the Pool Elevation at the end of the current timestep (current Pool Elevation) was used. Now, the Pool Elevation at the beginning of the current timestep (previous Pool Elevation) is averaged with the most recent estimate of the Pool Elevation at the end of the current timestep. This average elevation is used in the Max Release/Max Turbine Q, Unregulated Spill Table, and Regulated Spill Table (if applicable) to determine the maximum Outflow.

The getMaxOutflowGivenInflow Custom Tcl Routine has been modified to not require a Pool Elevation value as a seed to the iterative solution. The new arguments for this function are as follows:

The following is a list of the bugs which were fixed for this release. If you wish to view the details for a specific bug, please browse to http://cadswes.colorado.edu/users/gnats-query.html and search our bug database. You will need a RiverWare user login and password.