skip to main content
Release Notes Version 7.0
Release Notes Version 7.0
This document describes new features, enhancements, and changes in RiverWare Version 7.0.
Special Attention Notes
Following are special attention notes, indicating that functionality has changed that requires you to update models or that results may differ. If you have any questions, contact
• Input values on slots not in use: It is possible to change method selection such that input linked series slots are no longer “in use” on the object. The slots and data still exists on the object in case you wish to revert the method selection. Previously, the input values that were not in use would still propagate across the link and could be used by the linked object. This was misleading and has been changed. Now, if a slot is not in use, no propagation of input values will occur at beginning of run. This could change model results if you have inputs on slots that are not in use. If this is the case, modify method selection, change input location, or reconfigure your links.
• Slope Power Reservoir; Max Outflow computations changes: If you use either the Max Capacity flag on outflow or the GetMaxOutflowGiven... RPL functions on a Slope Power Reservoir, see the changes described “Max Outflow Calculation on the Slope Power Reservoir”.
• Reach; No Local Inflow, Solve Outflow method changes: On a Reach using the No Local Inflow, Solve Outflow method (in the Local Inflow and Solution Direction category), it was possible to specify or propagate an Outflow that was inconsistent with the lagged Inflow. This is now an error.
Batch Mode
RCL changes
Within Batch Mode and the RiverWare Command Language (RCL), the SetRunInfo command can be used to change the run range. A new argument !StartDate was added to this command. This argument can be used as an alternative to the !InitDate argument.
Data Management Interface
Configure Datasets Utility
A new utility was added to the Database DMI that allows you to configure multiple DSS dataset file paths simultaneously.
Database DMI Copy/Paste
Copying a Database DMI from the DMI Manager was modified to allow for two options:
• Copy Database DMI Only: This option copies only the top level Database DMI, but none of the Datasets or Name Maps. When pasted, the new DMI refers to existing Datasets and Name Maps. This was the previous behavior.
• Copy Database DMI, Datasets, and Name Maps: This option provides a “deep copy” of the Database DMI and all of the Dataset and Name Maps it accesses. For this option, when pasted, the new Database DMI is connected to newly pasted Datasets and similarly, Name Maps.
Database DMI Export/Import
The Database DMI Import/Export functionality was improved such that importing a DMI modifies the connections to any Datasets and Name Maps that are also imported. This allows you to take an entire Database DMI, Dataset, and Name Map and move it from one model to another and preserve the connections. For more information, see “Sharing Database DMIs” in Data Management Interface (DMI).
Excel Database DMI supports Table, Periodic and Scalar slots.
The Excel Dataset and Database DMI now allows you to import or export Table, Periodic and Scalar slot values. Previously, only series slots could be imported or exported. With this new functionality, you can use the Ranges approach to specify a range or list of cells in Excel to use or you can use the Headers approach and configure your Excel sheet in a specific format.
Multiple Run Management
Input DMI Repeat Count
The MRM input DMI was limited to a maximum repeat count of 999. Now the maximum number of input DMI repetitions and number of traces is limited to 99,999.
Ordering of Slots in an RDF file
The order of slots in a RiverWare Data Format (RDF) output file now matches the order in the output control file.
Saved Distributed MRM Run Configurations
With distributed MRM, it is possible to save the configuration file RiverWare creates to a named file and then start distributed multiple runs from the configuration file, thus bypassing the RiverWare interface. This is controlled through the optional Save Distributed Run Configuration As field in the MRM configuration dialog. For more information, see “Save Configuration As” in Solution Approaches.
Configuration files saved with RiverWare 6.9.7 or earlier will not be compatible with RiverWare 7.0. You will need to regenerate the configuration file through the RiverWare interface.
Reach - Solve Outflow method with Lagged Inflows
On a Reach using the No Local Inflow, Solve Outflow method (in the Local Inflow and Solution Direction category), it was possible to specify or propagate an Outflow that was inconsistent with the lagged Inflow. Now, this circumstance will result in an error.
Dispatch Slots
The Reservoir slots Evaporation Rate and Precipitation Rate were added to the list of dispatch slots. Now they are linkable and a new value (input, propagated, set by a rule) will trigger the object to redispatch, if possible.
Max Outflow Calculation on the Slope Power Reservoir
The max outflow computation iterates to find the Storage in the Slope Power Reservoir. This calculation uses the current outflow as one of the parameters in the computation (in Impulse Response slope storage calculation especially). Previously, it used the values on the Outflow slot which came from a previous dispatch. Once the max computation is complete, it sets the Outflow slot. Within the rest of the dispatch, it then uses that Outflow as the current value in the slope storage calculation. Since this is different, the Storage, Pool Elevation, and headwater are all different, thus leading to a different max Turbine Release and Spill.
The code was changed to use the values that are computed within the iteration for the current Outflow. In a test model, this does slightly change results. For example, in one test model, the flow on one timestep went from 293.50 (1000cfs) to 293.52 (1000cfs). The pool then changed by 0.0001ft. On the final timestep, the pool was 0.001ft different. They are not significantly different, but these can compound over time as the storage changes.
Reservoir Accounting Methods
The following two Table Series Slot columns were duplicated on separate Series Slots:
• Est Sed Deposition - Accumulated Perm Sediment column was duplicated on the Accumulated Permanent Sediment slot. This slot is added by the Total Vol Sed (Post2000) method in the Sediment Transport Calculations category.
• Rio Grande Pools - Carryover Content column was duplicated on the Carryover Content slot. This slot is added by the Abiquiu Gain Loss, Jemez Gain Loss or the Cochiti Gain Loss methods in the Reservoir Account Gain Loss category.
These series of data are duplicated on the individual series slots. The series slots hold the values used in the calculation but the data is also shown in the original table series slot. (This allows any existing output devices to continue working without changes.) In addition, if the value on series slot is not known, but the value on the table series slot is known, the table series slot value is copied to the series slot at the initial timestep and set as an input. This will preserve it for future runs and when aggregating to monthly.
In addition, previously on the Present Condition Table Series Slot, the River Channel Area and Barren Area values were required inputs on the initial timestep for a monthly run. These are now computed from other data. This slot is part of the Abiquiu Gain Loss, Jemez Gain Loss or the Cochiti Gain Loss, El Vado Gain Loss, Nambe Falls Gain Loss, and Elephant Butte Gain Loss (both variations) methods in the Reservoir Account Gain Loss category.
Reach and Reservoir - Coeff and Exponent and Forecast methods
Within the Coefficient and Exponent method on the reach (Generate Local Inflows category) and reservoirs (Generated Forecast Hydrology category), a minimum deterministic inflow was implemented. Now the Lower Bound on the Deterministic Local/Hydrologic Inflow slot is used as a minimum value in the computation. Any absolute values smaller than the minimum values behave as though the value is zero; that is, the deterministic value is used directly in place of a forecast value. For more information, see “Coefficient and Exponent” in Objects and Methods on the reach and “Coefficient and Exponent” in Objects and Methods on the storage reservoir.
Water User
Soil Moisture Modifications
The Water User soil moisture return flow methods Proportional Shortage with Soil Moisture and Variable Efficiency with Soil Moisture were modified with a new slot, Surface Runoff. In addition, the Supplement Diversion including Soil Moisture method in the Conjunctive Use category was modified to have an additional slot, Supplemental Runoff.
These slots represent water that is applied that is higher than max infiltration rate and runs off directly. If these slots are linked, the corresponding Return Flow does NOT include that water as it goes elsewhere. If they are not linked, the Return Flow does include that water and these two slots are for informational purposes. This distinction is needed as the quality of this water is different than the water that moves through the soil. For more information on new water quality salinity methods on the water user, see “Water User”.
Water User Performance Improvement
The run time performance of the Water User's SW GW Impulse Response return flow routing method was improved. In one test model, the run time was reduced by 27%.
Object Dialogs
Custom Slots on Simulation Objects
You can now create custom slots on any object including Simulation Objects. Previously, custom slots were only allowed on Data Objects. Having custom slots on Simulation objects allows you to locate your custom slots with the object to which they refer. This also makes RPL logic, Scripts, Output Devices, and DMIs much easier. For example, instead of referring to a reservoir’s minimum outflow on an accompanying data object, ReservoirData.MinFlow[ ], you can move the minimum flow custom slot onto the reservoir and refer to it directly: Reservoir.MinFlow[ ].
With this enhancement, the Open Object dialog was improved as follows:
• A custom column was added with a C icon to indicate a slot is custom. Select the header to sort and show all custom slots together.
• Custom slots are shown with icons that have a pale yellow background.
• Slot Groups are now allowed on any simulation objects except Aggregate objects.
Move Slots Utility
• A new Move Slots utility was added that allows you to move one or more slots from one object to another. To move slots using the new functionality:
– Open the object containing the slots that you would like to move
– Select the slots to be moved.
– Select the Move Slots to Object... menu from the Slots menu or right-click context menu.
– This will open the Move Slots to Object dialog.
– Select the destination object.
– Select the Move button.
– A confirmation dialog is presented; if the action is confirmed and successful, the destination object dialog is opened and the moved slots selected.
Negative Hydrologic Inflows
On the Slope Power Reservoir, negative hydrologic inflows are now allowed in optimization.
Preferred Units
Preferred optimization units were added for the PowerPerFlow unit type: 1 MW/cms.
Improved Performance for Shrinking Constraints
The efficiency of the internal algorithm for shrinking a constraint to a higher priority constraint with the same left-hand-side was significantly improved. In one large test model, this reduced the overall run time by approximately 25%.
Output Devices
Charts: Video File Animation Generation
Chart animation video files can be generated directly from RiverWare. Basic settings include the frame sampling timestep size, frames per seconds, and format. Four video formats are supported:
• MP4,
• WMV, and
• animated GIF
In addition, there are advanced settings available for complete customization of the export process.
Output Canvas
The Output Canvas, described in “Output Canvas” in Output Utilities and Data Visualization, allows for visualization of outputs in spatially distributed teacups and flow lines. The following improvements have been added to the Output Canvas:
Canvas Lines
Canvas Lines provide generic lines on the canvas. You can use these for many purposes but were designed to provide pointers to locations on the canvas. You can add end symbols including dots (shown to the right), triangles, and arrow heads. More information is available in “Canvas Line Group” in Output Utilities and Data Visualization.
Charts on an Output Canvas
Charts can now be placed on an Output Canvas and will animate at the same time as the canvas. Handles are available for resizing and scaling the selected chart. Geometry fixes to avoid clipping of the chart image due to the chart size specified within the Output Canvas configuration were also implemented. More information is available in “Chart Group” in Output Utilities and Data Visualization.
Miscellaneous Enhancements
Following are three miscellaneous enhancements made to the Output Canvas:
• Precision overrides were added for numeric values shown in Teacup, Object Icon, and Text Groups. This setting allows you to control how many digits are shown after the decimal.
• Plain-Text items now allow you to enter multiple lines of text as configured in the editor.
• In Slot Value Text Items, the RPL Priority value can now be shown.
New approach to View and Edit Plot Pages
The Plotting utility was modified to remove the Save approach. Now there is a separate Plot Page Editor used to configure the plots and then the Plot Page used to view and interact with a plot.
• Plot Page Editor: The editor is used to modify the slots shown and the appearance of the plot (colors, line types, markers, etc). New buttons on the left side provide access to add curves and configure the plots. This is shown below on the left.
• Plot Page: The Plot Page displays the plots and provides interaction with multiple plots. This is shown below on the right.
In addition, the original plot page dialog (shown to the right), used to select a list of slots to plot, was removed. all configuration is performed in the Plot Page Editor shown in the above left screenshot.
As a result, all snapshot slots can be added directly to a Plot as a unique curve. There is no longer an associated show “Snapshots and Slots” option.
Plotting Scalars
Scalar Slots can now appear in time series plots. Scalars with datetime units are shown as vertical lines. Scalars with any other unit type are shown as horizontal lines.
Time Scaling
The plotting utility now supports a new configurable Time Scaling feature for time series plots. This includes the following provisions:
• Time axis configuration options support symbolic dates, for example, Run Start or Finish, plus or minus a specified number of timesteps or basic time units. In addition, any fully specified RPL datetime or global RPL datetime function can be specified. The screenshot to the right shows the axis configuration with time options shown.
• A new time scaling operation (T button, , and Plot menu operation) sets the time range of a graph to the configured datetimes.
• There is an option to automatically apply this configured time scaling to a graph each time the graph is shown.
• The default axis preferences also support this time scaling setting, to be applied to newly created graphs. This replaces a simpler default configuration provision which provided two choices for the initial time range of newly created graphs.
• The Scale to specified time range toolbar button (S button, ) now has a shift-click option. When the button is shift-clicked, all open plot dialogs brought to the front and are synchronized to the specified time range of the clicked plot dialog.
Tabular Series Slot Reports - Environment Variables
You can now use environment variables in Tabular Series Slot Report file specifications. For more information, see “Output Tab” in Output Utilities and Data Visualization.
RPL Set Comparison Tool
The new RPL Set Comparison Tool compares two RPL sets and shows you the differences between the sets. This allows you to see where items are different, what the specific differences are, and allows you to easily access the RPL set dialogs so that you can change one or both sets.
This tool is very useful in the RPL set development processes over time and across multiple developers. It allows the comparison and understanding of development of a RPL set. In addition, it helps assist with merging of changes by providing quick access to the RPL editors and copy/paste functionality.
A screenshot of the tool is shown below. For more information, see “Comparing RPL Sets” in RiverWare Policy Language (RPL).
RPL Set Name vs Path
All RPL sets now maintain both a name and a file path (if saved as a separate file). Previously, these two concepts were intermixed. This allows you additional flexibility as follows:
• Sets saved to a separate file can have a meaningful name that describes the set, like “Operations Ruleset”. The path can then be used strictly as a file name, C:\Operations\OpsSet.v1.2.rls.gz
• Sets saved within the model file have a name that can be used for improved nomenclature. For example an Initialization ruleset could be named “Operations Initialization Set”.
Locations in RiverWare that refer to a set, now uses the set name. For example, in a Model Report, in the RPL Set item, you now choose the name of the set, not the path or location.
RPL Search and Replace Utility
The RPL Search and Replace utility, “RPL Search and Replace Dialog” in RiverWare Policy Language (RPL), allows you to search for and replace items within a RPL set. The following enhancements were made:
Next / Previous buttons
Buttons were added for advancing forwards or backwards through the search results. These can also be activated using keyboard short cuts:
• Next Item: F3
• Previous Item: Shift +F3
Scroll To and Select Match
When a match is opened (by double-clicking on that row or by using the next/previous item operation), the relevant dialog is now scrolled so the match is in view and the item is selected.
Expression Slot Descriptions are Searched
Expression slot descriptions are now included in searches when the RPL Expression Slot Functions set is searched and when the Descriptions options is checked.
RPL Editing
Auto-correct of Typed Values
When you double-click on a RPL expression (i.e., on a RPL value or an empty expression in a panel for displaying and editing RPL statements and expressions), a small, in-line editor window is opened at that location, allowing you to type in a value with which to replace the existing expression. If the value provided is not a valid replacement for the expression, RiverWare now attempts to coerce the input string into one that is valid.
This auto-correction process is guided by the types that can legally replace the existing expression. It tries a series of variations on the specified values, where each variation is an attempt to coerce the input into a different value type. Types are considered in the following order: DATETIME, OBJECT, SLOT, STRING, and LIST. If a valid auto-correction is found, it is used to replace the existing expression; if not, an error notification is presented, describing the problem with the input.
For example, consider the statement
WITH (STRING val = <string expr>) DO
PRINT "value: " CONCAT <expr>
If the text 't + 1' is entered as the variable value in the With expression, it is interpreted as the String “t + 1” because that is the only legal type for that expression; whereas the same text entered as the right-hand side of the CONCAT expression is interpreted as the DATETIME @“t + 1", because all types are valid in that location and a DATETIME conversion is considered first.
Common Values
Two new operations were added to provide common values when editing RPL expressions.
• A new “Values” button group was added to the palette to support insertion of common values and Flag Values.
• A right-click context menu on any selected RPL expression provides a Common Values menu.
Copy and Paste from Variable and Argument Declaration
A RPL variable declaration name can now be copied and pasted into expressions as appropriate.
Within the function editor, you can copy an argument name and paste it into an expression. This works slightly differently. To copy an argument select the argument name by double-clicking on it in the arguments panel, then perform the copy operation using either the right-click context menu or by typing Control + C. You can then paste this argument into an expression in the function using the Control+V keys or right-click menus. Note that the Edit->Copy menu does not work to copy the function argument.
Improved History
When you double-click on a literal value or an empty expression, a small, in-line editor window is opened at that location, allowing you to type in a value or select a value from the menu of items previously entered in the frame. Previously, this history menu was sometimes missing entries (especially those that were not a valid value to insert). Now, the history includes all previous entries (except empty strings).
Improved Pasting of Statements with Variables
RPL statements that define a variable (i.e., WITH and FOR statements), now allow better copy and pasting. For example, consider the following logic:
WITH (OBJECT res = % "res1") DO
IF (res & "Inflow" [] == 0.0) THEN
WITH (NUMERIC flow = 0.0) DO
Pasting the If statement onto itself previously caused the inner WITH statement to have an validity issue where the reference to “res” within the new Print statement would be reported as invalid. This has been improved so that copy and paste of these types or statements works as expected.
RPL Item Delete Confirmation
Deleting an item from a RPL editor tree view now presents a confirmation dialog.
Stop on NaN for Initialization Rules
The existing Stop on NaN property of a rule (“Stop On NaN” in RiverWare Policy Language (RPL)) allows you to specify that the run should abort instead of having the rule terminate early when a NaN is found in a slot value. This can be used to stop the run when missing data is expected but not found.
If an invalid value (NaN) is encountered while executing an initialization rule with the “Stop on NaN” property enabled (and the RPL debugger is not enabled), the run no longer immediately aborts, but rather posts an error and continues to execute any subsequent statements in the initialization rule and any subsequent rules in the initialization rules set. After all initialization rules have executed, the run is aborted with the message:
Aborting the run because one or more initialization rules with the “Stop On NaN” property set encountered an invalid value (NaN).
If multiple statements access data which are missing, the new behavior allows a single RiverWare run to identify all of these statements. Previously, you would need to resolve the first issue and conduct another run in order to be alerted to the next issue. But, the new behavior can report invalid values that are not in fact independent data issues (i.e., report false negatives), but are rather later rules accessing a value set by an earlier rule that has missing data.
If the RPL Debugger is enabled when an invalid value is encountered by an initialization rule with the “Stop on NaN” property set, RPL execution is paused just before the run is aborted, and the RPL debugger is presented, displaying the error message that is about to be posted.
Note that this represents a change in behavior for existing models, though not for runs that currently complete successfully.
RPL Predefined Functions - New IntegerWithUnitsToString function
A new RPL Predefined function, IntegerWithUnitsToString, was added. This function allows you to convert the integer portion of a NUMERIC value with the specified units into a string. This provides more flexibility than the existing IntegerToString function that only uses internal units.
For more information on IntegerWithUnitsToString, see “IntegerWithUnitsToString” in RiverWare Policy Language (RPL).
RPL WHILE Expression Maximum Iterations
The RPL WHILE expression (added from the palette) is now limited to loop no more than the maximum number of iterations. The maximum iterations is a model specific parameter saved in the RPL Parameters. The default maximum iterations is 10,000 but may be changed using the Policy RPL Parameters... menu on the workspace. If maximum iterations are exceeded, the run is aborted. See “Conditional and Iterative Operations Buttons” in RiverWare Policy Language (RPL) for more information on the WHILE expression.
Script Management
Disabling Actions
Previously, actions could be disabled (omitted from script execution) in the Script Dashboard. When reopened or if changes were applied from the Script Editor, all action checkboxes were turned back on.
Now, action enabledness can also be controlled in the Script Editor with checkboxes now appearing with each action item. Action enabledness is now part of the script configuration, and persists when applied from the Script Editor and if the model is saved to a model file.
New Action Types
Following are new action types added to the Script Manager:
• Enable Dispatching: Enable or disable dispatching of the specified set of objects.
More information is available “Enable Dispatching” in Automation Tools.
• Evaluate Expression Slots: Evaluate one or more specified Expression Slots.
• Open Object: Open the dialog for the specified object(s).
More information is available “Open Objects” in Automation Tools
Set Slot Value Actions
Setting DateTime values
All three slot-setting action types, when used to assign values to DATETIME slots now allow the specification of symbolic DATETIMES, including the name of a Global RPL Function returning a DATETIME value. This applies to these three script action types:
• Set Scalar Slot Value
• Set Series Slot Values
• Set Table Slot Value
Initial/Default Value
The slot value setting for those same three slot-setting Script Action types is now initially NaN, and can be set to NaN. This is supported in both the Script Editor and Script Dashboard.
Show Dialog Settings
These four existing Script Actions now have a Show Dialog (Yes/No) setting:
• Load Goal Set
• Load Ruleset
• Open Global Functions Set
• Replace Initialization Rules Set from File
When this setting is “Yes”, the set dialog for the relevant RPL Set is shown after opening the set.
Improved status and execution buttons
In both the Script Editor and Script Dashboard, the icon of the Play button changes to a Resume icon when the script is paused (e.g. in a Memo script action which has paused script execution).
When the Script Memo dialog is closed, the main dialog from which the script execution was started is shown, and raised to the top. This indicates that you should control execution of script from that dialog.
Improved Navigation
Both the Script Editor and Script Dashboard action items support new context menus (right-click) to allow you to directly open the dialog for these various objects types (e.g. slots) referred to within the action's configuration settings.
In addition, in the Script Editor, an adjustable “Splitter” was added between the Actions panel and the Selected Action Settings panel.
Removal of Obsolete Settings
A number of unnecessary or obsolete script action settings were removed. When you first load you model in 7.0, you may see diagnostics indicating these settings were removed. Once saved in 7.0, the messages will on longer be posted.
Column Width
The SCT now preserves the per-sheet column width specifications for the two relevant SCT row header columns: Slot Label and Slot Units.These are now preserved.
In addition, the scroll position is maintained when switching sheets.
Custom Slots on any Object
You can now create custom slots on any object including Simulation Objects. Previously, custom slots were only allowed on Data Objects. See “Custom Slots on Simulation Objects” for more information on changes to the interface when viewing custom slots. In addition, the Slot Selector now has a filter called Is Custom to allow you to filter by custom slots.
Unit Schemes and Slot Copy Paste
When slots are copied and pasted, the Unit Scheme exceptions are also updated accordingly so that the display attributes of the new slots match those of the original slots.
Water Quality
Pipe Junction
A new Pipe Junction Water Quality category was added. In the Propagate Salt method, the Pipe Junction methods behave like the confluence object in that it sums salt mass: Flow 1 Salt Mass + Flow 2 Salt Mass = Flow 3 Salt Mass. Salt concentrations are a flow weighted average. For more information, see “Propagate Salt” in Water Quality.
Water User
On the Water User, two methods were implemented for the new Salt Storage category:
• Soil Moisture Salt Storage (“Soil Moisture Salt Storage” in Water Quality)
• Soil Moisture Salt Storage with Supplemental Flow (“Soil Moisture Salt with Supplemental Flow” in Water Quality)
These methods model the diversion and return flow salt mass and concentration including the storage of salt mass in the soil moisture volume. They are the same except the latter also computes supplemental flow salt and adds it into the salt mass balance.
Tool Tips
Tooltips were added or improved on most of the toolbar and other buttons on the Workspace, the SCT, and the Run Control.
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:
Revised: 06/03/2019