skip to main content
Release Notes Version 3.1
Release Notes Version 3.1
Special Attention Notes
• The Accounting calculations in RiverWare are still under development. Accounting should only be used by sponsors directly involved with the development process.
• The Optimization solver is now available to non-sponsors. It is a beta version. Please report any problems to CADSWES. Online documents for optimization will be released soon.
• Rulesets saved in the new release CANNOT be used in older executables. There is no message to warn the user about this. Rulesets saved under previous executables CAN be used with the new release however.
• An annual (yearly) timestep has been added to RiverWare along with the yearly units to support it. Documentation of the development of an annual timestep model and a comparison of its results to the monthly timestep model from which it was derived is available as a link in the sponsor area of the web site.
• It is important that users do not use the Confluence as a bifurcation object. Specifically, the Inflow slot on a Confluence object should not be linked to the Inflow or Return Flow slot on any other object. A bifurcation object is now available in RiverWare.
• The AggDiversionSite object, when using the sequential linking structure, has been modified to divert the diversion requirement as opposed to the Total Diversion Requested. See “AggDiversionSite” under the Simulation Objects section of these release notes for additional information.
Required Model File Updates
Future Value Calculation
Cumulative storage value calculations were added to the calculateFutureValue method in simulation. Old models that perform future value calculations will have to fill in the Marginal Storage Value Table and select the Cumul Stor Value Table Automation method or fill in the Cumul Stor Value Table by hand.
Confluence Used for Bifurcation
Error checking was added to the Confluence to make sure an upstream slot is not linked to another upstream slot (including Return Flow). Models trying to use the Confluence as a bifurcation object will get an error message about this. Old models should use the Bifurcation Object instead.
Additional Error Checking in Rulesets
Bug fixes and code enhancements were made to tighten up error checking in rulesets. Some rulesets may contain errors that were previously not caught. These rulesets will now be unable to load successfully. Diagnostics information will alert the user and specify the specific area in the ruleset that is not valid. One specific case where old rulesets will not load in the new executable is when a slot is referred to in the ruleset that does not exist on the workspace. If the function that contains the slot was not being used, then this error was never being caught. Now the ruleset will not load until the user removes or turns of the function.
Max Outflow and Max Release
The convergence routine used to solve for the maximum Outflow or Release (Turbine Release) has been re-designed to increase robustness. This routine is used whenever the Max Capacity (M) flag is set on Outflow or Release on a reservoir or when using the GetMaxOutflowGivenInflow or GetMaxReleaseGivenInflow rules functions. The nature of the convergence routine is such that the maximum and minimum possible pool elevations for the reservoir are computed in order to bracket the solution. This could effect old model files by causing a table interpolation error if the maximum or minimum pool elevation falls outside of the range given in table slots. This problem is remedied by adding additional data to the table slots that cause the problem. It is possible that the pool elevation values are not realistic values in respect to the physical system (i. e. a pool elevation that is below the bottom of the reservoir). Since these calculations are only performed to bracket the final solution, they are not recorded and will not affect the model results. The new convergence technique may require more iterations before converging. The value in the Max Iterations slot may have to be increased if the user notices a brown warning message which states, “An internal iterative loop reached the maximum iterations of ‘(value in Max Iterations slot)’ when solving for ‘(Outflow or Release)’”. Increasing the value to 40 should be sufficient.
CRSSEvaporationCalc
Two evaporation method changes were made in conjunction with adding the annual timestep. The CRSSEvaporationCalc method in the Evaporation and Precipitation category has been renamed MonthlyEvaporationCalc and a new method, SingleEvaporationCalc, has been added. For both methods, the associated evaporation coefficients are now in units of length/time (velocity). Previously, the Evaporation Coefficients slot used in the CRSSEvaporationCalc method used units of length. Old model files will update automatically for the new units, but rulesets that contain hardwired units for the evaporation coefficients will fail with an illegal unit conversion error and will need to be updated manually.
Energy Cannot be Input with Max Capacity Outflow
If the Max Capacity (M) flag is set on the Outflow slot on a reservoir, then the Energy slot cannot be set as input. Previously this was not considered an error. If a model has this combination of inputs the user will get the following error when running the model in the new release: “Cannot compute Maximum Capacity Outflow when Energy is input.”
Account Carryover Methods
The account carryover methods were moved from the object level to the account level. This means that a carryover method will have to be selected for each storage account as opposed to each reservoir object. Accounting models that were using carryover will have to be modified by selecting the appropriate carryover method on each account. The default method sets carryover to zero.
General RiverWare
Enhancements to the SCT (Simulation Control Table)
Several enhancements were made to the SCT dialog.
1. Toggling Row Detail is activated by double-clicking on the row or by pressing Alt-D with the row selected.
2. The user may now page up and down through the SCT using the Page Up and Page Down buttons. Paging left and right through the SCT is accomplished by Control-Shift-Left/Right Arrow.
3. Arrow-key navigation around the SCT cells is possible by Control-arrow keys.
4. The user may now Copy and Paste rectangular regions, rows, and columns by using the Edit menu items or by Control-C (copy) and Control-V (paste). Copy/Paste does not paste summary type or units information.
Annual Timestep
An annual (yearly) timestep has been added to RiverWare along with the yearly units to support it. Documentation of the development of an annual timestep model and a comparison of its results to the monthly timestep model from which it was derived is available as a link in the sponsor area of the web site.
“--norun” Command Line Option
When invoking RiverWare with the --norun (that’s two “-” symbols), RiverWare will load with the Start and Step buttons in the Run Control dialog disabled. This prevents the user from running the model. This was developed for a situation where the model developers wanted to be able to show the model to stakeholders without allowing them to actually perform a run. To invoke RiverWare with this option type the following at the command line prompt:
> riverware --norun
Multiple Run Management
The multiple run management functionality was enhanced to enable Simulation runs to automatically follow Optimization runs. This allows Optimization models to be run in the Consecutive mode. This means that an Optimization run is executed for a given time period followed by a Simulation run for that same time period. The Simulation run uses information from Optimization and also provides the initial conditions for the next Optimization run, which is performed for the following run period (as defined by the user). Also, various bugs were fixed to improve the overall functionality of the Consecutive mode of multiple run management.
Table Slot Enhancement
Table slots now show the full row labels. Previously, the labels were truncated to 14 characters.
Simulation Objects
The following enhancements to the RiverWare simulation objects are described briefly. The user is encouraged to consult the Simulation Objects Documentation in the online help for more detailed descriptions of the enhancements to the objects and their methods.
AggDiversionSite
Sequential Linking Structure Changes
The sequential AggDiversionSite has been modified to divert the diversion requirement as opposed to the Total Diversion Requested. The diversion requirement is the minimum flow rate required to satisfy the Diversion Requested of all Water User elements without resulting in a shortage. This calculation uses the Outgoing Available Water from upstream elements (if it is not linked elsewhere) to determine the amount of water required to meet the request of the downstream element. This differs from the previous calculation which simply diverts the sum of the Diversion Requested for all the elements. This calculation would normally divert more than is required and would result in a larger value for Total Unused Water.
This change could affect model files that use sequential AggDiversionSite objects with multiple Water User elements. Differences in output would occur in the Diversion slot as well as the Total Unused Water slot on the AggDiversionSite. If the diversion point and the return flow point (linked to Total Unused Water) are on different objects, then the amount of water between these two point will also be different than previous results.
Reach
Seepage Calc Methods
Three new methods were added to the Seepage Calc category: Horizontal Gradient Seepage, Vertical Gradient Seepage, and Horizontal and Vertical Gradient Seepage. These three methods are used to model seepage from a reach to the groundwater or an adjacent drainage channel based on the hydraulic gradient and the hydraulic conductivity of the surrounding medium. Darcy’s law is used to compute the seepage value. The horizontal seepage methods are designed to model drainage channels that run parallel to the reach. The drains may act as a source or sink to the reach depending on whether the water surface elevation in the drain is higher or lower than that in the reach. The method is flexible enough to allow for multiple drains. The vertical methods are designed to model seepage to groundwater below the reach. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.
Pre-simulation Dispatching for Impulse Response Reaches
Modifications were made to the Reach object to allow pre-simulation dispatching when the impulseResponseRouting method is selected in the routing method category.
Bifurcation Object
A Bifurcation Object is now available on the object palette. The functionality of this object is similar to that of an upside down Confluence. There are only three slots associated with the Bifurcation Object: Inflow, Outflow1, and Outflow2. When two of the three slots are known the object dispatches to solve for the third. There are no user methods available for this object. Detailed documentation of the Bifurcation Object may be found in the Simulation Objects Documentation online.
Reservoir Objects
MonthlyEvaporation Calc
The CRSSEvaporationCalc method in the Evaporation and Precipitation category has been changed to MonthlyEvaporationCalc. The 12 Evaporation Coefficients (1 per month) entered by the user were changed to units of Velocity instead of Length. This allows the method to be used for any timestep (except yearly). The change in unit type takes place automatically when old models are loaded into the new release. Rulesets that contain hardwired units for the evaporation coefficients will fail with an illegal unit conversion error and will need to be updated manually
SingleEvaporation Calc
A new method, SingleEvaporationCalc, has been added to the Evaporation and Precipitation category. This method uses a single evaporation coefficient (in units of length/time) to represent the average rate of evaporation. Therefore, it can be used with any timestep. Detailed documentation of this method may be found in the Simulation Objects Documentation online.
Monthly Spill Calc
A Bypass slot was added to the monthlySpillCalc method in order to model spike flows. A spike flow must be entered into the Bypass slot to prevent it from being distributed to the turbine release over the month. Detailed documentation of this method may be found in the Simulation Objects Documentation online.
Max Flag on Outflow or Release
The convergence routine used to solve for the maximum Outflow or Release (Turbine Release) has been re-designed to increase robustness. This routine is used whenever the Max Capacity (M) flag is set on Outflow or Release (Turbine Release) on a reservoir. The nature of the convergence routine is such that the maximum and minimum possible pool elevations for the reservoir are computed in order to bracket the solution. This could effect old model files by causing a table interpolation error if the maximum or minimum pool elevation falls outside of the range given in table slots. This problem is remedied by adding additional data to the table slots that cause the problem. It is possible that the pool elevation values are not realistic values in respect to the physical system (i. e. a pool elevation that is below the bottom of the reservoir). Since these calculations are only performed to bracket the final solution, they are not recorded and will not affect the model results. The overall result of the new convergence technique is increased robustness so that the method now converges in cases where convergence was not possible previously. However, more iterations may be required before convergence is reached. The value in the Max Iterations slot may have to be increased if the user notices a brown warning message which states, “An internal iterative loop reached the maximum iterations of ‘(value in Max Iterations slot)’ when solving for ‘(Outflow or Release)’”. Increasing the value to 40 should be sufficient.
Future Value Calculations
The Spilled Energy Calculation methods were replaced by the methods in the FutureValueCalcCategory. The methods in this category are used to determine the future value of the energy that would have been generated by the water that was lost through the spillway. The noFutureValueCalc method is the default method for this category. No calculations are performed by this method and no slots are specifically associated with it. The calculateFutureValue method should be selected if the user wishes to perform these calculations. Detailed documentation of this method may be found in the Simulation Objects Documentation online.
Cumulative Storage Value Table Automation
This category allows the RiverWare simulation to automate the creation of the Cumulative Storage Value Table (used in the calculateFutureValue method). This category is only visible if calculateFutureValue is selected in the FutureValueCalcCategory. Two methods are contained within this category, None and Marginal Value to Table. The None method is the default and performs no calculations. If the other method is selected, the Marginal Storage Value Table will be used as the source for the generation of the Cumulative Storage Value Table. This is the only calculation associated with this method and there are no slots specifically associated with it. Detailed documentation of this method may be found in the Simulation Objects Documentation online.
Pumped Storage Reservoir
Pump and Release Accommodation
A new method category, Pump and Release Accommodation, was added to the Pumped Storage Reservoir object. This category contains two methods: Pump or Release Only (the default method), and Pump and Release. These methods perform no calculations and are only used as dependencies for the dispatch methods. A new dispatch method, solveMB_givenPumpedFlowOutflowInflow is available when the Pump and Release method is selected. The method checks the Pumped Flow and Outflow values to determine which one is zero. If Pumped Flow is zero, the solveMB_givenOutflowInflow method is executed. Conversely, if Outflow is zero, the solveMB_givenPumpedFlowInflow method is executed. These new methods will not change the outcome of any pumped storage calculations. They are used to allow both Pumped Flow and Outflow to be input to assist the optimization calculations (specifically, to avoid problems when running a post-optimization simulation run).
Thermal Object
Hydro Block Calculation
For both Optimization and Simulation, the Hydro Block calculations are now done based on the same period of time as the model timestep. Previously, in Simulation, the Hydro Block calculations were done on an hourly basis. This is no longer the case and therefore all hourly Hydro Block information has been removed. The “Opt” portion of the name of the remaining Hydro Block slots has been removed because they now apply to both Optimization and Simulation.
Allocated Preferred Customer
A Preferred Customer method was added to this method category on the Thermal Object to allow the user to subcontract energy that goes to a preferred customer before calculating the avoided costs from hydropower. This method is available for both Simulation and Optimization.
Rulebased Simulation
Model Run Analysis Information
RiverWare now has the ability to save and load the Model Run Analysis Data. This option is automatically activated when Save Run Results (Output Values) is selected when saving a model. When the model is subsequently loaded, the user may view this information (located in the Model Run Analysis -- Rulebased Simulation dialog) without running the model first.
Yearly Units for Rule Expressions
Annual units are now available for use in rule expressions. RiverWare takes into account whether the year is a leap year or not when converting to standard units.
Function Type Name Change
Internal Function and External Function
The menu items for adding a function to a ruleset have changed. Previously, a function was added to a policy group by selecting Ruleset Add Internal Function if the user wanted to create a function in the RiverWare rule language or Ruleset Add External Function if the user wanted to create a function using the Tool Command Language (Tcl). The menu items have been changed to Ruleset Add Function and Ruleset Add Tcl Function, respectively.
Predefined Function Modifications
All predefined functions are described in detail in the Rulebased Simulation Documentation online.
GetMaxOutflowGivenInflow and GetMaxReleaseGivenInflow
The convergence routine used to solve for the maximum Outflow or Release (Turbine Release) has been re-designed to increase robustness. This routine is used for the GetMaxOutflowGivenInflow or GetMaxReleaseGivenInflow rules functions. The nature of the convergence routine is such that the maximum and minimum possible pool elevations for the reservoir are computed in order to bracket the solution. This could effect old model files by causing a table interpolation error if the maximum or minimum pool elevation falls outside of the range given in table slots. This problem is remedied by adding additional data to the table slots that cause the problem. It is possible that the pool elevation values are not realistic values in respect to the physical system (i. e. a pool elevation that is below the bottom of the reservoir). Since these calculations are only performed to bracket the final solution, they are not recorded and will not affect the model results. The overall result of the new convergence technique is increased robustness so that the method now converges in cases where convergence was not possible previously. However, more iterations may be required before convergence is reached. The value in the Max Iterations slot may have to be increased if the user notices a brown warning message which states, “An internal iterative loop reached the maximum iterations of ‘(value in Max Iterations slot)’ when solving for ‘(Outflow or Release)’”. Increasing the value to 40 should be sufficient.
NetSubBasinDiversionRequirement
The NetSubBasinDiversionRequirement function has been enhanced. The method now includes Seepage and GainLoss effects (on reach objects) in the diversion requirement calculations. Also, Water User requests are now included in the diversion requirement.
SolveSubBasinDiversions
This is a new predefined function that performs the same calculations as NetSubBasinDiversionRequirement. However, this function also calculates the outflow at the bottom of the subbasin that results from the calculated diversion requirement. The function returns a LIST of two variables where the first is the diversion requirement and the second is the resulting outflow.
Predefined Functions
Four predefined functions have been added to the Rulebased Simulation Palette. The new functions, as well as all of the existing functions, are described in the Rulebased Simulation Documentation online. Following is a list of new predefined functions:
GetMinSpillGivenInflowRelease (OBJECT, NUMERIC, MUMERIC DATETIME)
This function evaluates to the minimum spill from a StorageReservoir, LevelPowerReservoir, or SlopePowerReservoir with the given inflow and release at the specified timestep. The OBJECT argument is the reservoir on which to perform the calculations, the first STRING is the average inflow into the reservoir over the timestep, the second STRING is the average release from the reservoir over the timestep and the DATETIME is the timestep at which to perform the calculations.
SolveShortage (OBJECT, NUMERIC, DATETIME)
This function is used to solve for the shortage on an AggDiversionSite or a Water User object. It returns a LIST of two NUMERIC values where the first value is the diversion shortage and the second is the depletion shortage. The OBJECT argument is the object on which to perform the calculations, the NUMERIC argument is the water available for diversion, and the DATETIME is the timestep at which to perform the calculations.
SolveSubBasinDiversions (LIST, DATETIME)
This function performs the same calculations as the NetSubBasinDiversionRequirement function. This function differs, however, in the fact that it returns a LIST of two NUMERICS. The first NUMERIC is the diversion requirement and the second is the resulting outflow at the bottom of the subbasin.
SumAccountSlotsByWaterType (OBJECT, STRING, STRING, DATETIME)
This function sums the values of all accounting slots of a given name on accounts of a given water type. The OBJECT represents the object on which the accounts exist, the first STRING is the water type, the second STRING is the name of the slots to sum, and the DATETIME is the timestep at which to perform the summation.
Important Bug Fixes
Copy/Paste in ForEach Statements
Several bugs were fixed (2430, 2454, 2455) to enable copying and pasting within a ForEach statement. A complete list of the bugs closed for this release is given under the Closed Bug Reports heading at the bottom of the release notes.
Copy/Paste of Parenthesized Expressions
Several bugs were closed to fix the copying and pasting of expressions in parenthesis (2388, 2389, 2391). A complete list of the bugs closed for this release is given under the Closed Bug Reports heading at the bottom of the release notes.
Optimization
General Enhancements/Fixes to Optimization
• Checks were added for errors returned from CPLEX function calls. Diagnostics will now be able to notify the user of errors and warnings that occur in CPLEX functions.
• The default value of minimax optimally was changed from 1x10-3 to 1x10-6.
• A new function was added to check approximation quality for both 2pt-line and piece wise calculations.
• The behavior of the Pumped Storage Reservoir is now consistent with the other reservoir objects when it is included in the No Opt Subbasin. This means that the Opt In column for Outflow and Pumped Flow is used to estimate flows which will affect optimized objects. These values are NOT used in simulation. The assumption is that the operation will be set using some combination of simulation columns. Alternatively, Outflow and Pumped Flow could just be entered as inputs in the simulation column.
• A function was added to add up individual spill requirements and put them in the Spill Opt In column. These values are used as lower bounds on Spill.
• An additional row was added to the Total Values slot. The row contains the simulation value of the optimization objective, which is the avoided cost plus the cumulative value of storage. This value is also reported to the diagnostics window.
• The marginal cost calculations were changed. If a unit or block exactly covers the load or generation then the marginal cost reported is the next unit or block that would be used.
Smooth Energy Calculations
Purpose
The smooth energy calculations were developed to deal with the way optimization handles energy production among reservoirs. The current optimization finds extreme points of an optimal region, where the production of energy is moved from reservoir to reservoir and from timestep to timestep in a disjoint manner. An example of this problem is the following simple matrix:
 
 
Timestep 1
Timestep 2
TOTAL
Reservoir 1
10
0
10
Reservoir 2
0
20
20
TOTAL
10
20
 
