skip to main content
Release Notes Version 5.2
Release Notes Version 5.2
Special Attention Notes
Following are special attention notes, indicating that
• functionality has changed that requires you to update models, or
• results may differ
If you have any questions, contact riverware-support@colorado.edu
Deprecated Expression Slots removed
Old-style expression slots are no longer supported in RiverWare 5.2. When loading a model and these slots are found, a message is posted and the slots are ignored (i.e. they are not loaded into the model).
Please see Special Attention Notes in the Prior Release Notes for information on finding and converting these slots using RiverWare 5.1.
Integer indexed slot display and synchronizing
Integer indexed slots are indexed by an integer instead of a timestep. Internally, these are stored as having an hourly timestep starting at Dec 31,1799. A bug (4797) was fixed where if a data object containing these slots was synchronized, the integer indexed series slots would also be synchronized to that new timestep and start/end date. Now, integer indexed slots will not be synchronized and any existing slots will be fixed on model load. If you had policy that referred to the timestep of these slots, it must be modified. Also, the display of these slots has been improved on the SCT cell values and summary statistics.
Series Slots converted to Periodic Slots
On the reservoirs, the following slots were converted from Series Slots to Periodic Slots:
• Irrigated Area Loss Rate
• K Factor
• Meadow Area Loss Rate
• Pan Ice Switch
When you first load your model, if you are using these slots, a series of warning message will be posted to diagnostics, for example:
“SLOT: Reservoir.K Factor: Trying to convert former slot type ("SeriesSlot") to new slot type ("PeriodicSlot")."
You must re-entered the data into these slots where applicable. This is especially true for the Pan Ice Switch; previously, the value would default to 0 if not input, now the value MUST be input. A single 0.0 in the periodic slot is sufficient if only 0 is required.
See “Storage Reservoir” for details.
Accounting
Data Object Exchange Utility
A specialized utility was added to the Accounting system to allow users to create an alternative mechanism to track water exchanged between accounts. In this approach, the user tracks the exchange with rules that reference specifically named slots on data objects. This utility, called the Data Object Exchange Builder, helps to create this type of exchange by adding slots to a data object and creating supplies on the workspace. The rules must be defined by the user and no support is provided as to what the rules do or how they are written.
More information on this utility can be found in the “Data Object Exchange Overview” section.
Diversion Account Enhancements
Return Flow Calculation - Variable Efficiency Return Flow
A new method was added to the Diversion Account’s Return Flow Calculation category. The Variable Efficiency Return Flow method computes the returnFlow by multiplying the Diversion by the minimum of the Max Efficiency or the ratio of Depletion Requested to Diversion. For more information on this method, see “Variable Efficiency Return Flow”.
Return Flow Route or Split
A new category, Return Flow Route or Split, was added to the Diversion Account. This category has two methods: Simple Lag and Split and Route. The default Simple Lag method (“Simple Lag”) uses the existing approach where the return flow can be lagged by an integer number of timesteps and no splitting of return flows is allowed. The Split and Route method (“Split and Route”) allows you to split the return flows to multiple supplies and then route those return flows using linear routing coefficients. Note, the Split and Route method cannot be used by a diversion account in a computational subbasin that performs a water rights allocation using the prior appropriation method and water rights solver.
Batch Mode and RCL
RCL specification of Machine\share paths
In RCL scripts, the file syntax did not allow the windows \\MachineName\shareName specification of paths. Now, an example of the correct syntax is:
OpenWorkspace \\\\MachineName\\shareName\\test.mdl.gz
Diagnostics
New Information on start up
An informational diagnostic is shown at start up which indicates which RiverWare Resource Database file (riverwareDB) is being used. If there is no riverwareDB file, a message is also posted.
Diagnostic window on Solaris
On Solaris, when a run aborts, the Diagnostics Output Window is no longer automatically set to be the active window but is still raised to the top.
DMI
Excel Database DMI Datasets
In the database DMI utility, an Excel Dataset was added to better allow you to interface with Excel. A database DMI can use an Excel dataset to import or export data directly from/to Excel. There are two main ways to specify how the data will be represented in Excel:
• Using Ranges and Name Maps: The user specifies Names Maps to correlate either Excel Named Ranges or Cell References to slots in RiverWare.
• Using Headers and Sheet Names: The user specifies that a standard Header naming convention will be used to correlate slots in RiverWare to data in Excel.
Within each of these two approaches, there are many user configurable options and features. See “Excel Datasets” in Data Management Interface (DMI) for more information.
Line enders
A new feature was added to the Control File-Executable type DMIs. This feature allows you to specify the line ending sequence that DMI's write. As specified in the DMI Editor, the choices are:
• Native (default for the current platform)
• Windows or
• Unix
RPL functions to specify Begin/End dates
For Database DMIs, you can now specify the slot selection’s Begin or End date with a RPL function defined in an opened Global Function Set. The function must not have any arguments and must return a fully specified datetime variable.
Status Dialog
A more informative status bar is now available during DMI execution. This dialog shows information on the DMI that is executing, the slots that it is processing and the location of the data. Because this dialog has minor impact on performance, especially when processing a large number of slots, it is optional and by default is not shown. This status dialog can be shown by toggling on the menu DMI Show Status Bar from the DMI Manager.
General RiverWare
RIVERWARE_HOME environment variables
On windows, the environment variable RIVERWARE_HOME_XX is optional for RiverWare to run. If it is not set, RiverWare will use the executable’s directory, i.e. it assumes RIVERWARE_HOME_XX is the location of riverware.exe. The directory used can be seen in the Help About RiverWare Show System Info... menu.
Multiple Run Management
Iterative Mode Output Control File
Iterative MRM no longer requires an output control file (although one can still be provided). Previously, even if no file was needed, a blank file was required.
Optimization
Constraints for Input Values
Previously, optimization was failing to use input values for some slots if the policy set didn't need the value either directly or indirectly. One noticeable example was pool elevation inputs for level power reservoirs.
Now, an input value leads to an expression, slot[t] = input value. This expression is forced into the model through the "linearization" process. The results depend on what happens to this expression during linearization. In the case of pool elevation, for example, the expression is replaced initially with an equivalent expression for storage and eventually reflected by setting the bounds on the storage variable equal to the appropriate value. A similar process is used for any slot replaced by substitution.
If instead, the slot is not replaced by this kind of substitution, then the original expression is introduced as a hard constraint. If the slot is linearized by a method other than substitution, the slot in the constraint will be replaced by a linear expression of other slots.
If the slot is not linearized, its defining constraints will be introduced, and the value will be used in those constraints.
If a slot is linked to another slot with an input value, this process is followed for both slots.
Slot minimum/maximum values are optional for decision slot variables that have a value. In the past, such variables would never be introduced, but now that they are linearizing expressions which contain variables with values, these variables exist.
Modified definitions
The Tailwater Base Value was added to the list of slots defined by certain optimization definitions.
Modified the substitution approximation code
When translating a constraint on one slot to a constraint on another slot, the original constraint value may lie outside of the table describing the slot relationship. The table may imply that the constraint cannot be satisfied. In this case, RiverWare now issues an error. Alternatively, the table may imply that the constraint is always satisfied. In this case, RiverWare now issues a warning that alerts the user that the table may be missing values.
Forward lags
When the code encounters the variable s[t] where s is the reach Inflow or Local Inflow slot, in theory, it should write an equation like:
(1) Reach.Outflow[t+Lag] = Reach.Inflow[t] + Reach.Local Inflow[t]
Prior to now, it would write the equation:
(2) Reach.Outflow[t] = Reach.Inflow[t-Lag] + Reach.Local Inflow[t-Lag]
which is incorrect, though until the changes above, this did not cause any noticeable problems.
In practice, this problem currently doesn't arise. If the Inflow or Local Inflow are going to influence the solution, a constraint on outflow will pull their values into the formulation. We may have to revisit this situation in the future if a new lagged physical constraint is added to the model. For now, this would have been a costly fix without any practical benefit.
Instead, Inflow and Local Inflow have been removed from the list of slots whose variables are defined by the reach mass balance definition. Because this leaves Inflow and Local Inflow potentially undefined, the check that all slots referenced in a problem must have at least one definition has been relaxed.
Unconstrained slots
A warning is issued if certain slots are unconstrained during optimization (i.e., they are not linked and NaN). Currently, these slots are Reservoir.Inflow, Reach.Inflow, Reach.Local Inflow, Confluence.Inflow1, and Confluence.Inflow2. Additional slots may be added to this list in the future.
Optimization
Plotting and Output
Table Slots - Reverse axes
Typically, when you plot a table slot with two columns, the plot shows the first column on the X axis and the second column on the Y axis. For some slots, like the Elevation Volume table, this is not ideal; the Elevation would more naturally be on the Y axis. A user preference has been added to allow you to override this default and instead reverse axes for slots that have this type of configuration. An example of this axis switch is shown in the two plots below. The left plot is the standard plot, the right plot is switched using the new setting.
Tabular Series Slot Report device
A new output device was added to the Output Manager. The Tabular Series Slot Report generates a plain text or HTML document showing, in a table or multiple tables, values for a set of series slots. The data for each series slot is displayed in one column of the table. A sample is shown below.
RiverWare Policy Language
Agenda order is not always shown
The agenda order (3,2,1... or 1,2,3...) is only applicable for RBS rulesets, iterative MRM, and optimization goal sets. Thus, a change was made so that the other sets (expression slot sets, accounting method sets, and global function sets) do not even show this setting using the View Show Advanced Properties. Also, for optimization goal sets, the agenda order is shown but must always execute in the 1,2,3... order; it cannot be changed.
Enabled/Disabled Expressions
The display of disabled expressions within RPL dialogs was changed to be cross hatched instead of using a solid color. You can change the color of the cross hatching (and all other display colors) in the RPL Layout dialog, “Colors” in RiverWare Policy Language (RPL). Also, the semantics of enabling or disabling an expression was modified. Now the toggle menu says “Enabled”; it has a check mark when enabled and no check mark when disabled.
IsInput Predefined Function
The RPL predefined function IsInput(slot, datetime) now will return false if the slot[datetime] is NaN.
Performance
An improvement was made to the caching of RPL expression values during initialization of a run. This improves evaluation time especially for expression slots evaluating at the beginning of the run that call the group of RPL functions that includes SumObjectsAggregatedOverTime, MaxObjectsAggregatedOverTime, etc.
Re-implementation of the List of Rules, Methods, Goals
In RPL sets, the list of blocks (rules, methods, goals) was re-implemented. The following functionality was added:
• Optionally show statements in the tree-view
• Copy/paste uses the system clipboard
• Drag and Drop is more intuitive:
– Drag/Drop between two sets is a copy/paste operation, Drag/Drop within a set is a cut/paste operation
– Dropping an item will append it after that location where it is dropped.
RPL Debugging
A fully functional RPL debugger was added. Now you can pause RPL execution, look at the values of RPL expressions as they are evaluated, and step through RPL execution. A screenshot of this utility is shown while the run was paused in the RPL function to the right. For more information, see “RPL Debugger” in Debugging and Analysis.
RPL Diagnostics units
For diagnostics that print RPL values and for the RPL debugger, it is now possible to show numeric values in the units specified in the Resource Database (riverwareDB) file. A toggle “User Resource Database Units for Diagnostics” was added to the RPL Parameters. See “Units for RPL Diagnostics” in Debugging and Analysis for more information.
Save loaded RBS set with model
It is now possible to save the loaded RBS Ruleset and/or the Optimization Goal Set with the model file instead of in a separate file. This behavior is controlled through a setting in the Run Control, View Optimization/Rulebased Simulation Run Parameters dialog.
The toggle Save Loaded RPL Set with Model controls where the set is saved. By default, this toggle is OFF meaning the set is saved in a file external to the model. Checking it ON will save the Loaded set with the model file. When a model file has this toggle ON and it is opened, the RPL set is loaded and then minimized (iconified).
Run Control
Order of controllers
In the run control dialog, the list of controllers was re-ordered as follows:
• Simulation
• Optimization
• Rulebased Simulation
• Post-Simulation Accounting
• Inline Simulation and Accounting
• Inline Rulebased Simulation and Accounting
Pause before Timestep
In the Run Control dialog, a toggle and datetime spinner were added to allow you to run, but pause before the specified timestep. This was added for debugging purposes. For more information, see “Making a Run” in User Interface
SCT
Copy Slot lists from SCT to Output Device config
From the SCT, you can now copy one or more selected slots to RiverWare’s slot clipboard. From the slot clipboard you can paste the list of slots to various places such as the Output Device slot lists and the Snapshot Manager slot list.
Export Copy optionally includes Column Headers
When you perform an Export Copy (Edit Export Copy...) from the SCT, you now have the option to include Column Headers along with Row Headers. In the SCT vertical timestep mode, the column headers include the slot/label and units. In horizontal timestep mode, the column headers include the timestep and weekday. For more information, See “Copy/Paste Data to/from the Clipboard (e.g., to Excel).” in User Interface
Flag letters and Rule Priority numbers
Previously on the SCT, series slot flag states were indicated only by background cell colors. Now, the user has the option of showing a flag letter and RPL priority numbers in addition to background color. Screenshots show this for both orientations of the SCT.
This option is contorlled through the View Cell Text menu. For more information, see “View Menu” in User Interface.
Four Hour Dividers
It is now possible to add four hour dividers (after 24:00, 4:00, 8:00, 12:00, 16:00, and 20:00) to an SCT in both axis configurations. This is configured in the SCT Configuration Horz Time or Vert Time tab (depending on axis configuration). Then the color of the divider can be set in the Color tab
Import Paste
Two dimensional import paste is now supported to the SCT. You can copy a table of data from Excel or another application and then Import Paste (Edit Import Paste...) the values. A dialog (shown to the right) displays the data that will be imported and provides options on how the import should perform.
SCT on abort
When a run aborts, the SCT no longer automatically scrolls to the abort operation's "context" timestep. The option to "Time Scroll" is still available to mimic the previous behavior.
Table Slots Column Labels
On the SCT, the Other Slots tab now lists, for Table Slots, the
• number of rows
• number of columns and
• the Column Labels.
Selector
Integer Indexed Slot Filter
In the slot Selector, there is a new filter option for finding integer indexed slots. This option, Integer Indexed Slots, is available in the Slot Type filter.
Simulation Objects
Power Reservoirs
Unit Power allows negative unit energy
On the power reservoirs, the Unit Power method was modified to allow the user to set (via input or rules) negative Unit Energy values to represent times when the unit is consuming energy. In this case, the Unit Turbine Release is set to zero.
Reservoirs
Conversion of series slots to Periodic
On the reservoirs, the following slots were converted from Series Slots to Periodic Slots:
• Irrigated Area Loss Rate
• K Factor
• Meadow Area Loss Rate
• Pan Ice Switch
When you first load your model, if you are using these slots, a series of warning message will be posted to diagnostics, for example:
“SLOT: Reservoir.K Factor: Trying to convert former slot type ("SeriesSlot") to new slot type ("PeriodicSlot")."
You must re-entered the data into these slots where applicable. This is especially true for the Pan Ice Switch; previously, the value would default to 0 if not input, now the value MUST be input. A single 0.0 in the periodic slot is sufficient if only 0 is required.
Periodic Net Evaporation Method
A new evaporation method, Periodic Net Evaporation was added to the reservoirs’ Evaporation and Precipitation category. Periodic Net Evaporation computes the gross evaporation from the reservoir and then subtracts out components of evaporation that would have occurred if the reservoir had not been built. This is the net evaporation and is set in the Evaporation slot. Each area of the submerged reservoir is separate including: river, streamside, terrace, and any remaining areas.
Single Value Seepage method
A new seepage method, Single Value Seepage, was added to the reservoirs’ Seepage Calc category. The Single Seepage Value method sets the seepage through the face of the dam equal to a scalar value.
Reach
Pan Evaporation method
A new method, Pan Evaporation, was added to the reach’s Evaporation Calculation category. This method models evaporation based on the pan evaporation rate, the surface area of the reach and a pan evaporation coefficient.
Reach Seepage
In the Head Based Seepage and One Timestep Seepage Lag methods, positive seepage is limited to be less than or equal to the inflow to the reach. A bug occurred when the reach re-dispatched with a larger inflow. The seepage was not reverting to its original value, but was using the constrained value. A slot "Seepage from Previous Timestep Conditions" was added to hold the lagged seepage. Then, the seepage is reset to this value when necessary.
Groundwater Storage - Evaporation category and methods
A new category, Evaporation, was added to the groundwater storage object.
This category contains two methods: No Evaporation and Wetted Sand Evaporation. No Evaporation is the default method and performs no calculations. The Wetted Sand Evaporation method computes the evaporation that occurs from the wetted sand of the shallow groundwater.
Slots
Expression Slot Re-implementation
Both Series and Scalar Expression slots were re-implemented to support more functionality including:
• Copying values
• Scrolling to a date
• Compressing values
• Showing Notes
• RPL debugging
In addition, the dialog layout and a few menus were re-arranged. Also, by default, the RPL expression is now shown.
Notes on Series Slots re-implementation
Notes on series slots were re-implemented. Notes, still organized within Note Groups, are now directly applied to individual series slot timesteps rather than by associating their containing Note Groups with whole series slots. Additionally, multiple notes can be associated with a timestep on an individual series slot. The note manager dialogs were re-designed; some samples of the dialogs are shown in the screenshot. See “Notes Overview” in User Interface for more information on this utility.
Periodic Slot - Regular interval row headers
The display of row headings on periodic slots configured with a regular interval have been changed. For example, when added to a data object, the default Lookup and Interpolate slots are:
Note:  This only applies to Regular Interval periodic slots; irregular interval slots have not been changed. For more information on periodic slots, see “Display of Dates” in User Interface.
Workspace
Display Group Editor dialog
The Display Group Editor was improved with changes to the display of the Legend lines and colors. Also, a column was added that shows a count of the active items in each group.
Font and Text Size
The ability to globally set the dialog font and text size was added. Use the Utilities Windows Set Font menu to access the font chooser dialog. This font will apply to all dialog menus, lists, buttons, and other text. There are few limitations with this feature:
• The font setting is only changed during a single RiverWare session. It does not persist between sessions.
• The font setting does not affect the workspace font size, existing SCTs, or RPL expressions.
• Different fonts seem to work well in RiverWare if they are reasonably sized but some dialogs don't display extreme-sized fonts.
Loaded RBS ruleset and Opt Goal set buttons added to workspace
The workspace now has buttons on the bottom of the dialog to show the loaded RBS ruleset or optimization goal set . The bar is red when there is a loaded set, grey when there isn’t. Clicking the button (when red) brings that loaded set to the front.
Policy menu reorganized
On the workspace, the Policy menu was re-organized as shown in the screenshot to the right. Now, the name of any opened set (and any set saved with the model) is added to the bottom of the menu as shown. Only the short name is shown in the menu, but the full path is shown in the workspace status bar.
Links in status bar
When you mouse over a link in either the Simulation or Accounting View, a tool tip shows the name of the link(s). Now, the name is also shown in the workspace status bar (lower left corner). If there are multiple links, only the first one is shown.
Closed Bug Reports
The following bugs have been closed for this release. For more information on any bug, see the CADSWES website. The bugs are listed in order by bug number:
 
