skip to main content
Release Notes Version 3.2
Release Notes Version 3.2
Special Attention Notes
• The Accounting calculations in RiverWare are now available to non-sponsors. The User Defined Accounting Methods (discussed in the Accounting section of the release notes) allow users to write methods that move physical water into accounts and apply physical gains/losses to the accounts.
• 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.
• Adobe Acrobat Reader is no longer included in the RiverWare Core Product file. This means that Acrobat Reader is not installed with RiverWare any longer. This probably won’t affect most users because Adobe is most likely installed on your system already. If your system does not have Adobe, you will need to install it. The RiverWare Download Page has a link to the version of Acrobat used by CADSWES. You can also get a more recent version by visiting the Adobe web site. The Download Guide and Installation Guide on the CADSWES web site provide additional information.
• The Tool Command Language (Tcl) that was previously used to write Rules was upgraded to version 8.2.3. The previous version of Tcl we were using was over six years old. It was necessary to upgrade to a recent version that is compatible with Windows NT. Our nightly regression test showed some model differences as a result of this upgrade. We believe these differences to be a result of a difference in the level of precision used in the two versions of Tcl. In one case, however, there was a syntax error in a Tcl function that was not detected by the old Tcl but was detected by version 8.2.3. In this case, the model aborted and a diagnostic message pointed the user to the exact location of the Tcl error. If your model still uses Tcl functions, it is possible that you will encounter minor differences in model run results. These differences should be less than the convergence level (0.01%) and should not affect the policy outcome. It is also possible that your Tcl functions have syntax errors that were not detected by the previous version of Tcl and are now noticed by 8.2.3. If this is the case, your Tcl function will need to be fixed.
• Additional error checking was added to the PeakPowerCalc and PeakBasePowerCalc methods. The new errors enforce a positive peak flow volume (computed as Outflow - Spill - Base Flow, converted to a volume). A negative peak flow volume would result in the computation of negative Power and Energy values. This situation would occur whenever the Outflow is less than the sum of the Spill and Base Flow. According to Dr. Terry Fulp this is an error situation that should result in the run aborting with an error message notifying the user. This may occur if there was an error in the Maximum Controlled Release value or, more likely, if the Base Flow value is too great. One of our CRSS regression tests aborted with this error so it is highly likely that some CRSS models contain this error and will now abort with the new release. In this case the user must decide upon a new Base Flow value (set in the Base Flow Table slot), that will not exceed the Outflow. The error produced in this situation will read, “Negative peak flow volume calculated. Spill + base flow cannot be greater than outflow. Check Max Controlled Release slot and/or base flow values.” The left hand side of the diagnostics window will give the object and timestep on which this occurred (this occurred on Lake Havasu in our regression tests). The model must be fixed by reducing the value in the second column of the Base Flow Table. Contact Terry Fulp if questions arise about the appropriate value for Base Flow.
• A new slot, Power Capacity, was added to the PeakPowerCalc and PeakBasePowerCalc methods. Previously, the power capacity was being computed and set in the Power slot. Now the Power Capacity slot will contain this value and the Power will represent the Power actually produced on a given timestep. This is discussed further in the Simulation Objects section of the release notes.
Required Model File Updates
Error Checking in PeakPowerCalc and PeakBasePowerCalc
Additional error checking was added to the PeakPowerCalc and PeakBasePowerCalc methods. The new errors enforce a positive peak flow volume (computed as Outflow minus Spill minus Base Flow, converted to a volume). A negative peak flow volume would result in the computation of negative Power and Energy values. This situation would occur whenever the Outflow is less than the sum of the Spill and Base Flow. According to Dr. Terry Fulp this is an error situation that should result in the run aborting with an error message notifying the user. This may occur if there was an error in the Maximum Controlled Release value or, more likely, if the Base Flow value is too great. One of our CRSS regression tests aborted with this error so it is highly likely that some CRSS models contain this error and will now abort with the new release. In this case the user must decide upon a new Base Flow value (set in the Base Flow Table slot), that will not exceed the Outflow. The error produced in this situation will read, “Negative peak flow volume calculated. Spill + base flow cannot be greater than outflow. Check Max Controlled Release slot and/or base flow values.” The left hand side of the diagnostics window will give the object and timestep on which this occurred (this occurred on Lake Havasu in our regression tests). The model must be fixed by reducing the value in the second column of the Base Flow Table. Contact Terry Fulp if questions arise about the appropriate value for Base Flow.
Upgrade to Tcl 8.2.3
The Tool Command Language (Tcl) that was previously used to write Rules was upgraded to version 8.2.3. The previous version of Tcl we were using was over six years old. It was necessary to upgrade to a recent version that is compatible with Windows NT. Our nightly regression test showed some model differences as a result of this upgrade. We believe these differences to be a result of a difference in the level of precision used in the two versions of Tcl. In one case, however, there was a syntax error in a Tcl function that was not detected by the old Tcl but was detected by version 8.2.3. In this case the model aborted and a diagnostic message pointed the user to the exact location of the Tcl error. If your model still uses Tcl functions, it is possible that you will encounter minor differences in model run results. These differences should be less than the convergence level (0.01%) and should not affect the policy outcome. It is also possible that your Tcl functions had syntax errors that were not detected by the previous version of Tcl and are now noticed by 8.2.3. If this is the case, your Tcl function will need to be fixed.
Minimum Efficiency Slot on the Water User
The Minimum Efficiency slot on the Water User object was changed from a Table Slot to a Series Slot. RiverWare automatically extends the time series range on this slot to match the Run Control Dialog. The single value held in the Table Slot is copied to every timestep in the series. So every model should be updated automatically to use the single table slot value for every timestep in the run. However, if the run dates of the model are changed, values for Minimum Efficiency must be input for the new timesteps. This can be done by hand or preferably through a DMI. If your DMI moves the timestep of your model ahead, then it should be modified to add data to the Minimum Efficiency slot. Another approach would be to extend the timeseries range on the Minimum Efficiency slot to include a very large number of timesteps. Then a value could be input on every timestep using the Fill Values command. This will work as long as the time series is expanded to encompass any possible run period.
(Variable) GainLoss Coefficient Restriction
The GainLoss Coefficient (or Variable GainLoss Coefficient) is no longer allowed to be -1.0 when a reach is solving upstream. A GainLoss Coefficient of -1.0 means that 100% of the Inflow to the reach is lost. When solving upstream given an Outflow value, it is impossible to determine a unique Inflow value if the GainLoss Coefficient is -1.0. Basically, an infinite number of Inflows could result in the given Outflow because 100% of it is lost before getting to the Outflow. RiverWare now detects this situation and flags an error when it occurs. Models that contain reaches that solve upstream and have a GainLoss Coefficient of -1.0 will abort when run in the new release. The GainLoss value must be changed to any number that is greater than negative 1.0.
General RiverWare
Printing an SCT (Simulation Control Table)
Menu options have been provided for printing a selection, the current page, or the entire SCT. Previously, if any cells were selected when the Print Portrait menu item was selected, the pages starting with the selection were printed and, if no cells were selected, the entire SCT was printed (printing the current page was not supported at all).
File Chooser Width
A fix was made to the RiverWare 3.1.1 patch release that forced the File Chooser dialog to open at the maximum possible single column width. Prior to this fix, if the user expanded the width of the File Chooser, it would expand to several small columns instead of one wide column. This was a problem when trying to view long file names. The File Chooser dialog was not wide enough to view the entire length of the file name. The fix made to RiverWare 3.1.1 corrected this problem but it introduced another problem that is dependent upon the user’s system. If the maximum File Chooser width is too large, a Galaxy (windows software used in RiverWare) bug would occur that causes RiverWare to crash with a floating point error as soon as the File Chooser is opened. Because this is system dependent, we removed the code that fixed the original problem. Now the File Chooser defaults to the original size and long file names may not be entirely visible. However, an environment variable called RW_FILECHOOSERWIDTH was created so the user can set the maximum file chooser width if it is not large enough to view the entire file name. The bug fix for RiverWare 3.1.1 was using a value of 255. This was large enough to view long file names but it produced the Galaxy core dump on some systems. The user must experiment with the maximum value for RW_FILECHOOSERWIDTH as it applies to his/her system. This number can vary anywhere from about 150 up to 400.
Model file vs. DMI Precision
Previously, if TVA ran DMIs, ran the optimization, saved the model, reloaded the model, and reran optimization, the solutions would be different. We have reduced the precision of DMI imports to the precision saved in model file and expect this to eliminate such differences. This is not testable at CADSWES and is essential for TVA to test.
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.
Water User
Multiple Split Return Flows
A new method, Multi Return Fractional Split, is available in the returnFlowSplitCalculation category. This method allows the user to split the Return Flow and send it to as many destinations as is necessary. In other words, a single Water User can be used to model an areas with similar characteristics that may produce more than one return flow. Each return flow can be linked to a different destination in the model. When this method is selected, the Returned Flows multislot is added. This slot can be linked to the Return Flow (or any other series slot) on several different reaches. When a link is created to this slot, a column representing this link is added to the necessary input table slots. This allows the user to have any number of return flows and data only needs to be given for those return flows that are specified by a link to the Returned Flows slot. Information regarding the use of this method is available in the Simulation Object Documentation online.
Return Flow Routing
A new method category called Return Flow routing is available on all Water User objects. The methods available in this category are dependent upon the method selected in the returnFlowSplitCalculation category. Three methods are available to route the either the return flow, the surface or ground water return flows, or any of the multiple split return flows. The impulse response method is the only routing calculation that is used for return flows. If the user needs to route return flows using a method other than impulse response, a separate Reach object must be used. Information regarding the use of the Return Flow Routing methods is available in the Simulation Object Documentation online.
Split Return Flow Fraction/Efficiency
Since the Multi Return Fractional Split method has been added to the returnFlowSplitCalculation category, the previously existing two categories were renamed so that it is apparent that these methods are used to split between surface and groundwater returns. Therefore, Split Return Flow Fraction and Split Return Flow Efficiency have been renamed SW GW Fractional Split and SW GW Efficiency Split, respectively.
Minimum Efficiency Slot
The Minimum Efficiency slot on the Water User object was changed from a Table Slot to a Series Slot. RiverWare automatically extends the time series range on this slot to match the Run Control Dialog. The single value held in the Table Slot is copied to every timestep in the series. So every model should be updated automatically to use the single table slot value for every timestep in the run. However, if the run dates of the model are changed, values for Minimum Efficiency must be input for the new timesteps. This can be done by hand or preferably through a DMI. If your DMI moves the timestep of your model ahead, then it should be modified to add data to the Minimum Efficiency slot. Another approach would be to extend the timeseries range on the Minimum Efficiency slot to include a very large number of timesteps. Then a value could be input on every timestep using the Fill Values command. This will work as long as the time series is expanded to encompass any possible run period.
Minimum Diversion Request
A new slot, Minimum Diversion Request, has been added to all methods in the Diversion and Depletion Request category. If the user has input a value on this slot, the Diversion and Depletion Request methods will make sure that the calculated Diversion Request is at least the Minimum Diversion Request. If however, the calculated Depletion Request is zero, this slot is not used and the Diversion Request is set to zero. The use of this slot is optional.
Reach
Impulse Response Slot Reconfiguration
The Lag Coeff slot was reconfigured to display the lag coefficients in rows rather than columns. This happens automatically and should not affect model results.
Evaporation Category
A new Evaporation Calculation category is available on the Reach object. This category is only available when noRouting is selected in the routing method category. The evaporation category contains a default method, which does nothing, and an Inflow Exponent Pan Evap method. This method computes evaporative loss from the reach based on an empirical equation that uses the Inflow raised to an exponent and a pan evaporation coefficient. Details on the specifics of the equation are available in the Simulation Objects Documentation online.
Reach Bank Storage Calculation
Previously, when computing the Bank Storage Return for the first few timesteps, a Routed Flow of zero was used for those timesteps prior to the Start timestep. This was causing volume conservation problems so the method was modified to assume a constant value for Routed Flow, prior to the Start timestep, that is equal to the first calculated value for Routed Flow. However, if the user has input Routed Flow values prior to the Start date, these will take priority and will not be reset.
(Variable) GainLoss Coefficient
The GainLoss Coefficient (or Variable GainLoss Coefficient) is no longer allowed to be -1.0 when a reach is solving upstream. A GainLoss Coefficient of -1.0 means that 100% of the Inflow to the reach is lost. When solving upstream given an Outflow value, it is impossible to determine a unique Inflow value if the GainLoss Coefficient is -1.0. Basically, an infinite number of Inflows could result in the given Outflow because 100% of it is lost before getting to the Outflow. RiverWare now detects this situation and flags an error when it occurs. Models that contain reaches that solve upstream and have a GainLoss Coefficient of -1.0 will abort when run in the new release. The GainLoss value must be changed to any number that is greater than negative 1.0.
Confluence Object
Confluence Solution Direction
A new method category, Confluence Solution Direction, was added to the Confluence object. The default method in this category is Solve Upstream or Downstream. If this method is selected the Confluence will be able to solve either upstream or downstream depending on the knowns and unknowns. The user may also select the Solve Downstream Only method. If this method is selected the Confluence will always solve in a downstream direction. This is useful in rules models where slot priorities may be causing the object to solve in a direction that is not intended.
Power Reservoirs
Power Capacity Slot
A new slot, Power Capacity, was added to the PeakPowerCalc and PeakBasePowerCalc methods. The peak power value will be set in the Power Capacity slot. This represents the power that could be generated at the given operating head if the turbines are fully open. Prior to this release, the peak power value was stored in the Power slot. Now the Power Capacity slot will hold the peak power and the Power slot will contain the actual power produced. This is calculated by dividing the Energy by the timestep length.
Input Energy Adjustment
A new method category, Input Energy Adjustment, was added to all power reservoir objects. The default method, No Energy Adjustment, will do nothing. If the user selects Reduce Input Energy, and the input Energy value exceeds the maximum energy for the given timestep, the Energy value will be reduced to the maximum value and will be flagged Max Capacity.
Reservoirs
Input Outflow Adjustment
A new method category, Input Outflow Adjustment, was added to all reservoir objects. The default method, No Outflow Adjustment, will do nothing. If the user selects Reduce Input Outflow, and the input Outflow value exceeds the maximum outflow for the given timestep, the Outflow value will be reduced to the maximum value and will be flagged Max Capacity.
Inline Power Plant Object
An Inline Power Plant Object is now available on the object palette. This object is used to simulate power production on a reach with no storage capabilities. The object has an Inflow and Outflow that are always equal, and a user method to compute Power and Energy based on the flow rate in the reach. Detailed documentation of the Inline Power Object may be found in the Simulation Objects Documentation online.
Rulebased Simulation
Hypothetical Simulation
A new palette function called HypotheticalSimulation is available on the Rule Palette. This function accepts a lists of user input values and then simulates a portion of the model, defined in a subbasin, without setting slots or having any other effects on the actual model. The function returns a list of NUMERICs, which are the output slots from the hypothetical simulation. The user defines the list of the slot values that are returned from the function. This function is useful in a rule where the user needs to see the downstream affects of a reservoir release, for example, without actually setting the release and waiting for RiverWare to simulate. The hypothetical simulation takes place during the execution of the rule that calls this function, so decisions can be made based on the returned results. If the model has lagged reaches, the user is able to access the downstream affects of a release as well as the future affects of a release. The hypothetical simulation portion of the function exactly replicates the actual simulation that would take place in RiverWare if the input values, specified by the user, were actually set.
The HypotheticalSimulation function takes three arguments. The first argument is a STRING which specifies the subbasin to simulate. Only those objects that are in the subbasin are hypothetically simulated. The second argument is a LIST of LISTS. Each list includes the slot, value, and timestep that the user want to us as input to the hypothetical simulation. Any values that already exist on the objects will also be used. The third argument is also a LIST of LISTS. Each list includes the slot and the date for all required return values. The function returns a LIST of the values for the specified slots at the specified times. Details on the use of this function and the syntax involved are available in the Rulebased Simulation documentation online.
Water Accounting
User Defined Accounting Methods
The accounting calculations in RiverWare are now accessible by all RiverWare users. New functionality has been added to allow users to write methods, in the same language used for rules, that move water into and out of the accounting system. In every accounting model there has to be a way to move physical water into the accounts. For example, in a rain event a reservoir will experience hydrologic or local inflows that will increase the storage in the reservoir. Most accounting systems then have some sort of policy that describes how this water is divided among the storage accounts in the reservoir. Another example is when the physical system is experiencing losses, these losses usually have to be applied to the accounts in some specific manner. The User Defined Accounting Methods can be written and selected by the user to accomplish both of these tasks.
The Method Set Editor can be accessed by selecting Accounting->Accounting Methods from the RiverWare Workspace main menu. This will bring up a dialog box that looks similar to the Ruleset Editor.
Each of the categories listed in the Method Set Editor corresponds to a user method category on a particular object or objects. When a method is added to one of these categories, the method then shows up in the list of available user methods in that method category on every object that has that category. The user activates these methods by opening up the object and selecting the method in the appropriate category (the same way user methods are selected for simulation). If a method is selected on an object, that method should only set accounting slots (i.e. Slot Inflow and Gain Loss on particular accounts) on accounts that are on that object. However, the methods are allowed to set slots on data objects. If a method attempts to set a non-accounting slot or a slot on another object and error result.
The user can write generic methods that may be used and selected on several objects. The ThisObject variable can be used when writing methods to access slots of a particular name on whatever object is using the method at a given time. Following is an example of a simple method (this can be printed for increased clarity):
This method sets the Slot Inflow slot on the RioGrande account to the value in the Hydrologic Inflow slot. Since the ThisObject variable is used, this method can be selected on more than one object, and the name of the object that is using the method at a given time replaces the ThisObject variable.
Pre-Defined Accounting Methods
Zero Slot Inflows on Reach
The Zero Slot Inflows method in the Reach Pass Through Account Slot Inflow category now sets the Slot Inflow to zero for all accounts on the Reach object.
Multiple Supplies Between Accounts
RiverWare accounting now has the ability to model multiple supplies between the same two accounts. This is accomplished by naming an upstream account as a supply, then naming the same account again as another supply. As long as the two supplies have different names this will not be a problem. This is useful when the user needs to differentiate among the various reasons why water is being moved between the two accounts.
Optimization
Multiple Run Management
Multiple Run Management is now working, but the testing on realistic models has been limited. To truly test MRM TVA should develop DMIs for MRM. If the DMIs are correct, we would expect that MRM will get the same results as manually running consecutively, and calling the single run DMIs between runs.
Lambda Cuts
Writing constraints on single variables that are part of a lambda representation now cause RiverWare to automatically add cuts to eliminate lambda variables and reduce linearization error. For example, writing the policy constraint Wheeler.Outflow >= 10 leads to cut constraints that will gradually reduce and eventually eliminate all lambda points with Outflow less than 10 as this constraint is satisfied. In our testing, these constraints have added about 25% to the run time of a model. The cut constraints can be turned off at a reservoir by selecting an appropriate method. We suggest this be tested for excessive run time on current models. In addition, this improvement in the lambda approximations suggests that it now makes sense to selectively increase the number of lambda points used in the lambda approximations. This will require a change in DMIs.
Marginal Cost
We have added a Previous Marginal Cost slot. If the generation is between blocks, the Previous Marginal Cost slot will reflect the block cost as generation is reduced while the original Marginal Cost slot will reflect the cost of increasing generation. If the generation is in the middle of a block both costs should be the same. We also added a table slot, Block End Tolerance. If the generation is within this value of the end of a block it will be considered to be at the end in terms of the marginal costs reported. If this value is NaN, it is replaced with zero which will cause the Previous Marginal Cost and Marginal Cost to be identical.
Performance Improvement
Performance improvements were made which are particularly noticeable in models with long run times on “No Spill” constraints. However, the gains have been somewhat offset by the increased run times of the Lambda cuts.
Smoothed Energy
The original smoothed energy task is completed and functional, but the results indicate that some modifications need to be made before it is useful for river scheduling.
Spill Input
Spill (or any type of spill) can be set to input for optimization and the result will be preserved in post-optimization simulation. Also, all of the simulation spill categories now have optimization counterparts.
Linearization Zero Terms
When linearization generates a term with a zero coefficient that term is not added. Previously this led to additional unnecessary linearizations and data demands.
Diagnostics
CPLEX diagnostics are now directed to the RiverWare diagnostics window. This change led to fixing several bugs that previously had gone undetected.
A number of warnings have been rewritten to be more clear and additional warnings have been added.
Bug Fix Highlights
When an expression slot divides by zero, the user now receives an error message to indicate the cause.
The value -0.0 appears to have been eliminated. Two independent sources were fixed.
The model no longer aborts if an entire priority is eliminated implicitly by use of the BY operator and slots with NaN. Additionally, the error message associated with this error has been improved.
Several problems with the optimization parameter dialogs were fixed.
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.
 
1327
1353
1395
1400
1816
1827
1879
1921
1963
2039
2123
2125
2179
2191
2214
2216
2280
2217
2232
2260
2261
2269
2341
2405
2419
2496
2527
2537
2542
2546
2585
2605
2611
2614
2618
2632
2637
2645
2646
2647
2648
2650
2655
2660
2669
2679
2682
2684
2689
2690
2693
2694
2695
2698
2700
2729
2734
2737
2738
2739
2740
2748
2751
2756
2767
2770
2771
2772
2776
2778
2779
2782
2786
2788
2794
2795
2797
 
Revised: 06/03/2019