Release Notes Version 4.9
Special Attention Notes
Subslots default convergence
Subslots on multi-slots are now given a convergence type of “None” when they are created. Previously, subslots were given the default convergence of 0.01% and there was no way to modify or change this value. Convergence issues will be caught by the multi-slot or the other end of the link, so checking convergence on subslots is unnecessary. Although test models have shown insignificant numerical differences in results, this modified approach could change the results of some models.
Contact riverware-support@colorado.edu if multi-slot values have changed significantly.
Slot name change
Deterministic Local Inflow and Deterministic Hydrologic Inflow
As part of the new cumulative to incremental disaggregation methods described in “Calculate Incremental Local Inflows category”, the name of the control point slot “Deterministic Local Inflow” was changed to “Cumulative Local Inflow.” On reservoir objects, the name of the slot “Deterministic Hydrologic Inflow” was changed to “Cumulative Hydrologic Inflow.” The forecast methods in the Generate Forecast Inflows/Hydrology category that previously used the “Deterministic Local/Hydrologic Inflow” slots now use the new “Deterministic Incremental Local/Hydrologic Inflow.”
If you use one of the Generate Forecast Inflows/Hydrology methods that access this slot, there are two options:
• If you wish to continue using data in the old “Deterministic Local/Hydrologic Inflow” slot in its previous form (either cumulative or incremental), it is recommended that you re-input the data into the new “Deterministic Incremental Local/Hydrologic Inflow” slot. If you do not re-input the data, RiverWare automatically copies the existing data from the new Cumulative Local/Hydrologic Inflow into the Deterministic Incremental Local/Hydrologic Inflow at the beginning of a run. The data will not have input flags. To see or modify the input data, you would need to select the Compute Forecast Period Incremental Local/Hydrologic Inflow method in the Calculate Incremental Local/Hydrologic Inflows on Subbasin method temporarily. To avoid having to select this method, it is recommended that you re-input the data into the Deterministic Incremental Local/Hydrologic Inflow slot.
• If you have cumulative flows in the old Deterministic Local/Hydrologic Inflow slot and you plan to disaggregate the flows using one of the new methods, the data should remain in the new Cumulative Local/Hydrologic Inflow slot. You must then select a new disaggregation method in the Calculate Incremental Local/Hydrologic Inflows on Subbasin on the Control Point/Reservoir and create a subbasin to perform the disaggregation.
In addition, if any of these slots are referenced by DMIs, output manager devices, rules, or expression slots the models will need to be modified. For more information on these methods, please see “Slot name change: Deterministic Hydrologic Inflow” (reservoirs) or “Slot name change: Deterministic Local Inflow” (control points).
LengthPerTemperature unit type changed to LengthPerTemperature_F
The unit type LengthPerTemperature was changed to LengthPerTemperature_F. The internal, standard units for this type are “m/F” and user units include “ft/F” and “inches/F.” In the old LengthPerTemperature unit type, there were units of “m/C” and “ft/C,” these have been removed. When users open an existing model in RiverWare 4.9 for the first time, the following warning message is posted regardless of whether this unit type is used: “The unit type LengthPerTemperature was changed to LengthPerTemperature_F. Existing data in slots with this unit type must be updated. See the RiverWare 4.9 release notes in the online help for more information.” In RiverWare’s engineering methods, this unit type is only used in the K Factor slot on the “PanAndIceEvaporation” and “CurrentSurfaceAreaPanAndIce” evaporation methods. Users who have either of these two methods selected or are using this unit type on data objects will need to re-input the correct data into these slots. To identify if your model has slots with unit type, use the slot selector from the main workspace. Select Workspace SlotsOpen Slot to bring up the slot selector. The following screenshot shows the slot selector configured to select slots with this unit type. In the Slot Selector, select the All button in the Object Types column (1) and the All button in the Objects column(2). Then select the slot filter button
(3) and select Slot Unit Type Filter (4). In the pull down menu, select LengthPerTemperature_F (5). Any slots that appear in the slot area (6) have this unit type and must be addressed. Highlight a slot and click Apply or OK to open this slot. If you have slots with this unit type, you will need to re-import or re-enter the data and also make sure any DMIs and/or rules are updated to correctly reference these slots.
(3) and select Slot Unit Type Filter (4). In the pull down menu, select LengthPerTemperature_F (5). Any slots that appear in the slot area (6) have this unit type and must be addressed. Highlight a slot and click Apply or OK to open this slot. If you have slots with this unit type, you will need to re-import or re-enter the data and also make sure any DMIs and/or rules are updated to correctly reference these slots.
General RiverWare
Documentation
The RiverWare help files have been reorganized to be more general and sorted by topic. Additional documentation has been provided on how simulation and rulebased simulation works. Also, accounting documentation is now available.
We recommend using Acrobat Reader 8.1 on Windows or Acrobat Reader 7.0 on Solaris (or later versions) for compatibility with our menus and links. In Reader 8.1, a minor configuration change is necessary to add the “previous” and “next” buttons to the toolbar. Select Tools->Customize Toolbars. A window titled “More Tools” will open. Scroll down to the “Page Navigation Toolbar” section and toggle on the “Previous View” and “Next View” buttons. Select “OK”. These two buttons are useful when following links in the help files. When following a link, the “Previous View” button will return you to the previous document and the “Next View” button can then take you back to the link page.
Searching the online help can be done using the Acrobat Reader Search Utilities.
Batch Mode/RCL
ListSlotDMI command
A new keyword pair was added to the RiverWare Command Language (RCL): SlotListDMI <DMI name> <output file>
This pair writes information about the slots to / from which the DMI imports / exports data; the information is written as comma-separated values to the output file. The information includes:
• The slot’s name.
• The slot’s priority (determined by its dataset association).
• The slot’s begin date “mm-dd-yyyy”.
• The slot’s begin time “hh:mm:ss”.
• The slot’s end date “mm-dd-yyyy”.
• The slot’s end time “hh:mm:ss”.
• The dataset associated with the slot.
• The dataset’s type, currently DSS or HDB.
– If the dataset is DSS, then additional type specific information is written : the DSS path “/A/B/C/D/E/F/”.
More information on this and other RCL keywords can be found in “About RiverWare Command Language” in Automation Tools.
DateTime values in slots
It is now possible to store DateTime values in series, aggregate series, table, and scalar slots on data objects. To store datetimes, a new unit type, DateTime was added. Within this unit type, the user can specify the following either fully or partially specified datetimes (as user units):
• Full DateTime
• Month
• Month and Day
• Time of Year
• Day of Month
• Time of Month
• Time of Day
• Year
To input dates into the slot, the user can either type a DateTime into the slot or use the provided selector and then select apply. The structure of the selector depends on the type of user unit that is specified. The following screenshots show both a slot with a fully specified DateTime and one with a partially specified DateTime showing only the month:
For more information including directions on storing DateTime values in slots, see “DateTime Values in Slots” in User Interface.
Data Management Interface
Database DMIs: HDB connection
There is now the ability to establish a direct data connection between RiverWare and the Hydrologic DataBase (HDB). This connection requires Oracle Client or a full database installation to be available from the user's machine. Data is transferred by creating and configuring HDB datasets in the Dataset Manager and running DMIs containing these datasets. More information on this feature can be found in “HDB Datasets” in Data Management Interface (DMI). This is the alpha release of this feature; the functionality and user interface are still under development.
DMI Import of Periodic Slots
A bug related to units and configuration of a multiple-column periodic slot during importation has been fixed. When importing (and resizing) data via a DMI to a periodic slot, columns other than the first did not have the correct units or configuration. After the table is resized to match the number of underlying table columns on the periodic slot column map, all the columns are set to have the same configuration (including units) as the first.
Multiple Run Management (MRM)
In the MRM consecutive mode, a change was made to allow the user to enter up to 99,999 timesteps instead of the default 99 timesteps.
Units
m3/d
A new flow unit was added to the units file: m3/day. RiverWare displays it as m3/day.
General User Interface Enhancements
Slots
Notes on Series Slots
It is now possible to add notes to values in series slots. These can be used to denote when certain operations start, change, or end. The user can see the notes through a tool tip or by configuring to show a column of notes as shown in the following screenshot.
Further information is given in “Notes on Series Slots” in User Interface.
Slot Adjust Values
One or more values selected in a slot can be adjusted using the “Adjust Values...” item available from the Edit menu of slot dialogs. When the user selects “Adjust Values...” RiverWare opens an Adjust Selected Slot Values dialog which allows the user to provide the amount by which the selected slot values should be adjusted. Values may be adjusted by a percentage, or if all of the values have the same units, by a fixed increment in user units. The user first selects (highlights) the slot values to be adjusted then chooses the “Adjust Values...” option from the Edit menu. In the Adjust Selected Slot Values dialog that appears, the user enters the adjustment value. The user then applies that adjustment value to the selected slot values by selecting the “Ok” button or cancels the adjustment using the “Cancel” button. The dialog automatically closes.
The slot value(s) assure) adjusted by adding a certain amount to the existing slot value(s) or by multiplying the slot value(s) by a percentage. The user may specify a positive or negative quantity. The percentage option adjusts the existing amount by adding a specified percentage of that amount.
For example if the values 10.0 and 100.0 acre-ft/month are selected and the user enters 10 acre-ft/month into the Adjust Slot Values Dialog and selects “Ok”, then the values will be changed to 20.0 and 110.0. If the user enters 10%, the values will be changed to 11.0 and 110.0.
Note that it is easy to select all cells in a column by clicking on the header for that column.
Open Series in SCT
The Open SeriesSlot and Open TableSeriesSlot dialog boxes now support functions to show the series data in a new SCT or add the series data to the single open SCT (enabled only if one SCT is shown).
These functions are accessible from series-data applications of the Open Slot dialog: File SCT Show in New SCT and Add to Open SCT.
Global Time Scroll
A context menu option was added that allows the user to globally scroll the all opened dialogs to a given timestep. On an open slot dialog, the user can right select a timestep in a slot and select Global Time Scroll. Then all open (or previously opened) dialogs that have a timestep will scroll to this timestep. For example, the Model Run Analysis, opened plotting devices, and Open Object dialogs will scroll to that timestep. This operation can be performed from numerous locations in RiverWare including the Open Slot dialog and Model Run Analysis.
Model Run Analysis port to Qt
The Model Run Analysis and its related dialogs were ported to Qt. The dialogs, although similar to the previous version, now have a new look as shown in the following screenshot:
Also noted on the screenshot are some additional features including:
• The objects can be sorted by Name, Type, Position, or Internal order.
• Scroll to Date functionality
• A button to show the Dispatch Details. (This button will open the Dispatch Details in a docked window.)
In addition, the Dispatch Details and List Rules dialogs are now in Qt. These two dialogs can either be shown as stand alone dialogs or docked in the Model Run Analysis as shown in the following rulebased run dialog.
When docked, the dialogs can be separated using the Detach button. When in stand alone mode, the dialogs can be docked from the Dispatch Detail’s File Dock in Model Run Analysis menu. A button is also provided to switch between the Dispatch Dialog and List Rules. Finally, on the Dispatch Detail’s dialog, the Dispatch Methods and Slots view are now on separate tabs.
In the new dialogs:
• “Time on Top” is the only currently implemented configuration
• The font can be changed
• The rules colors can be changed from the color menu
• Pre-simulation and post-simulation timesteps are now shown
On the Model Run Analysis dialog, right-click context menus were added to Show Dispatch Detail, Open the Object, Copy the Time, Global Scroll, and Disable Dispatching.
In the Dispatch Detail dialog, selecting the Object icon brings up the Open Object dialog. Similarly, selecting the icon
brings up the Model Run Analysis and docks the Dispatch Detail.
brings up the Model Run Analysis and docks the Dispatch Detail.Slot Selector Enhancements
A new filter was added to the slot selector dialogs to filter slots by timestep size. Using this filter, the user can specify to show only slots of a given timestep size.
In addition, the selector was enhanced to show and select by the column name in Series Slots, Table Slots and Table Series Slots. This is appropriate and available, for example, in Database DMI Name Maps where the user can select to import column 2 of an Agg Series Slot. To facilitate functionality, a Column Name filter was added to the selector. In addition, a push button was added to highlight “Columns Only” on the selection. The wildcard toggle also works for this type of selection. A “columns only” toggle was added next to the wildcard toggle to specify that in the wildcard selection, only the columns should be selected and not the overall slot. Following is an example of how this could be used: A user configures 5 agg series slots to contain crop water requirements for 10 different crops. (5 slots * 10 columns = 50 timeseries) When creating a name map for use in importing via the database DMI, the user sets the filter to select each of the columns that are labeled “Crop 1” across the multiple slots. The user can then specify that “Crop 1” maps to “corn” in the database Name Map. This enables the user to set up only 10 Name Maps, one for each crop, instead of the 50 that were previously required. Following is a screenshot of the selector showing these new filters.
Timestep size on SCT
An option was added to allow the user to configure the SCT to display slots at a different timestep from the Run Control. For example, an SCT can be configured to show monthly slots within a daily model. Only one timestep size is allowed per SCT, but multiple SCT’s can be configured with different timestep sizes for a given model.
This feature is configured using a new “SCT Timestep Size Override property” found on the General tab of the SCT configuration dialog.
Engineering Methods
This section describes engineering object methods that involve more than one object. The methods for each object are also described in “Simulation Objects”.
Spatial, Temporal, and Incremental Flow Disaggregation
New methods were added to the reservoirs, Control Point, and Computational Subbasins to allow the user to disaggregate flows spatially, temporally, and incrementally as follows.
Spatial disaggregation methods
Two approaches were added to allow flows to be spatially disaggregated throughout a subbasin. The WAM Precipitation Curve Number method uses the Water Availability Model (WAM) method to disaggregate known flows spatially throughout a computational subbasin. It uses the NRCS curve number, mean precipitation, and drainage area along with the known flow at a “gage” control point to calculate the unknown local inflows (Distributed Flow) at all other control points in the subbasin. For more information see “WAM Precipitation Curve Number” in Objects and Methods. The Drainage Area method disaggregates known flows spatially throughout a computational subbasin based on drainage area. For more information see “Drainage Area” in Objects and Methods.
Specified Factors temporal disaggregation method
The Specified Factors temporal disaggregation method takes the Distributed Flow (typically a monthly value in a daily timestep model--though this is user configurable) and temporally disaggregates it to be the same timestep size as the run control. The method multiplies the Distributed Flow by a Temporal Disaggregation Factor to obtain the Temporally Disaggregated Flow. For more information see “Specified Factors” in Objects and Methods.
Calculate Incremental Local Inflows category
In certain basins, local inflow data is input into the model as cumulative values, that is, the local inflows for a given control point or reservoir includes all of the upstream local inflows including water entering upstream objects. Because RiverWare must have distributed data, methods were added to compute incremental local inflows from cumulative local inflow data. Computation of incremental local inflows has two variations to it: with and without forecasting. In the simple case, forecasting is not necessary and the incremental local inflows can be calculated at the beginning of run for all timesteps in that run. In the more complex case, cumulative inflows are forecasted throughout the forecast period, then the forecasted incremental flows are calculated. This forecasting occurs at the beginning of each timestep. To facilitate these two variations, categories and methods were added to the Computational Subbasin, Control Points, Reservoirs, and Confluences.
Users will first need to set up one computational subbasin for each group of control points and reservoirs that contain cumulative local inflow data. The computational subbasin(s) must include all control points and reservoirs containing the cumulative local inflow data as well as all the intervening reaches and confluences. Each control point and reach should only be included in one computational subbasin.
For each computational subbasin, select a method from the Compute Incremental Local Inflows category. This enables the Reservoir Boundary for Incrementals category. If cumulative local inflow data is only cumulative until a reservoir is reached, select the Stop at Reservoirs method. Otherwise, select the Continue Through Reservoirs method if cumulative data continues through reservoirs, or Ignore Reservoirs if there is no cumulative data on reservoirs.
For each control point and reservoir in the computational subbasin several new methods must be selected. In RiverWare, local inflows are called “Local Inflows” on Control Points and “Hydrologic Inflows” on Reservoirs. In this discussion, we will use the terminology Local Inflows exclusively; please substitute Hydrologic Inflows anywhere a reservoir is referenced. First, Select either the Input Local Inflows or Forecast Local Inflows from the Local Inflow Calculation category. Next, select a method from the Calculate Incremental Local Inflows on Subbasin category. Depending on the Local Inflow Calculation, you can either select to calculate incrementals for the Full Run or calculate incrementals and forecast throughout the Forecast Period. For more information, see “Incremental Local Inflows” in Objects and Methods.
Simulation Objects
Reservoir Objects
Flashboard and Superboard Spill methods
In the reservoir flashboards and superboards unregulated spill methods, a check was added to see if the availability slot is input or set by a rule. Previously, the availability was just checked for inputs, not rules. Now, users can set the availability with a rule.
Surcharge Error Check
An error check was added to the Flattop Surcharge method to ensure that the non-zero portion of the Rating Curves is increasing.
Peak Power Equation with Off Peak Spill - Warning message removed
In the Peak Power Equation with Off Peak Spill method on the power reservoirs, the following warning message was removed: “Pool Elevation too low to generate power.” This warning message was posted any time the reservoir was below the Minimum Power Elevation. The method behaves the same as previously: power and energy are still calculated to be zero; only the message has been removed.
Compute Incremental Hydrologic Inflows on Subbasin category
Two new methods were added to reservoir objects in the new Calculate Incremental Hydrologic Inflows on Subbasin category: Compute Full Run Incremental Hydrologic Inflows and Compute Forecast Period Incremental Hydrologic Inflows methods. These methods are used to disaggregate cumulative hydrologic inflows. The first method disaggregates cumulative inflows to Incremental Hydrologic Inflows for the entire run. The second method forecasts and disaggregates cumulative inflows to incremental hydrologic inflows on each timestep throughout the forecast period.
Slot name change: Deterministic Hydrologic Inflow
On reservoir objects, the name of the slot “Deterministic Hydrologic Inflow” was changed to “Cumulative Hydrologic Inflow.” In addition, the forecast methods in the Generate Forecast Hydrology category that previously used the “Deterministic Hydrologic Inflow” slots now use the new “Deterministic Incremental Hydrologic Inflow.”
If you use one of the Generate Forecast Hydrology methods that use these slots, there are two options:
• If you wish to continue using data in the old “Deterministic Hydrologic Inflow” slot in its previous form (either cumulative or incremental), it is recommended that you re-input the data into the new “Deterministic Incremental Hydrologic Inflow” slot. If you do not re-input the data, RiverWare will automatically copy the existing data from the new Cumulative Hydrologic Inflow into the Deterministic Incremental Local/Hydrologic Inflow at the beginning of a run. The data will not have input flags. To see or modify the input data, you would need to select the Compute Forecast Period Incremental Hydrologic Inflow method in the Calculate Incremental Hydrologic Inflows on Subbasin method temporarily. Because of this, it is recommended that you re-input the data into the Deterministic Incremental Hydrologic Inflow slot.
• If you have cumulative flows in the old Deterministic Hydrologic Inflow slot and you plan to disaggregate the flows using one of the new methods, the data should remain in the new Cumulative Hydrologic Inflow slot. You then must select a new disaggregation method in the Calculate Incremental Hydrologic Inflows on Subbasin category on the reservoir and create a subbasin to perform the disaggregation.
In addition, if any of these slots are referenced by DMIs, output manager devices, rules, or expression slots the models will need to be modified. See “Generate Forecast Hydrology” in Objects and Methods for information on the Generate Forecast Hydrology category for the storage reservoir.
Control Point
Variable Routing Coefficients category
A new category, Variable Routing Coefficients was added to the Control Point. Within this category, a new method, Compute Aggregate Coefficients allows the user to specify that this Control Point has an alternative set of routing coefficients that are to be used in the Flood Control calculation. See “Control Point Variable Routing Coefficients category” for more information.
Local Inflow Spatial Disaggregation on Subbasin category
This category has two methods that are used to hold the slots necessary for the calculation of Distributed Flow at an ungaged control point using the known flow at the Gage Control Point on the computational subbasin. In the WAM Precipitation Curve Number method, there are six slots: Distributed Flow, Drainage Area, Curve Number, Mean Precipitation, Upstream Gages, and Downstream Gage. These slots will be accessed by the computational subbasin when executing the computational subbasin’s WAM Precipitation Curve Number method. In the Drainage Area method, there are four slots: Distributed Flow, Drainage Area, Upstream Gages, and Downstream Gage. In both of these methods, the computational subbasin will use the user input Distributed Flow values in the Gage Control Point to calculate and set the Distributed Flow values at all other control points in the subbasin. The WAM Precipitation Curve Number method takes into account the drainage area, mean precipitation and NRCS Curve Number while the Drainage Area method uses only the drainage area in the calculation. For more information, see “Local Inflow Spatial Disaggregation on Subbasin” in Objects and Methods.
Gage Control Point category
A new category, Gage Control Point, was added to the Control Point when the WAM Precipitation and Curve Number method is selected. Methods in this category are used to indicate which Control Points are the “gage” control points. There are two methods in this category: the default, no action None method and the Gage Control Point method. When selected, the Gage Control Point method indicates that the control point is considered a “gage” control point. When this method is selected, the Control Point changes from a blue color to an orange color. For more information, see “Gage Control Point” in Objects and Methods.
Local Inflow Temporal Disaggregation on Subbasin category
A new method category, Local Inflow Temporal Disaggregation on Subbasin, was added to the control point. The Local Inflow Temporal Disaggregation on Subbasin method category contains two new methods: None, and Specified Factors. The Specified Factors method contains one new slot: Temporally Disaggregated Flow. This slot holds the result of the temporal disaggregation as calculated from the computational subbasin. For more information, see “Local Inflow Temporal Disaggregation on Subbasin” in Objects and Methods.
Compute Incremental Local Inflows on Subbasin category
Two new methods were added to control point objects in the new Calculate Incremental Local Inflows on Subbasin category: Compute Full Run Incremental Local Inflows and Compute Forecast Period Incremental Local Inflows methods. These methods are used to disaggregate cumulative local inflows. The first method computes incremental local inflows for the entire run. The second method computes forecasted incremental local inflows on each timestep for the forecast period. For more information, see “Compute Incremental Local Inflows on Subbasin” in Objects and Methods.
Slot name change: Deterministic Local Inflow
On Control Points, the name of the slot “Deterministic Local Inflow” was changed to “Cumulative Local Inflow.” In addition, the forecast methods in the Generate Forecast Inflows category that previously used the “Deterministic Local Inflow” slots now use the new “Deterministic Incremental Local Inflow.”
If you use one of the Generate Forecast Inflows methods that use these slots, there are two options:
• If you wish to continue using data in the old “Deterministic Local Inflow” slot in its previous form (either cumulative or incremental), it is recommended that you re-input the data into the new “Deterministic Incremental Local Inflow” slot. If you do not re-input the data, RiverWare will automatically copy the existing data from the Cumulative Local Inflow into the Deterministic Incremental Local Inflow at the beginning of a run. The data will not have input flags. To see or modify the input data, you would need to select the Compute Forecast Period Incremental Local Inflow method in the Calculate Incremental Local Inflows on Subbasin method temporarily. Because of this, it is recommended that you re-input the data into the Deterministic Incremental Local Inflow slot.
• If you have cumulative flows in the old Deterministic Local Inflow slot and you plan to disaggregate the flows using one of the new methods, the data should remain in the new Cumulative Local Inflow slot. You then must select a new disaggregation method in the Calculate Incremental Local Inflows on Subbasin category on the Control Point/reservoir and create a subbasin to perform the disaggregation.
In addition, if any of these slots are referenced by DMIs, output manager devices, rules, or expression slots the models will need to be modified. See “Generate Forecast Inflows” in Objects and Methods for details on the Generate Forecast Inflows category for the Control Point.
Computational Subbasin
Control Point Variable Routing Coefficients category
Functionality was added to allow the subbasin to use alternative routing coefficients in the Flood Control calculation. A new category called Control Point Variable Routing Coefficients was added to the computational subbasin. In this category are two methods, a default do-nothing No Method, and the new method Compute Aggregate Coefficients. This new Compute Aggregate Coefficients method is used to determine the set of routing coefficients to use for each Control Point in the subbasin. For each Control Point, the method aggregates routing coefficients using the intervening reach routing methods. This allows the Flood Control calculation to make use of variable routing coefficients during high flow events. This calculation is only performed during the Flood Control calculation and does not affect the routing in the simulation objects. For more information, see “Control Point Variable Routing Coefficients” in Objects and Methods.
Multiple downstream-most objects in flood basin
It is now possible to have more than one downstream-most object in a subbasin used by the Flood Control predefined function.
Local Inflow Spatial Disaggregation
A new method category, Local Inflow Spatial Disaggregation, was added to the computational subbasin. The category contains three methods: the default no-action method None, the WAM Precipitation Curve Number, and the Drainage Area method. The WAM Precipitation Curve Number method calculates the Distributed Flow at an ungaged control point using the known flow at the Gage Control Point as well as the NRCS curve number, mean precipitation, and drainage area of both the gaged and ungaged control points. The Drainage Area method calculates the Distributed Flow at an ungaged control point using known flow at the Gage Control Point using drainage area ratios only. For more information, see “Local Inflow Spatial Disaggregation” in Objects and Methods.
Local Inflow Temporal Disaggregation
A new method category, Local Inflow Temporal Disaggregation, was added to the computational subbasin. The category contains two methods: the default no-action method None, and the Specified Factors method. The Temp Disagg Factors slot is required input for the Specified Factors method and holds a daily timeseries of the factors by which the monthly Distributed Flow values are multiplied to temporally disaggregate to daily. In practice, the data for the Temp Disagg Factors slot can be developed from historical daily data that is converted to a daily factor (percent per day of the monthly value). This slot is located on the computational subbasin (and not the control point) because the disaggregation factors apply to all control points in the subbasin. For more information, see “Local Inflow Temporal Disaggregation” in Objects and Methods.
Compute Incremental Local Inflows
A new method category, Calculate Incremental Local Inflows, was added to the computational subbasin. The category contains three methods: the default no-action method None, the Compute Full Run Incremental Local Inflows method, and the Compute Forecast Period Incremental Local Inflows method. The latter two methods calculate the incremental local inflows to all control points and reservoirs in the subbasin given the cumulative local inflows at each object without forecasting and with forecasting, respectively. The computational subbasin(s) must be set up by the user and must include all control points and reservoirs which contain the cumulative local inflow data as well as all the intervening reaches and confluences. Cumulative local inflow data can be either cumulative until a reservoir is reached in the river system or continue through one or more reservoirs. For more information, see “Incremental Local Inflows” in Objects and Methods.
Reservoir Boundary for Incrementals Category
A new category Reservoir Boundary for Incrementals is available if one of the Calculate Incremental Local Inflows is selected. The category contains three methods, the default Stop at Reservoirs, Continue Through Reservoirs, and Ignore Reservoirs. These methods are used to specify how cumulative local inflows are configured in the basin. For more information, see “Reservoir Boundary for Incrementals” in Objects and Methods.
Diversion Object
Change to SolveMB_GivenOutflow dispatch method
On the Diversion object's solveMB_givenOutflow dispatch method, “Available for Diversion” was removed as a required known in the dispatch conditions. This dispatch method solves for the Diversion and Diversion Request given the Multi Outflow. Typically, the Multi Outflow is calculated by a rule using the ComputeReservoirDiversions predefined function. This function determines the reservoir diversion and limits diversions to be less than the available water in the reservoir. As a result, Available for Diversion is not a required known for this dispatch method. For more information, see “solveMB_givenOutflow” in Objects and Methods.
Reach
Base Plus Fractional Loss Method in the GainLoss Calculation Category
A new method Base Plus Fractional Loss was added to the GainLoss Calculation category on the reach. This method models loss in a reach as a base loss plus a loss fraction of the flow above that base. In addition, total loss is limited to a maximum value. For more information, see “Base Plus Fractional Loss” in Objects and Methods.
Variable Step Response routing method
A new routing method, Variable Step Response, was added to the Reach. In this routing method, the user specifies a set of flow thresholds and a set of corresponding step response routing coefficients. When the reach dispatches, the routing method selects the appropriate routing coefficients based on the inflow to the reach. This method was added to support systems where large overbank floods lead to increased travel times. For more information, see “Variable Step Response” in Objects and Methods.
Water User
Fraction Return Flow Input category
A new category called Fraction Return Flow Input was added to the Water User object. This category, dependent on the selection of the Fraction Return Flow method in the returnFlowCalculation category, specifies how the Fractional Return Flow slot is to be input. Within this category are three new methods: Input Fraction, Zero Fraction, and Periodic Fraction. The default method is the Input Fraction which duplicates the existing functionality. The Zero Fraction method sets a zero for Fraction Return Flow each timestep. The Periodic Fraction allows the user to input a periodic slot that is used to calculate the Fractional Return Flow. For more information, see “Fraction Return Flow Input” in Objects and Methods.
RiverWare Policy Language
RPL User Interface
RPL Statements
In RPL set editors, the Rule/Method menu option was improved to only show the types of statements relevant to the given set. In a Ruleset or Object-level Accounting Method set, the following statements can be added: Print, Assignment, ForEach, If, If Else, and Stop Run. The last three statements are new, see “IF and IF ELSE Statements” for more information. In a RPL based Optimization set, the following statements can be added: Soft Constraint, Constraint, Objective, Freeze, If, and If Else.
RPL Palette
Re-use of expressions in sub-expression:
When the user selects a non-empty RPL expression, and then clicks a palette button, RiverWare now does a better job, where applicable, of re-using the existing expression in the first sub-expression. In general, the existing expression becomes the first part in the new expression. So if you have an expression 10 [“cfs”] and you select the <N>+<N> button, the expression becomes 10 [“cfs”] + <N>. In the WITH and GET operators, the selected expression becomes the body of the expression.
Available Palette Buttons:
The palette was improved to better show which buttons are available for a selected expression. In particular, all buttons are disabled when a type/name pair is selected. For example, in a ForEach statement, if the “NUMERIC result” is selected, all palette buttons become disabled. Also, when a binary expression is selected, the correct palette buttons are now enabled.
Functions:
On the palette, the functions are now either shown as available or unavailable to replace the selected expression based on expression type and the function’s return type. Available functions (either predefined or user defined) are shown in dark text, while unavailable functions are shown in a light grey text. The screenshot above shows that the functions that return a NUMERIC are available and the functions that return a LIST are not available. The user can still single click on a function to select it and show the description (user-defined functions only). Double-clicking an unavailable function will give a Paste Error and ask if you would like to continue using this function.
Operations in RPL set editor dialogs
Orange Check Mark:
In the RPL dialogs, an orange check mark was added to policy and utility groups to specify that one or more items in that group is “off” as shown in the following figure. As before, the user can select the orange check to turn “off” the entire group, resulting in a red X. To turn it on again, restoring the previous state and showing an orange check, simply click the red X.
Selecting Red X:
Also, selecting an item’s X in a group that is turned “off” now turns the entire group “on” without making any changes. This prevents the user from inadvertently changing the status of an item in a group that is off only to find that it is now different when the entire group in turned back “on”.
If all individual items in a group are turned off (red X), then the entire group is considered off and the group will also have a red X. If the user clicks on the group’s red X, a warning message will appear to indicate that at least one item in the group should be turned on.
Deselecting a Row:
In the RPL set editor, left-clicking on a row in the listview that was previously selected by left-clicking causes the row to become de-selected. Previously, selecting a selected row had no special significance. Also, there was no reliable and easy way to de-select a row.
RPL Parameters Dialog
A new “RPL Parameters” dialog was added to the Policy menu on the workspace. This dialog allows the users to provide settings and values which affect all applications of RPL. These parameter settings are saved with the model file.
Currently, there are two parameters:
• Collect RPL Set Performance Information: This switch is not new. It has been moved from the Simulation and Rulebased Simulation run parameters dialogs. (Previously, this was accessed from the Run Control View Simulation Run Parameters or Rulebased Simulation Run Parameters.)
• Numeric Comparison Tolerance: This parameter specifies whether or not to use a tolerance value for numeric comparisons in RPL and allows the user to specify the tolerance value.
IF and IF ELSE Statements
It is now possible to add an IF or IF ELSE statement as the uppermost statement in a rule. This is similar to adding an assignment statement. Care should be exercised when using these statements as the left-hand side of the expression can quickly be hidden under multiple layers of logic.
Stop Run Statement
A new Stop Run statement was added to RPL for use as the uppermost statement in a rule. This STOP RUN <expr> statement is accessible from the Rule Add Stop Run menu. When executed, this statement will abort the run and post an error message contained in the specified <expr>. The new Stop Run statement provides functionality allowing a rule to stop a run at the uppermost level. Using the Stop Run statement with the new IF and IF ELSE statement allows a rule to evaluate an expression and stop the run if necessary as shown in the following figure:
The existing STOP_RUN button is still available on the palette. This button should be used within a rule when it is desirable to stop the run inside another statement. The difficulty with this approach is that the expression has to be within an assignment or Print statement. If using a Print statement, then diagnostics have to be turned on to evaluate the Print. This is not the intended use of either the assignment or print statement. The new Stop Run statement avoids having to place the STOP_RUN expression within a Print statement that only evaluates if the user has diagnostics enabled.
Time Invariant Functions
It is now possible to designate a user defined function as being “time invariant”. To indicate that a function does not vary with time, the function editor's Function menu provides a toggle control labelled “Set Time Varying”.
A check mark (on, by default) indicates the function does vary with time. No check mark (off) indicates the function does NOT vary with time. Toggling the check mark off communicates to RiverWare that the function is guaranteed to evaluate to the same value each time it is evaluated, i.e., it is time invariant. Note that functions with arguments will almost certainly not be time invariant; if a function has an argument, then presumably there are some argument values for which the function will evaluate to different values. If a function with no arguments is time invariant, then the first time the function is called within a run the body will be evaluated and the result saved internally. For all subsequent calls of that function within the run, the cached value will be returned without further computation, reducing computation time.
Note that incorrect application of caching to a time varying function will lead to incorrect results, so it is recommend that the time varying property be toggled off for a function only when it is definitely time invariant, run time is critical, and RPL set analysis has indicated that a significant portion of the run is spent evaluating the function. When the function does not vary with time a warning message is added to the bottom of the function editor.
Note: During rule evaluation, the workspace remains unchanged (because RPL expressions evaluate without side effects), so it is safe to cache values for functions without arguments within a single rule. RPL does this automatically for all functions without arguments. Multiple evaluations of such a function within the same rule execution will cause the function to evaluate only once.
RPL Diagnostics
FOREACH diagnostics
A diagnostic was added to the “Rule Execution” category. This message is posted when a FOREACH statement is called. The diagnostic prints the list of values over which the FOREACH statement is iterating.
Modified Predefined Functions
HydropowerRelease
In the HydropowerRelease predefined function, a call is made to determine the maximum proposed power release. This call was modified such that RiverWare does not abort with an error if the Elevation Volume table is exceeded during the mass balance iteration. Instead, the limits of the table are used in the iteration scheme.
SolveOutflowGivenEnergyInflow
The predefined function SolveOutflowGivenEnergyInflow was modified such that RiverWare does not abort with an error if the Elevation Volume table is exceeded during the mass balance iteration. Instead, the limits of the table are used in the iteration scheme.
MeetLowFlowRequirement
The MeetLowFlowRequirement predefined function was incorrectly accessing the current slot values before returning the result to the calling rule. The function was fixed to now add the calculated flow to the current values in the Low Flow Release and Outflow slots.
New General Predefined Functions
DateToNumber and NumberToDate
Two new predefined functions were added that convert between RPL date/times and numeric values which are used to encode those dates in a way appropriate for slots that have the new DateTime unit type.
New Accounting Predefined Functions
AccountAttributes
AccountAttributes(STRING -- “object^account”) returns a list containing the account's attributes, i.e., the account's water type, water owner, and account type of the form {STRING, STRING, STRING}.
ObjAcctSupplyByWaterTypeRelTypeDestType
ObjAcctSupplyByWaterTypeRelTypeDestType(STRING -- subbasin, STRING -- water type, STRING -- release type, STRING -- destination) returns a list of lists each containing an {Object, Account, and Supply}. The function is provided a subbasin (argument 1), a water type (argument 2), a release type (arguments 3) and a destination type (argument 4). The function searches the specified subbasin and finds all of the {Object, Account, Supply} triplets which match the following conditions: the object is in the given subbasin, the returned object^account is served by the supply, and the supplying account (upstream end of the supply) has the given water type, release type, and destination.
ObjectsFromAccountName
ObjectsFromAccountName(STRING -- account name, STRING -- account type) returns a list of the objects that contain an account with the given name and type.
ObjectsFromWaterType
ObjectsFromWaterType(STRING -- water type, STRING -- account type) returns a list of the objects that have an account with the indicated water type and account type.
SourceAccountAndObject
SourceAccountAndObject(STRING -- supply name) returns a list containing the indicated supplies’ source (upstream) account and object of the form {STRING, OBJECT}.
SupplyAttributes
SupplyAttributes(STRING -- supply) returns a list containing the supply's attributes, i.e., the supply's release type and destination of the form {STRING, STRING}.
Accounting
Documentation
Documentation of the Accounting system was added to the RiverWare Help files. See “Accounting Overview” in Accountingfor the help file.
Water Rights Appropriation Solver
A Water Rights Appropriation solver was added to RiverWare. This solver determines how to appropriate natural flows based on the accounts’ priority dates. Further documentation on the methods and predefined functions that constitute this solver can be found in “Water Rights Allocation” in Accounting.
Exchange Balance Dialog Ported to Qt
The Accounting system's Exchange Balance dialog was ported to Qt, providing the general capabilities of the new Open Series Slot dialog for Accounting Slots. A screenshot of the new dialog is shown below. Now the Payback Supply series are also shown as a column on the dialog. The column labels have been generalized and a key has been added to the bottom of the dialog. As a result, there are no long supply names in the column labels. Otherwise, the dialog has the same functionality plus the added functionality that exists in the new implementation of the Qt slots, including better column width management and an information area on the bottom of the dialog.
Synchronizing the Accounting System when Enabling
When enabling Accounting, if there are not yet any accounts defined, the Accounting System’s time range (i.e. the accounting period) and timestep size are now synchronized with the time range and timestep defined on the Run Control.
Opening an Account from the Accounting View
In the Accounting view, when the user double-clicks an Account icon only the account dialog opens. Previously, the Open Object dialog would also appear.
Keyboard Accelerators
The keyboard accelerators, Alt+O and Ctrl+Alt+O are now defined as follows for accounting: Alt+O -- Clear Selected Values, Ctrl+Alt+O -- Clear All Values in the selected Slots.
Clear All Operation on Orphaned Accounts
Generally, an Account MultiSlot can be edited directly only when it has exactly one Supply. This limitation applies to the “Clear Values” menu operation on the Account MultiSlot as well. A new exception to that limitation enables the “Clear Values” menu operation when there are no Supplies on a MultiSlot. This feature is needed only in anomalous circumstances, e.g. as a result of some internal error, when all links (Supplies) are removed, providing a way to completely clear the MultiSlot.
Diversion Account
Return Flow Lag Units Type Change
The units of a diversion account Return Flow Lag slot have changed from TIME to NONE/NOUNITS. The value is interpreted as a number of timesteps in which to lag the Return Flow. Fractional lags are not permitted.
RiverWare will automatically update the unit type on existing models and issue a warning. If the slot has a valid, non-zero value, RiverWare issues another warning to the effect that the user has to convert the value from time to number of timesteps. There is NO automatic conversion from time to number of timesteps. This change applies ONLY to the diversion account Return Flow Lag. Passthrough account lag is unchanged.
Diversion Account Solution Equation
The diversion account solution equations were modified to conserve mass when there is a Return Flow Lag and timestep length is non-constant (e.g. monthly). Now, the equation uses the Diversion, Depletion, and Return Flow as a volume (using the length of the appropriate timestep). The full equations for the Diversion account can be found “Account Solution Equations” in Accounting.
Optimization
Upgrade to CPLEX 10.1
RiverWare’s optimization now uses CPLEX 10.1 and Concert 2.3.
Change in “Convolved” Table Calculation
Nonlinear functions with two variables have the form y = f(x,z). These functions are linearized during optimization in RiverWare where the value of f is held in a table. For example, a Stage Flow Tailwater Table holds tailwater elevation, y, as a function of stage, x, and outflow, z. The table has the structure where the z values (outflow) is repeated while varying the x values (stage). The optimization first estimates a linear function for y as a function of x given an estimated z value. Some linearization methods use a second step to add a linear factor of z to this approximation. Others implicitly assume a constant z variable.
In some cases, such as the Stage Flow Tailwater Table, reversing the roles of the x and z variables in the linearization makes sense. Riverware creates a new “convolved” table to hold the resulting table in these cases. In our example, the resulting table is the Convolved Stage Flow Tailwater Table.
Previously, the convolved table was just a re-ordering of the original table. However, if the x values in the original table do not repeat, the resulting convolved table can be badly structured resulting in poor linearizations and runtime errors.
Now, the calculation of the convolved values first calculates a “full” table where every x value exists for every z. Visually, if the x and z values were viewed in a graph, the full table would appear to be a complete grid of points. The full table of y values is then created by interpolating and extrapolating values in the original table. The table can then be convolved correctly.
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.
3406 | 3588 | 3769 | 3803 | 3889 | 3935 | 3938 |
3940 | 3951 | 3956 | 3965 | 3966 | 4026 | 4047 |
4054 | 4062 | 4086 | 4089 | 4091 | 4092 | 4093 |
4108 | 4109 | 4110 | 4115 | 4120 | 4123 | 4125 |
4128 | 4129 | 4130 | 4131 | 4132 | 4134 | 4135 |
4137 | 4138 | 4139 | 4140 | 4141 | 4142 | 4143 |
4144 | 4147 | 4148 | 4149 | 4150 | 4151 | 4155 |
4156 | 4157 | 4158 | 4159 | 4161 | 4162 | 4163 |
4165 | 4166 | 4167 | 4168 | 4169 | 4170 | 4171 |
4171 | 4171 | 4174 | 4175 | 4176 | 4177 | 4179 |
4180 | 4182 | 4183 | 4185 | 4186 | 4187 | 4188 |
4189 | 4190 | 4191 | 4194 | 4196 | 4197 | 4199 |
4200 | 4201 | 4202 | 4204 | 4205 | 4207 | 4211 |
4217 | 4218 | 4220 | 4222 | 4223 | 4224 | 4225 |
4227 | 4228 | 4229 | 4230 | 4231 | 4234 | 4235 |
4236 | 4237 | 4238 | 4239 | 4240 | 4241 | 4243 |
4244 | 4246 | 4249 | 4250 | 4251 | 4254 | 4256 |
4257 | 4258 | 4262 | 4263 | 4264 | 4265 | 4269 |
4270 | 4276 | 4282 | 4285 | 4287 | 4290 | 4291 |
4293 | 4295 | 4296 | 4297 | 4303 | 4305 | 4306 |
4307 |
Revised: 11/11/2019