RiverWare is now available and supported for Windows 2000 and Windows XP (it will also run on NT but CADSWES is supporting Windows 2000 and XP). The user should be aware of the following differences that exist in RiverWare for Windows:

The Open Object dialog has been completely re-written using the Qt graphical user interface toolkit. The new dialog has a slightly different layout, but all previous functionality remains in nearly the same place as in the old dialog.

In addition to numerous bug fixes from the old Open Object dialog, some of the new enhancements in the dialog include:

The text files generated when exporting a slot now include automatically generated comment lines (starting with "#"). These comment lines include the slot name and the scale and units of the data. Exported files for Table Slots and Agg Series Slots include one comment line for each slot column.

The background and foreground colors are controlled differently for Galaxy-based dialogs and Qt-based dialogs in RiverWare. Galaxy-based colors are controlled through the X-Windows manager. While Qt-based dialogs are controlled through the ’qtconfig’ application. A new environment variable, RW_SYNC_XRESOURCES, has been added to RiverWare. By setting this environment variable, Qt will query Galaxy and attempt to mimic the colors used by Galaxy. Galaxy dialogs often use a dithering algorithm, so colors may not match exactly.

The following enhancements to the RiverWare simulation objects are described briefly. The user is encouraged to consult the Simulation Objects Documentation in the online help for more detailed descriptions of the enhancements to the objects and their methods.

A new method that allows seepage to be routed using the Impulse Response method was added to the Reach object. The option to route seepage using this method becomes available when a seepage calculation method is chosen. Upon choosing to route seepage, the calculated seepage values (un-routed) are stored in the PreRouted Seepage slot. The routed values are stored in the Routed Seepage slot.

The Known Inflow slot name on the Reach was changed to Deterministic Local Inflow to better reflect the true content of the slot. Existing models that use the Known Inflow slot will be automatically updated to the Deterministic Local Inflow slot the first time the model is saved.

A new method that allows seepage to be routed using the Impulse Response method was added to the Distribution Canal. The option to route seepage using this method becomes available when a seepage calculation method is chosen. Upon choosing to route seepage, the calculated seepage values (un-routed) are stored in the PreRouted Seepage slot. The routed values are stored in the Routed Seepage slot.

A new convergence algorithm based on the bisection method is now used on Reservoir objects. Previously, in the event that the getMaxOutflow, getMaxRelease, getMinSpillGivenInflowRelease and mass balance functions did not converge, the functions would enter a second convergence algorithm that would determine the intersection of the two curves under the assumption that the curves were straight lines. This approach proved to be problematic in instances when the two curves are, in fact, not straight lines. For example, when the pool elevation drops below the spillway crest during a timestep, the spill is simulated using a decay function which does not exhibit linear behavior. To aide this problem and others, the line intersection algorithm was replaced with a search algorithm based on the bisection method. The bisection method is an incremental search algorithm in which the interval is always divided in half. Using this method, the assumption that the curves are linear is eliminated. For a more detailed description of the bisection convergence algorithm, see the Simulation Objects Documentation in the online help.

Previously, if the pool elevation dropped below the minimum power elevation during an iterative routine such as getMaxOutflowGivenInflow, the turbine release was set to zero. If the pool elevation rose above the minimum power elevation during the iteration, the turbine release was set according to the maximum release table. In the event that the pool elevation was near the minimum power elevation at the start of the function, this logic proved to be problematic because it introduced a discontinuity in the max release curve. For example, if the pool elevation was a tiny bit below the minimum power elevation, the release was zero. Yet, if the pool elevation in the next iteration was slightly above the minimum power elevation, the release could be set to some large value obtained from the maximum release table. In this situation convergence could not be obtained. To fix this convergence problem, it is now assumed that the turbine release is zero throughout the iterative function if the pool elevation at the previous timestep is less than the minimum power elevation. Similarly, it is assumed that a release is possible if the previous pool elevation is greater than the minimum power elevation even if the pool elevation during the function drops below the minimum power elevation.

NOTE: This change could significantly affect models that have reservoirs which operate close to the minimum power elevation. Neither the old nor the new approach represents physical reality, however, so a “real” fix to this problem is still needed.

The mass balance of the Reservoir was not converging in specific cases when the storage value was very near zero. In RiverWare the massBalanceSolveStorage convergence routine looks for the intersection of the reservoir mass balance equation and some other equation such as max outflow. A problem was occurring when the intersection of the lines was very close to the storage = zero limit and the iteration loop required storage to go negative before converging. The mass balance routine now converges via one of two possible approaches.

The first approach uses the negative range in the search for storage. In this approach users must append an additional row to the Elevation Volume Table and define a negative storage value. This approach is quite effective for convergence purposes and also gives valuable information if the solution ends up being in the negative range. If the storage solution is negative, RiverWare notifies users that the outflow is too great to be physically possible. For diagnostics purposes, this method also provides users with a measure of exactly how short the storage is.