700
957
981
1146
1151
1176
1199
123
1
1258
1265
1267
1269
1477
1520
167
5
1765
1942
1992
2157
2161
2284
234
5
2418
2497
2518
2554
2555
2680
284
6
2929
3100
3225
3248
3270
3374
339
0
3391
3414
3425
3481
3501
3510
351
4
3523
3536
3550
3603
3604
3650
366
1
3666
3673
3687
3696
3702
3708
370
9
3737
3739
3752
3755
3756
3759
376
0
3761
3779
3802
3806
3810
3837
384
0
3847
3875
3903
3925
3944
3945
398
9
4146
4152
4153
4210
4279
4288
432
0
4355
4358
4395
4412
4446
4457
446
1
4463
4471
4518
4528
4544
4549
461
6
4623
4625
4654
4659
4667
4669
469
7
4699
4712
4729
4732
4736
4738
474
1
4743
4745
4747
4748
4749
4750
475
1
4752
4753
4754
4755
4756
4757
475
8
4761
4762
4763
4764
4766
4767
476
8
4769
4770
4771
4772
4774
4775
477
6
4778
4784
4785
4787
4788
4789
479
0
4791
4793
4794
4795
4796
4797
479
9
4800
4801
4802
4803
4804
4806
480
7
4808
4809
4810
4811
4812
4813
481
6
4817
4818
4819
4820
4821
4822
482
3
4825
4826
4827
4828
4831
4832
483
5
 
 
 
 
 
 
 
 
Revised: 06/03/2019