skip to main content
Release Notes Version 4.3
Release Notes Version 4.3
Special Attention Notes
• If the text or graphics in this file are not clear, you may need to print this document. Resolution should improve on the printed page.
RiverWare for Windows 2000 and Windows XP
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:
Differences in RiverWare for Windows
• Middle-mouse features such as QuickLink or rearranging the rows in the run analysis dialog are activated with the combination (pressed in this order): Alt + right mouse button + left mouse button. In Windows, the mouse configuration can also be changed so that middle mouse button actions are executed with the right mouse button (this would avoid the awkward sequence mentioned above).
• QuickLink can also be activated using the right-mouse button.
• The Windows DMI executable can be a DOS batch file or any other windows executable that can be run directly from a command shell.
Problems/Bugs in RiverWare for Windows
• The Locator View window often gets in a bad state when you resize the main workspace.
• It is possible that the objects may get shifted off the workspace if the workspace window is resized in certain ways. In order to make the objects visible again, you must save the model then reload it. Reloading the model will shift the model so that all objects are visible on the workspace.
Saving Model Files and Rulesets
• When saving model files or ruleset files that you intend to move between windows and unix systems, always save with the .gz extension. This saves the model/ruleset in a binary format that is the same on windows and unix.
New Plotting
• RiverWare now uses the same integrated plotting tool for both the Windows and Solaris platforms. The plotting tool was developed at CADSWES using the new Qt GUI package. Detailed documentation of the new plot tool is included in the online help (not in this file). CADSWES is open to any suggestions or questions that you may have concerning the new plotting tool.
General RiverWare
New Open Object Dialog
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.
Note:  The old Open Object dialog can still be accessed for this release by setting the environment variable RW_USEOLDOPENOBJECT. This should only be used as a temporary workaround as the old Open Object dialog will be permanently removed in an upcoming release.
In addition to numerous bug fixes from the old Open Object dialog, some of the new enhancements in the dialog include:
• Extensive use of right-mouse-button context menus. Many functions are now available both from the dialog menubar and from context menus. Most items in the lists - slots, accounts, and aggregate elements - have their own context menus that are activated by right-clicking on an item in the list.
• Open and plot slots directly from the Engineering Methods view.
• Display slots for different controllers directly from the Open Object dialog without changing the controller in the Run Control Dialog. From the main dialog menubar select “View” “Show Slots for.”
• Reorder the slots in the “Engineering Slots” view. Slots can be ordered by selecting a slot and pressing the “Up” and “Down” buttons at the top of the slot list or, for non-aggregate objects, by clicking and dragging a slot within the list. The new custom slot order is automatically saved for the object. The slot order can also be saved to be applied to other objects of the same type by selecting “View” “Save Object-Type Slot Order.” All slot orders are saved in the model file.
• Sort the items in any of the lists - engineering slots, engineering methods, or accounts - by pressing a column in the header at the top of the listview. All lists can be sorted alphabetically ascending or descending by any column in the list. The engineering slots list can also be sorted by slot type, by the custom slot order for the specific object, or by the slot order saved for all objects of the given type.
• Aggregate objects now use the same Open Object dialog as non-aggregate objects.
Exporting a Slot Now Includes Comments
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.
Note:  The comment lines are intended for user convenience only. They are human readable only -- not "machine" readable. The exact format of these comment lines is not guaranteed, and could be changed in future releases.
Qt/Galaxy Integration (Solaris Only)
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.
Simulation Objects
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.
Reach Object
Impulse Response Routing for Seepage
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.
Known Inflow Slot Changed to Deterministic Local Inflow
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.
Distribution Canal
Impulse Response Routing for Seepage
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.
Reservoir Objects
New Reservoir Convergence Algorithm
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.
Changes to the Use of Minimum Power Elevation
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.
Convergence of Mass Balance Solve Storage Near Zero
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.
Minimum Pool Elevation Warning
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.
Max Release Warning
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.
Known Inflow Slot Changed to Hydrologic Inflow
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.
Control Point Object
Regulation Discharge Category
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.
Known Inflow Slot Changed to Deterministic Local Inflow
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.
Rulebased Simulation
Performance Improvements
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:
• RiverWare now caches a reference to the function accessed by each function call, saving the time required to look up the function by name.
• Some function argument error checking in done only once at the beginning of a run instead of every time the function call is evaluated.
• When diagnostics are disabled, we more thoroughly avoid spending time processing certain rule diagnostics.
• Symbols (references to variables and functions) are managed more efficiently during validation and execution.
On several large benchmark models these changes improved the overall runtime by an average of greater than 30%.
New Palette Expression
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:
FOR ( <type/name pair> IN <list expression> )
WITH LIST result = { } DO
APPEND <expression not involving result> ONTO result
may be replaced with the following pattern involving a MAP LIST expression:
MAPLIST ( <type/name pair> IN <list expression> ) DO
<expression not involving result>
x + 10
Evaluates to the list:
{ 11, 12 }
New Palette Functions
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.
RowLabel, ColumnLabel
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.
SumSlotSkipNaN, SumFlowsToVolumeSkipNaN
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.
ToCelsius, ToFahrenheit, ToKelvin
The ToCelsius, ToFahrenheit, and ToKelvin functions convert a value in one temperature scale to another scale.
Changes to Temperature Units
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.
New Rulebased Simulation Diagnostics Settings Categories
Hypothetical Simulation
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”.
Function Execution
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.
Rules Analysis List Dialog
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.
Rules Performance Analysis
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.
Function Diagnostics Menu Items
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.
Plotting Account Slots
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.
Plotting from Object Account Summary
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.
New Warning
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.
Conditional Constraints
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"))”
Performance Improvement and Numerical Stability
Several technical changes were made to improve performance. The details are as follows.
• Variables with redundant bounds were changed to infinite bounds to reduce unnecessary pivoting.
• The upper bounds on variables were changed to use optimization units instead of internal units to prevent "infinite" bounds (by CPLEX’s definition) from being translated to finite bounds.
• The setting of the algorithm was moved so that either a primal or dual algorithm can be used to solve a linear program. The algorithm selected is based on the type of goal.
• A new capability was added to detect slow progress in the LP and trigger both a fresh "presolve" and a restart with a fresh basis.
• A new and more efficient CPLEX function, CPXtightenbds, was used to instead of CPXchgbds where ever possible.
• Several CPLEX parameters were adjusted to improve performance based on conversion to CPLEX 8.0 and changes in TVA’s problems.
• Frequently, when RiverWare is generating internal variable names for CPLEX non-slot variables, the name is similar to the previous variable; code was added to retain the last name generated and to reuse it when possible.
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.
Bugs Fixed
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 and search our bug database. You will need a RiverWare user login and password.
Revised: 06/03/2019