skip to main content
Release Notes Version 5.0
Release Notes Version 5.0
Special Attention Notes
Following are special attention notes, indicating that
• functionality has changed that requires the user to update models, or
• results may differ
If you have any questions, contact riverware-support@colorado.edu
Convergence
Checking Iterations when Convergence is None
Previously, if a slot had “None” specified as the convergence criteria, the iteration count was being skipped. This bug has been fixed and a convergence type of None will now result in the slot skipping the convergence check but max iterations will be checked. A possible implication of this fix is that some models which were not previously reaching their maximum iteration will now do so.
Convergence Type and Min/Max on Accounting Slots
On accounting slots (Account.Inflow, Account.Outflow), the convergence type will be set to Percent Change and only changes to the value will be permitted. In models created using previous versions of RiverWare, the convergence type will be changed on model load if they are not already Percent Change. Accounting supplies between two multislots (e.g. transfers in & out) will be changed to have a convergence of None and those between a series slot and a multislot will have the convergence of the series slot typically Percent Change. Also, there is no min/max checking done on account slots so this configuration option has been disabled.
With this change, many supplies now will have None as the convergence criteria. Even though the account solving will converge based on the convergence of the slots to which the supplies are propagated, rules that set supplies may fire more often as they will always reset the value, even if it is exactly the same. If this situation is occurring, users may need to modify some rule logic and should judiciously set the rules comparison tolerance “Setting Tolerance for Use in the Logical Comparison Operators” in RiverWare Policy Language (RPL) if they have not already done so.
Convergence Slot Name Change
On Reservoir objects the Convergence slot has been renamed Convergence Percentage. The new name was chosen as it is more descriptive of the slots purpose. The user will see a warning message when the model is first loaded. If this slot is used in RPL sets or DMIs, the user will need to update the RPL set or DMI with the new name.
Muskingum Cunge routing method
A bug was fixed in the Muskingum Cunge method where the Distributed Outflows were being written at the previous timestep. The Outflow to the reach was correct. This bug was fixed so that now the Distributed Outflows are written at the correct timestep. Users of this method will notice different results in the Distributed Outflows slot but the Outflow from the reach will be the same.
Old-style Optimization is no longer supported
In RiverWare 5.0, the original (Tcl-based) optimization is no longer supported. Now, only RPL-based optimization runs can be made.
Removed support of TCL functions in RPL
The RiverWare Policy Language (RPL) no longer supports Tool Command Language (TCL) user-defined functions. When the RPL set is loaded (the set can still be opened) and an enabled Tcl function is found, an error is issued: “RPL no longer supports Tcl functions. Please remove or disable the function.” Please convert any TCL functions into RPL functions.
General RiverWare
Data Object and Slot Descriptions
Description Tab Added
A tab was added to the Data Object to allow the user to provide a description of the object. See screenshot. Descriptions can be copied/pasted to/from the system clipboard or printed directly to a printer or file.When printed, all of the descriptions for the slots on the object are also printed. See “Description Tab” in User Interface for more information.
Description of Slots on Data Object
Any slot on a data object can now have a description as shown in the screenshot. This description is accessed from the View Add Description or View Show Description (if it already exists). Descriptions can be copied/pasted to/from the system clipboard or printed directly to a printer or file. See “Slot Descriptions” in User Interface for more information.
Diagnostics Manager Ported to Qt
The Diagnostics Manager and Diagnostics Configuration dialogs were re-implemented. The look and feel is the same as the previous windows but there are minor differences. See “Diagnostics” in Debugging and Analysis for documentation on the diagnostics interface.
File Loading
Dialogs modified
The following Load/Save file choosers were improved for better functionality:
• Load Model File
• Save Model File As
• Open RBS Ruleset / Open and Load
• Open Optimization Ruleset / Open and Load
In particular, the dialogs are now re-sizable and on Windows there is a toolbar on the left side with buttons to common locations like Desktop, My Recent Documents, and My Computer.
Tip:  The My Recent Documents links is especially useful as it provides a history of models and directories that have been used. Once you select My Recent Documents, you may need to sort the column by clicking on Date Modified to see the more recently edited docs.
A default file extension filtering was added. The user can filter model files by:
• *mdl, *.mdl.gz *.rw and *.rw.gz (default)
• gzip Files (*.gz)
• All *
For RPL sets, the filters include
• RuleSet files (*.rls, *.rls.gz)
• gzip files (*.gz)
• All (*)
In addition, the user can use asterisks (*) as wildcards in the File name to further filter by file types.
Tip:  With this default filtering, it becomes even more convenient to use one of these extensions when naming models and rulesets
See “Loading Models” in User Interface for more information.
Re-open Model or Ruleset from File menu
Menu options were added to allow the user to “Reopen” files. These options allow the user to re-open commonly used files saving the user a step locating the file. See “Reloading Models” in User Interface for more information. This option was added to the following:
• Model Files: On the File menus on the RiverWare workspace, a menu was added to allow the user to Reopen Model.
• Rulesets: From the Policy Ruleset, and Policy Optimization Ruleset menus on the RiverWare workspace, menus were added to allow the user to Reopen or Reopen and Load a ruleset.
• SCTs: From the main Workspace Utilities SCT menu, options were added to allow the user to Reopen an SCT. This menu also exists on the SCT’s File menu.
Import/Export
Export/Import of Links, Accounts and Supplies
When exporting objects, the user is now able to specify that links, accounts and/or supplies are to be included in the action.
Import Object Location
The object import behavior now places objects at their original locations (coordinates) on the workspace. When objects are imported they become the new workspace selection and at least one of the objects is scrolled into view. The user can then move all the objects or use the Subbasin Manager dialog to easily define a new subbasin containing all of the selected objects. This allows the user to more permanently associate imported objects with each other. Also, when importing objects, RiverWare now includes the accounting system coordinates. Previously these were only included when saving a model file.
Import Paste Slot Data
Import Paste was implemented in the standard Slot dialogs, supporting copying from an external tabular data application (e.g. Microsoft Excel) into RiverWare slots. This is supported for all Series Slots and Table Slots, including Periodic Slots. See “Import Paste” in User Interface for more information.
Link Editor
The link editor was re-implemented for better usability and functionality. It now shows existing links in a tree-view layout. Links can be created or deleted directly from this dialog. See “Link Editor” in Model Building Quick Start for more information.
Tip:  Quick links, using the right mouse, select the workspace, is still the quickest way to create or delete links.
Performance
File loading of compressed files
A better model file loading mechanism was implemented to speed up the loading of gzip compressed files on Windows. File load time should be increased by approximately 20%.
Run Length Encoding
The model file format has been modified to use run-length encoding where possible for flags and data. To maximize the ability to use this encoding for flags, the flags series is written out separately from the data series. Small model files might get slightly larger, but most large model files will get smaller especially if they are large in the number of timesteps.
Plotting
Date Display Marker
When enabled, an automatic red vertical marker line is shown at the date displayed in the date time spinner in the toolbar. The user enables/disables this marker using a button next to the date scroll spinner. Note, the marker line can be used when a Global Time Scroll operation occurs. Global Time Scroll operations synch all dialogs to the selected date. It can be selected from the right-click context menu on slots and plots.
Multi-layout Plots
Multi-layout plots (2x2, 3x2, 3X3, etc) now plot better and fit on the screen.
Periodic Slot Plotting
Plotting of periodic slots was enhanced so that values at the begin time and end time of the specified plot time range are plotted, as well as any points defined in the periodic slot that fall into the plot time range. This ensures that the periodic slot line is plotted even if no defined points in the periodic slot fall into the plot time range, and also ensures that in the case where defined periodic slot points fall into the time range, that the periodic slot line is plotted from the full left side to the right side of the graph instead of being cut off at defined periodic slot points.
Probability Scale
A true probability scale was added to plotting in RiverWare. When exceedence percent values from a statistical slot are graphed from the open slot or open object dialogs, they will automatically be plotted with the true probability scale. This scale has 50% as the center line, and the scale gradations go symmetrically and irregularly (using probability scale) outward to values approaching 0 and 100 as seen on normal probability paper. This replaces the “faux” scale that was previously implemented to plot standard normal variables. See “Plotting a Statistical Table Slot” in User Interface for more information.
Time Labeling
Better time labeling was added to plots that displaying time. Ticks are now generated that are more appropriate to the range of time being shown. Instead of the random date labeling in previous releases, the new labeling chooses beginning of years, months, days or hours, as appropriate, for ticks and labeling. Also, the plot labeling was changed so that ticks on the time scale are marked and labeled at the beginning of day (hour 00:00) instead of in the middle of the day (hour 12:00). Time labeling is now automatic; the user is not able to select the number of tick marks or select that it is logarithmic. The user can still configure the time axis limits.
Run Analysis
Buttons were added to the Run Analysis dialog to allow the user to move objects up or down in the list. This allows the user to re-order objects by Custom, Name, Position, or Type.
Selector
Account Priority data
A filter was added to the selector to allow the user to select accounts by priority date. Two options were added: Junior To date and Senior To date.
Slot Type Filter
The Slot Type filter can be set to show only Scalar Slots and 1x1 Table Slots. This is useful in the new Slot Lists on the new SCT Tabs (“Scalar and Other Slots tabs”) -- both Scalar Slots and 1x1 Tables are shown within the same list.
Scalar Values
The selector dialogs were improved to now show Scalar Slot values in the column when the Slot Type Filter is set to “Scalar and 1X1 Table”. This allows the user to see the value of the slot when making selections.
Slots
Column widths
On the open slot dialog, the “Fit/Grow” column-width adjustment operations were improved to take into account the increased width of “bolded” header text, used to indicate selected columns.
Convergence
On the Configure Slot dialog, the display of convergence types Absolute, Unit Percent, and Percent were re-labeled to better show their meaning. In particular, if the Absolute or Unit Percent is chosen, the unit that is to be used is now shown in the dialog. Documentation of the convergence criteria was added “Configure Slot Dialog” in User Interface.
Global Slot Configuration Dialog
A global slot configuration dialog called Configure Existing Slots was added. This dialog is accessed from the Workspace Slots Configure Slots and allows the user to select one or more slots (using the selector) and configure all or selected slots. Configuration options include: User Units, Display Format, Convergence, and Unit Type for Slots on Data Objects. See “Global Slot Configuration” in User Interface for more information.
Integer Indexed Series Slots
Users can now add Integer Indexed Series and Agg Series slots to Data Objects. These slots behave like timeseries but are indexed by integer (1, 2, 3, ...) instead of date. These slots were implemented to work with the Iterative Mode of Multiple Run Management (i.e. each value in the slot represents a run) but can be useful for other purposes. More information on integer indexed series can be found here “Integer-indexed Series and Agg Series Slots” in User Interface. More information on iterative mode of MRM can be found “Iterative Mode Configuration”.
Periodic Slot re-implementation
The periodic slot dialog was re-implemented to be more similar to other slots. The user can now do the same actions that are available on other slots like:
• Multiple-Cell editing
• Multiple cell Copy and Paste operations, including Export Copy
• Import Paste (to and from the system clipboard)
• Fill Values Below (with value of the selected cell)
• Replace NaNs Below (with value of the selected cell)
• Interpolate vertically between the values of two selected cells, or a range of selected cells
• Adjust Values (of an arbitrary selection of cells)
• Column Sum Row (optionally shown as the bottom row)
• User Supplied Text Descriptions (on Periodic Slots on Data Objects)
• Column width Adjust Operations (five different operations)
Series Display Compression
The compression of series slots feature has been added. See “Series Display Compression” in User Interface for more information. This display feature allows the user to filter the data that is shown. The filtering options include:
• Compress Repeated Values (shown to the right)
• Hide NaN Values
• Hide Value: 0 (or other user defined value)
• Hide NaNs and Value: 0 (or other user defined value)
• Show Values: 0 (or other user defined value)
• Show NaNs and Values: 0 (or other user defined value)
• Show Values <= 0 (or other user defined value)
• Show Values >= 0 (or other user defined value)
When deciding if a value should be shown or not. The utility uses the selected Precision Type. Precision Types may be set to one of the following options:
• Display
• Convergence
• Exact
Slot Configuration
On the Configure Slot and slot Configure Timeseries dialog, the Object, Slot, and Account (where applicable) is now more clearly indicated. Also, on the Configure Timeseries, there is now a button to allow the user to show the Run Period (and the Accounting Period for accounting slots).
Slot Order
On open objects, the user can now initialize the custom order from any of the automatic sort orders: Object Name, Object type, or Object Icon Position (vertical, on Simulation canvas). The Up and Down icon buttons can then be used to further customize the slot order. See “Sorting Slots” in User Interface
Statistical Slots
The statistical slots were modified to :
• display partial duration frequency functions (min and max)
• display value duration frequency functions (min, max, and avg)
• display fully specified date column where applicable
• allow a different frequency calculation method
• add an option to plot all data columns of value duration results.
Snapshot Manager
The Snapshot Manager dialog was re-implemented and enhanced. See “Snapshots” in Output Utilities and Data Visualization for more information. Highlights include:
• New columns have been added to display the number of slots contained within the snapshot and a timestamp indicated the date and time when the snapshot was created.
• A variety of slot order options have been added to the Snapshot Manager dialog including up and down arrow buttons and a Sort pull down menu. The typical cut, copy, paste, remove, select all, invert selection, and add slots menu items are available within the Slots pull down menu.
• Removing a Slot from the Snapshot slot list will not remove it from previously created Snapshot Objects. Nor will deleting the original Slot (e.g. an original Slot on a Data Object)
Software Technology Changes
The 5.0 release is a major milestone in RiverWare development. After many years of removing dialogs that use the “Galaxy” graphical user interface support library, all Galaxy dialogs have been replaced and Galaxy is no longer used by RiverWare.
Following is complete list of major software technology changes that have been implemented in RiverWare 5.0:
• Completed removal of the “Galaxy” GUI support library. This has been replaced by Qt.
• Began the port from (Trolltech) Qt3 to Qt4 using the Qt3-Compatibility support library.
• Completed port of Qwt (plotting package) from version 0 to version 5.
• Upgraded the Tool Command Language (TCL) used for model saving and loading from version 8.3 to version 8.5.
Subbasin Manager
The Subbasin Manager dialog has been re-implemented. It is now divided into three tabs which represent the User Defined subbasins, Automatic subbasins, and Object Membership of subbasins. On the Object Membership tab the user selects an object and subbasins containing this object are then shown in the list below along with the number of objects within the subbasins and the type of the subbasins. The subbasin list may be expanded in tree view to show all the objects contained within each subbasin on the list. This dialog now provides better support for re-organizing the list of subbasins and opening subbasins directly from the manager. For more information, see “Subbasin Manager” in User Interface.
Units
Unit Converter
The Unit Converter was re-implemented. See “Unit Converter Dialog” in User Interface for more information. Now there is better support for varying timesteps (i.e. months and year). The user can select the length of the month or year to use (where applicable). Also, there are quick buttons for the common unit types Flow, Volume, Area, and Length. Also, calculations are automatic; hitting enter is not necessary.
New Units
The following units were added to the units file. Additional units can be defined by the user in the “units” file in the RiverWare installation directory.
• m3/month: RiverWare displays it as m3/month.
• m3/year: RiverWare displays it as m3/year.
Workspace - Canvas Selection
The selected Workspace Canvas (Simulation or Accounting) is now saved in the RiverWare model file and the model is automatically opened to that view. Now, if you close a model with the accounting view shown, it will re-open to the accounting canvas.
Accounting
Exchange Manager and Exchange Configuration dialogs ported to Qt
The Exchange Manager dialog and Exchange Configuration dialogs were re-implemented. The Exchange Configuration dialog no longer has tabs, all of the data can be seen at once. See “Exchange User Interface” in Accounting for more information.
Import/Export of Accounting Supplies
Import and export of objects now allows supplies to be imported/exported as well. When objects are exported, accounts and supplies are optionally exported based on user selection. Note that supplies cannot be exported unless Accounts and Links are also exported. If only a subset of a model is selected, links and supplies may be broken.
When importing objects which already exist on the workspace, the imported objects are renamed. RiverWare now does the same for supplies located on these objects. If the supply name is a duplicate, the import mechanism will assign the string DUPL to the end of the new name. In addition, if the imported supply has a Release Type or Destination that does not already exist, RiverWare will add the supply’s release or destination type to the accounting system configuration. Similarly with imported Accounts, if the Water Type or Water Owner does not exist in the importing model, it will be created.
Slots
Instream Flow Account
The “Available Natural Flow” slot on the Instream Flow Account was changed to “Available Allocatable Flow.” This slot is available when you have a priority date or water rights method selected.
Convergence Type and Min/Max on Accounting Slots
On Accounting slots (Account.Inflow, Account.Outflow), the convergence type will be set to Percent Change and only changes to the value will be permitted. In models created using previous versions of RiverWare, the convergence type will be changed on model load if they are not already Percent Change. Accounting supplies between two multislots (e.g. transfers in & out) will be changed to have a convergence of None and those between a series slot and a multislot will have the convergence of the series slot typically Percent Change. Also, there is no min/max checking done on account slots so this configuration option has been disabled.
With this change, many supplies now will have None as the convergence criteria. Even though the account solving will converge based on the convergence of the slots to which the supplies are propagated, rules that set supplies may fire more often as they will always reset the value, even if it is exactly the same. If this situation is occurring, users may need to modify some rule logic and should judiciously set the rules comparison tolerance “Setting Tolerance for Use in the Logical Comparison Operators” in RiverWare Policy Language (RPL) if they have not already done so.
Slot Configuration
On the Configure Slot and slot Configure Timeseries dialog, the Object, Slot, and Account is now more clearly indicated. Also, on the Configure Timeseries dialog for accounting slots, there is now a button to allow the user to Synch with Accounting Period and a button to Show the Run Period and the Accounting Period.
Water Rights Allocation
Account Subordination
The predefined function SolveWaterRights (and the new SolveWaterRightsWithLags) now includes the ability to model subordination of water rights. The user defines this subordination through method selections on the dominant account. See “Computing Appropriation with Subordination” in Accounting for more information.
Account Subordination Viewer
A dialog was added to the accounting system to display accounts that are Subordinate or Dominate to one another. This is used in a water rights model using the SolveWaterRight predefined function to allocate water based on priority dates with subordination. See “Using Diagnostics with the Solvers” in Accounting for more information.
Disaggregation of Initial requests from Annual Values
In the previous version of RiverWare, the method category Account Initial Request Calculation on Computational Subbasins (“Account Initial Request” in Objects and Methods) had the following methods and dependencies:
• Daily Timestep instantiated the following periodic slots:
– Daily Demand Coefficients
– Daily Leap year Demand Coefficients
• Monthly Timestep instantiated the following periodic slots:
– Daily Demand Coefficients
– Daily Leap year Demand Coefficients.
These methods and dependent slots have been replaced with following:
• Periodic Coefficients now instantiates:
– Daily Demand Coefficients
– Daily Leap year Demand Coefficients
– Monthly Demand Coefficients
– Monthly Leap year Demand Coefficients
• Series Coefficients now instantiates:
– Daily Demand Coefficient Series
– Monthly Demand Coefficient Series
The Series Coefficients methods will use series slots to find the multipliers for determining per-timestep demands on the accounts rather than using periodic slots. Having two different methods and associated series slots allows each of the slots to be input once and saved in the model file, and they will remain across timestep-size changes to the model. Note that it is not be possible to set up a model to use the periodic slot for the monthly run and the series slot for the daily run without user intervention (changing this method selection) when switching run timestep sizes.
Fill Conservation Pool and Meet Diversions from Storage Accounts
The new method, Fill Conservation Pool with Diversions, was added to the Storage Account method category Calculation of Initial Request. This method will compute the amount required to fill the conservation pool (as with the Fill Conservation Pool method) and to that amount it will add the total demands of the prioritized water accounts that divert from the storage account directly. See “Fill Conservation Pool” in Accounting for more information.
Percentage of Total Requirement to Meet Demand on Storage Accounts
A new category and methods have been added to determine whether a fill factor will be used, and if so, the form that it will take. This new category is to be used with Fill Conservation Pool and Fill Conservation Pool with Diversions methods. The new Storage Account method category Cons Pool Fill Factor contains the following methods: None, Fill Factor is Series, and Fill Factor is Scalar. The last two methods have the dependent Fill Factor slots associated with them. See “Conservation Pool Fill Factor” in Accounting here for more information.
Priority Slot on acct is recalculated when date is changed
If the Priority Date is changed on an account, the Priority scalar slot for all accounts are re-calculated based on the new date. This allows the user to immediately see the effect of changing a Priority Date.
Results of Turning Off a Water Right
When a Water Right is turned off (has no priority date), it does not automatically deselect “dependent” methods. There is no such thing as dependent methods on accounts, so all methods and their data are maintained.
SolveWaterRightsWithLags
A new predefined function SolveWaterRightsWithLags was added to allow the water rights allocation functionality to compute allocations when there are lags involved in the solution. See “The SolveWaterRights() and SolveWaterRightsWithLags() Rules Functions” in Accounting for more information.
Database DMI
Database DMI editor
A new Database DMI editor dialog was created that provides one-dialog for configuration of fully functional DSS Database DMIs. It allows the user to specify all required configuration information and as much optional configuration information as is feasible. The real power of this dialog is that the user can see the fully specified information that will be sent to the DSS database.
This dialog is like an editable “view” into the Dataset Manager and Database DMI dialogs. Thus, the user can see what has already been configured in those dialogs but also make edits that will be applied to those pieces. It is important to note that if the user edits a dataset or Database DMI in the editor window, the user cannot also edit the individual components at the same time. See “Creating a Database DMI” in Data Management Interface (DMI) for more information.
HDB Datasets - User specified timeout value
For HDB datasets, a user specifiable dataset read/write timeout value was added. This value will override the client/server default value of 60 seconds. Only HDB datasets expose the value in the user interface.
Name Map Order
The user can now re-order name maps in the Name Map dialog. Previously, the maps were always listed by priority order. The user can switch between custom and priority order using the Display menu. In custom mode, the user can re-arrange name maps using the up and down arrows. For more information, see “Name Map Ordering and Priorities” in Data Management Interface (DMI).
No Units
The database DMI now allows slots whose unit type is NONE to be read or written, regardless of the availability of dataset or database units. If the slot unit type is NONE then no unit conversion is possible. This means users don't have to create datasets which specify the NONE unit for the purpose of reading or writing data for which no unit conversion is possible.
Table Series slots
The Database DMI functionality is now able to support Table Series Slot and Agg Series Slot columns. The slot selector was also improved to support the selection of these slots for this purpose. See “Selecting Slots” in User Interface for more information on selecting table series slot columns.
Multiple Run Management
Accounting Slots using DMIs
When using output DMIs with MRM, the account name is now written into the output file for accounting slots.
Iterative Mode Configuration
The Iterative Runs tab of the MRM configuration dialog was re-implemented to provide a more usable interface. In addition, a better rule selector was added. See “Iterative Runs” in Solution Approaches for more information.
MRM Output to RDF files
The same data can now be sent to multiple RDFs during an MRM run using the following syntax:
Object.Slot: file=filename1 file=filename2
Additionally, MRM can now output data that is not at the same timestep as the run. Within the MRM configuration dialog, the user can select the following options:
• Must match - the slots' timesteps must match; the first slot's timestep determines the file's timestep, subsequent slots' whose timesteps don't match are skipped.
• Use smallest - use the smallest timestep; for example, if monthly and yearly slots are configured for the file use a monthly timestep (and yearly slots will output 11 NaN followed by a value).
• Use largest - use the largest timestep; for example, if monthly and yearly slots are configured for the file use a yearly timestep (and monthly slots will output their December values).
For more information, see “Output” in Solution Approaches
Spaces in Control File paths
For some time now, in DMIs there is the option to allow spaces in paths in the control file. This ability has been extended to Output control files that are specified in the MRM configuration output tab.
Optimization
RPL Based Optimization
The RPL-based optimization controller is now the only optimization controller supported in RiverWare. The original (Tcl-based) optimization is no longer supported.
RPL-based optimization is a global solution that solves for the optimal solution across all timesteps. To contrast, Simulation and Rulebased simulation solve each timestep, marching forward in time. In RPL-based optimization, the user creates an optimization policy set, using the RiverWare Policy Language (RPL), that contains constraints and objectives. RiverWare uses this set along with mass balance and other physical constraints and approximations to create an optimization problem. The optimization problem is then solved by the CPLEX solver and the results are sent back to RiverWare. Note, a separate CPLEX license is still required.
A typical optimization model uses the following three steps:
1. Simulation run to determine the consequences of any inputs
1. RPL-based optimization run to solve the optimization problem
1. Rulebased simulation run that incorporates some of the optimal results and removes linearization errors. For example, one option is for the rules to return the optimal reservoir outflows to the workspace.
If you would like additional information on using this controller, contact riverware‑support@colorado.edu.
Documentation
Preliminary documents were added for optimization “Optimization Overview” in Optimization but the documents are still under development. In addition, documentation of the thermal object was added “User Methods” in Objects and Methods.
Optimization Run Parameters
The Set CPLEX and Goal Parameters was re-implemented and renamed the Set Optimization Solver Parameters. This dialog now provides a more user friendly tree-view of the parameters used in optimization.
RiverWare is shipped with two files, cplex.par and goals.par, which provide overrides for optimization parameter defaults. There was not an effective way for the user to make changes to these values that would take effect for future runs.
Now, when an optimization controller is selected RiverWare first looks for the files cplex.init.par and goals.init.par in the optimization directory (the value of the environment variable RIVERWARE_OPT_DIR or /tmp/opt-<user name> if that variable is not set). If a parameter override file is found there, it is used, otherwise it looks for the installed version of that file.
When the user changes parameter settings in the Optimization Parameters dialog, there is a toggle indicating whether or not they would like to save the changes to a file; if this is selected when changes are accepted by the user, the non-default parameter settings are written to the cplex.init.par and goals.init.par files in the optimization directory. Unless these files are removed or the optimization directory is moved, all subsequent optimization controllers will begin by reading these parameter settings
RiverWare Policy Language
RPL User Interface
Comments on Statements
Previously, comments could be added to RPL expression, but not RPL statements themselves (Assignment, Print, ForEach, etc...). Now the user can add comments to RPL statements using the Add Comment or Delete Comment buttons on the palette.
DateTime Support Changes
The RPL DateTime syntax was modified for a more compact notation for referencing the current timestep. The symbolic DateTime grammar was extended to support “t” for “current timestep”, “t-1” for “Previous Timestep”, and “t+1” for “Next Timestep”. In addition, numerics within the date/time string no longer require the unit of “Timestep”. For example, the DateTime notation “Start Timestep + 2 Timesteps” is now represented as “Start Timestep +2”. All DateTime are shown in this new format, the user can still type in the old format and they will be automatically converted.
Editing types in RPL Looping variables
Menu based entering of RPL types of looping variables (For, With, While) in RPL expressions has been provided. Users can now individually select and edit the type and name of a variable name declaration. To edit a type, the user double-clicks on the type, is presented with a pull-down menu listing all the RPL types, and the user selects one of these types. The user edits a name as they would a literal value. The inline editor prevents the user from entering invalid names. See “Data Types for Looping Variables” in RiverWare Policy Language (RPL) for more information.
Note:  Previously, it was possible to copy/paste a type/name pair together, now the type and name must be selected/copied/pasted individually.
Editing Values
Users no longer have to hit enter when editing literal values in RPL editors. Clicking the mouse outside of the edit field is considered completion of the edit.
Modified display of looping expressions
The display of the RPL FOR expression was modified from:
to:
This provides an explicit visual cue to what is done with the result of evaluating the body.
Also, the display of the WHILE expression was modified to:
Open and Load
When using the Open and Load command from the Policy menu RiverWare will now open the ruleset whether it is valid or not. Previously, if the selected ruleset was not valid RiverWare would post a message in the Diagnostic Output and not open the set. Now, RiverWare still posts the message but also open the set without loading it.
Policy Group Priority Range
The RPL list view in the RPL dialog has been modified to show the priority range for Policy Groups whose members are not currently visible. For example, in the screenshot, the group Big Res Rules contains rules 1-5 and the group Small Res Rules contains rules 8-11.
RPL Function Argument Editor
This dialog provides a structured interface to specifying the type and names of a RPL function's arguments. For example, in the screenshot, there are two existing arguments (OBJECT res, and DATETIME Date) and the user is configuring a third argument. The old way of specifying function arguments by entering them directly into the function editor is still supported.
RPL Value Inline Editor Changes
The RPL value inline editor now uses a pull-down menu which provides a history of previous edits within the dialog. This effects the editing of literal values within RPL expressions. As before, the user initiates the edit by double-clicking on the terminal expression they wish to edit (a value or an empty expression). This creates an inline editor which allows the user to edit the value in place. If an existing value is being edited, the editor is initialized with the text corresponding to that value, otherwise it is empty. This editor differs from the previous one in the following ways. At the right-hand side of the editor is a button which provides access to a menu containing the previous values entered in the dialog. There is also a popup menu (accessible by right-clicking within the editor) which provides basic editing operations such as copy and paste. See “Entering Values” in RiverWare Policy Language (RPL) for more information.
This means there are three ways to edit the contents of the inline editor.
• Type in a value,
• Select one of the values in the pull-down menu, or
• Use the editing operations (copy/paste) in the popup menu.
The user signals completion of editing by hitting Enter or by clicking somewhere outside of the inline editor. This closes the editor and replaces the originally selected expression with the entered value. As before, if the entered text is not valid the user is provided with a notification window and the expression reverts to its original value. The entered text is added to the list of values which will be accessible in the inline editors menu the next time a value is edited in the dialog whether it is valid or not. C
Tip:  This feature is useful when the user enters invalid text in a RPL expression. Previously the user would have to retype the entire input, with the new features, the user can simply select what was previously typed and correct any mistakes within the text entry.
TCL user-defined functions are no longer supporter
The RiverWare Policy Language (RPL) no longer supports Tool Command Language (TCL) user-defined functions. When the RPL set is loaded (the set can still be opened) and an enabled Tcl function is found, an error is issued: “RPL no longer supports Tcl functions. Please remove or disable the function.” Please convert any TCL functions into RPL functions.
RPL Palette
NanToZero Operator
A NanToZero operator was added to the RPL Palette. This operator has a single numeric sub-expression; that sub-expression is a lookup of an invalid value (NaN), then NaNToZero evaluates to 0.0 in the units of the lookup slot. Otherwise it simply returns the value in the lookup slot, unchanged. This operator provides a simple and efficient way to treat a missing slot value as zero, a common requirement of water accounting policy. This is only useful when the sub-expression is an object/slot lookup expression. See “Miscellaneous Buttons” in RiverWare Policy Language (RPL) for more information.
Tool Tips
Mouse-over tool tips were added for all palette buttons. These will help the user find the appropriate button without having to look in the help.
Predefined Functions
The following predefined functions were added or modified. If the user previously had a user-defined function of the same name, the user-defined function name will have to be changed or the set will not load
FloodControl
The FloodControl function executes the selected flood control method on the computational subbasin and returns slots and values to set on those slots. Now, the function also returns the Target Balance Level is and its value. The Target Balance Level stores what was previously shown on the Temp Balance Level slot. See “FloodControl” in RiverWare Policy Language (RPL) for more information.
GetAccountFromSlot
GetAccountFromSlot(SLOT slot) predefined function has been added to the RiverWare Policy Language. Given a Slot, the function return its parent account name as a String. It is an error if the slot is not on an account. See “GetAccountFromSlot” in RiverWare Policy Language (RPL) for more information.
GetObjectFromSlot Function
GetObjectFromSlot(SLOT slot) predefined function has been added to the RiverWare Policy Language. Given a Slot, the function return its parent Object. The slot must either be on a Simulation Object or an account, otherwise it is an error. See “GetObjectFromSlot” in RiverWare Policy Language (RPL) for more information.
GetRowIndexByDate Function
GetRowIndexByDate(SLOT slot, DATETIME date) predefined function has been added to the RiverWare Policy Language. Given a slot with rows indexed by date, this function returns the 0-based numeric index corresponding to a given date. The value -1 is returned if the given date is not within the date range of the slot. This function is applicable to the following types of slots: Series Slot, Table Series Slot, and Periodic Slot. It is considered an error if the slot is not indexed by date. See “GetRowIndexByDate” in RiverWare Policy Language (RPL) for more information.
GetSlotName Function
GetSlotName (SLOT slot) predefined function has been added to the RiverWare Policy Language. Given a SLOT, return the slot name portion of the full name as a String. See “GetSlotName” in RiverWare Policy Language (RPL) for more information.
HasRuleFiredSuccessfully Function
The RPL predefined function HasRuleFiredSuccessfully now accepts the string “Current Rule” as a reference to the currently executing rule (block). This prevents the user from having to type in the full name of the rule and edit the name each time the rule name changes. See “HasRuleFiredSuccessfully” in RiverWare Policy Language (RPL) for more information.
HydropowerRelease
The HydropowerRelease function determines the releases to meet an energy demand or load. If the Seasonal Load Time method is selected on a reservoir, the HydropowerRelease now also returns the Load slot and value to set on that slot. See “HydropowerRelease” in RiverWare Policy Language (RPL) for more information.
Run Time Function
RunTime predefined function has been added to the RiverWare Policy Language. This function returns the number of seconds which have elapsed since the current run began, or if called from outside a run, the total number of seconds within the last run. This function is useful for analyzing performance. See “RunTime” in RiverWare Policy Language (RPL) for more information.
Slot Functions now work on Table Series Slots
The following functions take a slot and time range as input and either gets or sums values within a range on the slot. These were extended to work on Table Series Slots:
• GetSlotVals
• GetSlotValsByCol
• SumSlot
• SumSlotByColumn
• SumSlotSkipNaN
• SumSlotByColSkipNaN
• SumFlowsToVolumne
• SumFlowsToVolumeSkipNaN
• SumFlowsToVolumeByCol
• SumFlowsToVolumeBySkipNaN
RPL Set Analysis - Find Next Button
In the Search field, the “Find Next” button has been replaced with two simple arrow icon buttons, up-triangle and down-triangle to search forward or backward, respectively. In addition, pressing Return in the search box now searches forward.
Executing DMIs from Rules
When executing a DMI from a rule (using pre and post execution DMIs) it is no longer necessary to execute a DMI group. Now a rule can execute a single DMI directly.
SCT
Scalar and Other Slots tabs
A tabbed approach was added to the main SCT display area. The tabs are “Series Slots”, “Scalar Slots”, and “Other Slots”. The Series Slots tab, which is the conventional SCT data table, can contains all series slots and table series slots. The Scalar Slots tab can contain both scalar slots and 1x1 table slots. The user can change a single scalar value by editing the cell directly. Also, multiple scalar values can be edited directly from the SCT by selecting the slots and typing a new value in the toolbar. The Other Slots tab can contain all slot types which are not supported by the other tabs. See “Scalar and Other Slots Tabs: Slot Lists” in User Interface for more information.
SCT Column Width Adjustment
Column Width Adjustment toolbar buttons have been added to the SCT dialog. The available adjustment options include:
• Resize Columns: Set All to Selected Column Width
• Grow Columns: Fit Data
• Resize Columns: Fit Data
• Resize Columns: Fit All
Also, the “Fit/Grow” column-width adjustment operations were improved to take into account the increased width of “bolded” header text, used to indicate selected columns.
SCT configuration defaults
When a new SCT is created, it no longer aggregates timesteps by default. Also, if there is no default SCT defined, the warning message is not displayed anymore. The user can define the default SCT to aggregate if desired. For more information on the default SCT configurations click “Use the Default Configuration” in User Interface.
Supporting different timesteps
In the RiverWare 4.9, the user could create and use SCTs that have a different timestep than the current run step. Now the users now have two options for determining the range of the SCT (begin and end dates, timestep size):
• Relative to Run (the old way): the range and timestep default to that of the run when the SCT is created. The user can specify the number of pre- or post-run timesteps to view in addition to those within the run. They can also override the timestep of the run and specify a different timestep.
• Based on Slot ranges: the timestep is determined from the first slot added to the SCT, the range is maintained to be the minimal range which includes all the ranges of the member slots.
A new toggle was added to the General tab: Always Synchronize to Slots which engages the Based on Slot range mode described above.
Simulation Objects
Computational Subbasin
Changes to Flood Control algorithm
The Operating Levels Balancing Flood Control algorithm has been modified to better deal with tandem reservoirs and when they can store. This was done to prevent situations where the upstream reservoir is making releases to be stored in a downstream reservoir which is surcharging and there is downstream flooding. The downstream reservoir can now only store either in the conservation pool or through tandem balancing when the downstream reservoir is not surcharging at the current controller timestep. This check does not affect flood releases that are being passed through because there is space downstream. That will still happen even if the downstream reservoir is surcharging. More information can be found “Operating Level Balancing” in Objects and Methods.
Initialize Flow Slots for Routing
A new category was added to the computational subbasin called Initialize Flow Slots for Routing. This category contains methods that are used to initialize slots that are required to be known for routing to solve at the start timestep. It searches throughout the subbasin to determine the earliest pre-simulation timestep at which data must be known for each object to solve at the start timestep. It sets values in these slots at pre-simulation timesteps according to the selected method. There are three methods: the default, no-action No Method, Backcast Zeros and Backcast Initial Value. More information can be found “Initialize Flow Slots for Routing” in Objects and Methods.
RiverWare - MODFLOW Link
A dynamic link between RiverWare and MODFLOW 2000 was added. This link allows the user to model the interaction between surface water in RiverWare and shallow groundwater in MODFLOW. In RiverWare, the user specifies the RiverWare objects and MODFLOW cells or segments involved in data exchange using the Computational Subbasin object. The Computational Subbasin displays cell by cell values for exchanged data. Then, the Reach, Water User, Aggregate Diversion Site, and GroundWater Storage objects each contain methods that, when selected, allow an object’s data to be exchanged with MODFLOW. During a run, the two models run in parallel, exchanging data (seepage, heads, stages, return flows, etc) at each RiverWare timestep / MODFLOW stress period. Note, the RiverWare timestep must match the MODFLOW stress period.
More information on this connection can be found “RiverWare / MODFLOW Connection” in Objects and Methods along with links to each of the relevant RiverWare objects involved in the data exchange.
Reservoirs Only Method
The Reservoirs Only method was added to the Reservoir Boundary for Incremental category on the subbasin. This method allows users to set up a subbasin of only headwater reservoirs. They then can input cumulative locals and the method will copy these to the forecast slot. This allows consistent data input across all reservoirs that disaggregate local inflows. More information can be found “Reservoirs Only” in Objects and Methods.
Control Point
Hydropower Flooding Exception Category
The Hydropower Flooding Exception category was added to the control points with two methods: No Method (default) and Flooding Does Not Constrain Hydropower Releases. The No Method method is the previous behavior. Any proposed hydropower releases (calculated by the HydropowerReleases predefined function) would be cut back by any additional flooding at each downstream control point. The method, Flooding Does Not Constrain Hydropower Releases, excepts the given control point so that flooding is allowed at that control point due to hydropower releases only. More information can be found “Flooding Exception” in Objects and Methods.
Regulation Discharge Methods
The slots, Level Regulation Parameter and Percent Full Regulation Parameter were added to the control point dependent on selection of a regulation discharge method. These output slots provide the user with the parameter or level that was used in the regulation discharge calculation. The appropriate slot is set from the regulation discharge method which is executed from the dispatch method. More information can be found “Regulation Discharge” in Objects and Methods.
Reach
Local Inflow Adjust
It is no longer require that Local Inflow Adjust be input on the reach if dispatching before the start of the run with the solveNRLocalInflow method. Local Inflow Adjust now defaults to 0.0 in this condition. This is consistent with the rest of the methods as this slot is filled with zeros at the beginning of the run (for the run range only).
Muskingum Cunge Improved Method
The Muskingum Cunge Improved method is a new routing method on the Reach object. The new method is a modification to the MuskingumCungeRouting method but is designed to better conserve mass. More information can be found “Muskingum-Cunge Improved” in Objects and Methods.
Muskingum Cunge routing method
A bug was fixed in the Muskingum Cunge method where the Distributed Outflows were being written at the previous timestep. The Outflow to the reach was correct. This bug was fixed so that now the Distributed Outflows are written at the correct timestep. Users of this method will notice different results in the Distributed Outflows slot but the Outflow from the reach will be the same.
Periodic GainLoss Method
A new Periodic GainLoss method was added to the Reach object. This method is used to model gain and/or loss in a reach. The gain and loss values are entered as periodic data for a given time range. Gains are entered as positive values and losses are entered as negative values. This method will be available for all routing methods except Time Lag Routing. More information can be found “Periodic Gain Loss” in Objects and Methods.
Reservoirs
Operating Level Balancing Flood Control
The Target Balance Level slot was added and the Temp Balance Level slot was removed from the reservoir’s Operating Level Balancing flood control method. Now, the Target Balance Level is returned from the FloodControl function and set from the rule. The Target Balance Level stores what was previously shown on the Temp Balance Level slot
Peak Power Eqn With Off Peak Spill
The slots Dump Energy, Operation Factor, and Thermal Purchase were added to the Load Calculation methods on the Reservoir. These slots are output values describing how much power was produced compared to the desired Load. Dump Energy, Operation Factor, and Thermal Purchase are calculated at the end of the Peak Power Eqn with Off Peak Spill method unless the Seasonal Load Time method is selected. In that case, Dump Energy and Thermal Purchase are calculated at the end of timestep as the Load is not yet known. But, Operation Factor is always calculated at the end of that power method.
Seasonal Load Time method
In the Seasonal Load Time method, the Load slot was added. Now, when the HydropowerRelease function is called, the Load is also returned to the calling rule.
Water User and Agg Diversion Site Objects
Dispatch method required knowns
The dispatch method names were changed from
• solveStandAlone_givenDivReqDepReq to solveStandAlone_GivenDivReq - “Solve given Diversion Requested” in Objects and Methods
• solveSequential_givenDivReqDepReq to solveSequential_givenDivReq - “Solve Sequential given Diversion Requested” in Objects and Methods
Depletion Requested is no longer a required known for these methods. If Depletion Requested is not specified, the local variable will be set equal to Diversion Requested but the Depletion Requested slot will not be set. Also, Depletion Shortage will not be calculated.
Tip:  With this change, in rulebased simulation, the user no longer has to set Depletion Requested with a rule in order for the Water User to dispatch.
Sequential Structure Modifications
On the water user element on an AggDiversionSite (when set to be sequential), the Outgoing Available Water now does not include the groundwater return flow. Groundwater return flow goes into the ground and is either lost or linked to another object. Therefore the new approach sets the Outgoing Available Water equal to surface water return flow only.
On the AggDiversionSite, sequential set up, the slot Total Surface Return Flow is currently set up to sum the element’s Surface Return Flow. This is incorrect or not-meaningful as downstream elements can use leftover Surface Return Flow. It has been changed to set the Total Surface return Flow equal to the last element’s Surface Return Flow. This may not be the same as the Total Unused Water. Total Unused Water can include water that was not diverted by the last element. The last element’s Surface Return Flow is only the portion of water that was diverted that it returned via the surface. See “Sequential Structure” in Objects and Methods for more information on the Sequential structure dispatch algorithm
Water Quality
Documentation
Documentation of the water quality system was added to the RiverWare help: “Water Quality Overview” in Water Quality.
Predictor Corrector Salt Model
The Predictor Corrector (given Inflow Salt Concentration) salt calculations on reservoirs now better handle situations where the reservoir runs out of water. When this occurs, the reservoir is treated like a reach and the salt concentration is set to a weighted salt average of the inflows to the reservoir. For more information, see “Solve Pred-Corr Salt Given In” in Water Quality.
In addition, the Simple Well-Mixed salinity dispatch methods no longer set diversion salt concentration equal to zero if diversion is zero. This was leading to unusual dispatching patterns. Now, if Diversion is zero, the concentration is non-zero but the Diversion Salt Mass will still be zero.
Closed Bug Reports
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.
 