If users do not want to specify negative storage values and do not want to allow negative storage values in the solution, a second approach to convergence is employed. When users do not append the Elevation Volume Table with a negative storage value RiverWare does not allow the search algorithm to go into the negative range. Instead, the algorithm uses storage = 0 whenever it is in the negative storage range. If the outflow is really too great to be physically possible, then the algorithm will keep iterating until it reaches maximum iterations. If this happens, then RiverWare does a final mass balance check at the storage = 0 point and informs the user that the outflow is too great and the run stops.

A warning was created on the Slope Power Reservoir to warn the user if the Pool Elevation slot was set to a value that is below the minimum pool elevation. If the dispatch method determines a pool elevation that is less than the minimum, the slot is first set to this value and then the warning is issued.

Within the Storage Reservoir, if an input Release value is greater than Max Release, a warning message is generated. The warning, “Input Release is greater than Max Release,” does not abort the run, however, users should check that input values are correct.

The Known Inflow slot name was changed to Hydrologic Inflow to better reflect the true content of the slot. Existing models that use the Known Inflow slot will be automatically updated to the Hydrologic Inflow slot the first time the model is saved.

A new method category called Regulation Discharge was added to the Control Point object. The methods in this category model the Southwest Division Army Corps of Engineers’ algorithms for calculating the maximum amount of flow that is allowed in the channel and the empty space available at the control point based on the state of the system. These methods are executed prior to flood control methods that can utilize the empty channel space. At the selection of any regulation discharge method, a method category for both Sag Operation and Regulation Recession appear. Selecting methods in these categories model additional algorithms that can alter the regulation discharge results. The regulation discharge methods are still in the testing phase and should not be used by anyone except the Army Corps of Engineers. However, they are designed to be generic so in the future they can be used by anyone who needs to model regulation discharge.

The Known Inflow slot name was changed to Deterministic Local Inflow to better reflect the true content of the slot. Existing models that use the Known Inflow slot will be automatically updated to the Deterministic Local Inflow slot the first time the model is saved.

The performance of models using RPL sets (rule based simulations and some accounting simulations) has been improved. Briefly, the changes responsible for the improvements were:

On several large benchmark models these changes improved the overall runtime by an average of greater than 30%.

Following is a brief description of a new rules palette expression available for use in the RiverWare Policy Language for writing rules.

The MAP LIST expression. This expression can replace the FOR expression in some situations and is typically much more efficient. In particular, the following pattern involving a FOR expression:

may be replaced with the following pattern involving a MAP LIST expression:

Example:

Evaluates to the list:

Following is a brief description of the new rules palette functions (Predefined Functions) available for use in the RiverWare Policy Language for writing rules. Details on the use of these functions and the syntax involved are available in the Rulebased Simulation documentation in the online help.

The RowLabel and ColumnLabel functions get the label associated with the row or column of a table slot.

The AccountNamesFromObjReleaseDestinationIntra function is the same as AccountNamesFromObjReleaseDestination function except that it only looks at transfer supplies, as opposed to outflow supplies.

Given a periodic slot and a date, the DatesInPeriod function returns an ordered list of dates representing the beginning time of each interval which begins in the specific period containing the input (reference) date.

Every periodic slot has a period associated with it, and this period is divided into intervals. Intervals are either regular (e.g., Days) or irregular (e.g., 8:00 July 3). One can map a period (divided into intervals) onto a timeline, leading to several specific periods (divided into specific intervals). For example, the period "Year" maps onto specific periods corresponding to each year, such as the specific period which is the year 2003.

Providing a reference date serves to indicate a specific period, and this function returns the dates corresponding to the beginning of each time interval which begins in that specific period.

The Split function takes two strings as argument, a primary and separator string, and returns a list of strings formed by representing the substrings of the primary string which are separated by the separator string. This function is case sensitive.

The Exp function takes two numeric arguments, an operand and an exponent, and returns the result of exponentiating the operand to the power given by the exponent. The return value is dimensionless (has no units).

The exponent is not restricted to being an integer (as with the "^" operator), but it is an error for the operand to have units.

The SumSlotSkipNaN and SumFlowsToVolumeSkipNaN are variations of the SumSlot and SumFlowsToVolume which treat NaN’s as zeroes.

The FlattenList function takes a list and replaces any lists contained within that list with the individual items in those lists.

The ToCelsius, ToFahrenheit, and ToKelvin functions convert a value in one temperature scale to another scale.