In most practical cases, the energy demands at every timestep are almost constant, and the energy supply from every reservoir is also almost constant over the run. There are many ways to allocate the energies, but this extreme case is not good. Instead, it is desirable that a smoother energy allocation is found, where each reservoir at each timestep contributes a proportionate amount to satisfying the demand.
Results
Ideally, the energy at each reservoir for each timestep will have a policy constraint at a priority p which is directly after the max avoided cost objective. The following constraint can be written to result in “smoothed” energy values:
(30.1)    
The constraint defined by equation 1 is written for some t, where Ep is the energy (actual variable) at the subscripted reservoir and timestep,
(30.2)    
where Ep-1 is the resultant energies from the last priority level, and the r subscript is constant,
(30.3)    
where Ep-1 is the resultant energies from the last priority level, and the t subscript is constant and
(30.4)    
Equation 1 is a simplified constraint and does not include any flexibility terms. However for the simple example in Table 1, Equation 1 can be applied to get the following results:
 
 
Timestep 1
Timestep 2
TOTAL
Reservoir 1
10/3
20/3
10
Reservoir 2
20/3
40/3
20
TOTAL
10
20
 
example for row 1, column 1:
(30.5)    
The optimization will attempt to get as close to the results in Table 2 as possible. In the case where there may be flexibility terms, the total values are allowed to vary slightly.
Policy Constraints
Because the interface to the user is the constraint editor, the trigger for the creation of the constraints listed above must be simple. This is done through the use of a special subbasin name, Smooth Energy Reservoirs, to which users will add the reservoirs used in the smooth energy calculations. Then, the user will write a single policy constraint: for [t in time by <slot>, ThermalObject.Energy Result[t] = ThermalObject.Smooth Energy[t]]
This constraint will be replaced with a constraint for each of the reservoirs for each timestep. The slots referenced in the user constraint above will be slots that are flagged as linearized variables. The Energy Result slot will be ignored while linearization of the Smooth Energy will trigger the writing of all the physical and policy constraints.
Closed Bug Reports
Bug Fixes
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.
 
845
1153
1480
1513
1733
1862
1864
1866
1869
1874
1876
1882
1899
1976
1990
1998
2032
2067
2071
2144
2146
2175
2185
2188
2190
2245
2253
2255
2259
2270
2274
2276
2277
2283
2301
2308
2327
2331
2363
2368
2370
2376
2378
2387
2388
2389
2390
2391
2393
2394
2395
2396
2401
2404
2406
2407
2410
2412
2415
2416
2417
2420
2422
2423
2426
2428
2429
2430
2431
2435
2436
2438
2443
2446
2447
2449
2450
2451
2453
 
 
 
 
 
 
Revised: 06/03/2019