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.

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.

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.

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.

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.

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.”

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.

Several enhancements were made to the SCT dialog.

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.

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:

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 slots now show the full row labels. Previously, the labels were truncated to 14 characters.

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.

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.

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.

Modifications were made to the Reach object to allow pre-simulation dispatching when the impulseResponseRouting method is selected in the routing method category.

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.

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

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

All predefined functions are described in detail in the Rulebased Simulation Documentation online.

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.

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.

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.

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.

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.

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.

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:

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.

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:

The constraint defined by equation 1 is written for some t, where Ep is the energy (actual variable) at the subscripted reservoir and timestep,

where Ep-1 is the resultant energies from the last priority level, and the r subscript is constant,

where Ep-1 is the resultant energies from the last priority level, and the t subscript is constant and

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:

example for row 1, column 1:

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.

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.

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.