The RplUnit temperature dimension has been expanded to three dimensions, corresponding to the following three temperature scales: Kelvin, Celsius, and Fahrenheit. Up until now we had a single temperature dimension, but this was not adequate for representing units such as "m/F". However, more work remains to be done to fully support operations involving temperature. In particular, we need to provide a more convenient mechanism for allowing users to guarantee that values read from the workspace have units with a particular scale.

A new diagnostics category “Hypothetical Simulation” has been created to issue informative diagnostics during the execution of a RPL hypothetical simulation function. The category can be toggled on within the Rulebased Simulation Diagnostics Settings dialog box. Diagnostic messages are posted during the execution of any one of the five hypothetical simulation function methods. Among other messages, the diagnostics indicate the range over which a hypothetical simulation is occurring. All Hypothetical Simulation diagnostics messages are prepended with the string “HypSim”.

A new function diagnostics category, Function Execution, has been added to the Rulebased Simulation Diagnostic Settings. This diagnostic category allows function diagnostics to be toggled on and off independent of rule execution diagnostics.

A Rules Analysis dialog was added to RiverWare. The analysis dialog provides a list of Rpl objects (Rules, Functions, Groups) of ruleset and provides a mechanism to view various characteristics of those Rpl Objects. For example, the analysis dialog can be used to examine static features like the orphaned functions of a ruleset. The analysis dialog can also be used examine dynamic features like the evaluation time of the each Rpl object.

The ability to instrument the evaluation time of functions and rules has been added to Rulebased Simulation. By selecting the "Enable Rules Performance Analysis" toggle in the Simulation Run Parameters dialog, which accessed through the Run Control dialog, the rule-based evaluation instrumentation is enabled. This instrumentation will track the CPU time spent during evaluation/execution and number of evaluations of each function and rule. This instrumentation itself does consume CPU time, so it should only be used for debugging purposes. The results of instrumentation can be viewed in the new Rules Analysis List dialog.

New menu options have been added to the Ruleset Editor and the Group Editor to enable/disable pre/post diagnostics in all functions in the ruleset/group.

Users can now plot accounting slots from the Edit Account dialog box by selecting a slot display column (by selecting the column header or any cell value) and selecting the "File >> Plot Slot..." menu operation. This brings up a plot dialog box. The user can plot many individual slots from a single account.

Users can now plot series data from the Object Account Summary dialog box. The data shown in that dialog box represents the sum of analogous slots across a set of Accounts on a single Engineering Object, with one slot type per display column. A plot for one Slot type is generated by selecting its display column (by clicking the column header or any cell value) and selecting the "File >> Plot Slot ..." menu operation. This brings up a Plot dialog box.

Only a single static plot can be generated for each Object Account Summary Dialog Box (i.e. one such plot for each Engineering Object). The plot is not updated when any of the Account Slot data which contributed to the sum changes. Performing a subsequent plot operation from the Object Account Summary dialog box replaces the previously generated plot.

A new warning has been added to insure that the first approximation point of a spill upper bound approximation is less than the initial value of elevation or storage (depending on which is used in the linearization). Previously, cases that would generate this warning would lead to an infeasible linear program.

Each constraint can now have conditions added to it by selecting a button in the constraint editor. The default is that no conditions are placed. The button options are no conditions, a condition expression, a time condition, or both. Both of these conditions appear as separate lines below the constraint.

The time condition specifies a range of valid model start times for the constraint in question to be valid. The range is specified as a pair of month/day entries. For example, a constraint used in the winter might have a time condition like "Nov 5 <= run start time <= Feb 15". These dates are editable.

The condition expression is built up from the expression editor. It should evaluate to true or false based on conditions known at the beginning of the run. The expressions use any of the following operators: <=, >=, =, <, or >. The left and/or right side of these expressions are linear expressions that would typically reference slots. Multiple conditions can be created by using the newly created “AND” and "OR" operators. As with other expressions, the expression editor will allow nonsensical expressions to be entered and the user has the responsibility of entering a reasonable expression. The new operators can in theory be used in formulating constraints and objectives as well, but there doesn’t seem to be any immediate practical benefit of doing so.

An example of a condition expression is:

“(((Boone.Pool Elevation[0] > 1600 "ft") OR (South Holston.Pool Elevation[-1] >

1700 "ft")) AND (AVG i FROM -4 TO -1, Watauga.Outflow[i] <= 100 "cfs"))”

Several technical changes were made to improve performance. The details are as follows.

Numerical stability was dramatically improved by keeping floating point numbers stored as doubles throughout optimization. Previously, some numbers were converted to text during formulation of the optimization problem.

Instead of adding constraints with a single variable, the bounds on that variable are adjusted, thus reducing the size of the linear program.

Diagnostic capability was enhanced by adding dumpSAV, dumpBAS, and dumpPRE functions. These functions generate respectively a binary CPLEX problem and basis file, a text basis file, and a presolve file.

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.