517
674
676
697
852
1674
2096
2359
2659
2686
2874
3072
3083
3090
3377
3568
3583
3592
3684
3688
3763
3829
3953
3963
4215
4219
4232
4245
4253
4272
4275
4286
4289
4298
4300
4301
4304
4308
4310
4314
4316
4317
4319
4322
4324
4325
4326
4327
4329
4330
4331
4333
4334
4337
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4350
4352
4353
4354
4357
4359
4360
4362
4363
4364
4365
4366
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4385
4386
4388
4390
4392
4393
4394
4396
4397
4398
4399
4400
4401
4402
4403
4406
4407
4408
4410
4411
4416
4417
4419
4422
4423
4424
4426
4427
4428
4429
4430
4435
4436
4437
4438
4439
4440
4447
4448
4449
4450
4451
4452
4453
4454
4459
4460
4467
4468
4469
4472
4476
4477
4478
4479
4480
4482
4483
4485
4486
4487
4489
4490
4491
4492
4493
4494
4495
4496
4497
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4512
4514
4515
4516
4517
4519
4521
4522
4523
4524
4525
4530
4531
4532
4534
4535
4536
4537
4538
4539
4540
4541
4542
4545
4546
4548
4550
4553
4554
4556
4559
4560
4561
4564
4565
4566
4567
4568
4569
4570
4571
4572
4574
4575
 
 
Revised: 06/03/2019