skip to main content
Release Notes Version 4.1
Release Notes Version 4.1
Special Attention Notes
• RiverWare is now available for the Windows 2000 platform. RiverWare will also run on NT, however, it is only supported for Windows 2000. Important information about using the Windows executable is included below in the RiverWare for Windows 2000 section.
• Plotting is now available for the Windows version of RiverWare. RiverWare uses PrestoPlot for all plotting that takes place on the Windows platform. This is intended as a temporary solution until a better cross-platform plotting solution can be found.
• Optimization is now available for the Windows version of RiverWare. You will need a Windows CPLEX license to run optimization on Windows. Contact CADSWES for this.
• Rulesets now have file versioning so that ruleset files can be matched with model files. This allows RiverWare see which release was last used to save the ruleset. The first time a ruleset is loaded into RiverWare Release 4.1, RiverWare will not recognize the ruleset version (because an existing ruleset will not have one yet) and the user will see the following RiverWare notice.
Even though the dialog box says that the file cannot be recognized as a RiverWare ruleset, it will recognize it when the Continue button is clicked. Then, once the ruleset is saved in the new release, it will have a version number and you will not see this message again.
• Several new predefined functions have been added to the rules palette. Since these are very general functions, and have very general names, there is a possibility for naming conflicts with existing rulesets. For example, one of the new functions is call “Sum”. If an existing ruleset contains a user defined function or variable called “Sum”, the ruleset will not load in the new release. The user will get an error message when loading the ruleset. The message explains exactly where the conflict is located. In order to load the ruleset in the new release, the user will need to modify the ruleset to alleviate the conflict. This is done by changing the name of the user defined function or variable.
Negative Outflow Warnings Removed
• Prior to this release, if a reach object computed a negative outflow it would print a warning message to the diagnostics window. In Rulebased Simulation models, reaches often solve several times per timestep. While some of these solutions may result in a negative outflow, the final result is usually a positive outflow. This results in several warning messages that are insignificant because the final answer is not negative. Furthermore, these messages clutter the diagnostics window and are generally annoying. In RiverWare 4.1 these warning messages have been removed. Since most users ignored these messages for the reasons given above, this is generally not a problem. However, if some users were relying on these warning messages to catch modelling errors, they need to be aware of this change and find this information some other way.
Required Model File Updates
solveMB_givenInflowRelease
The iteration technique for the solveMB_givenInflowRelease dispatch method on reservoir objects has changed. As a result of this, the method may converge to slightly different values (within the convergence limit). This can be fixed by decreasing the value in the Convergence slot. Also, it may be necessary to increase the number in the Max Iterations slot. If you are seeing a warning message that says “Internal loop reached the maximum iterations of ...” then you need to do this.
This new iteration technique is a bisection method that is bounded by the maximum and minimum pool elevation values in the Elevation Volume Table. Therefore, this requires the same range of values for pool elevation in the spill, max release, and elevation volume tables. For example, if the elevation volume table ranges from 0-2400 ft, then the spill table needs to go from 0-2400 ft. If these tables are inconsistent in an existing model, the model will not run in this release until the tables are updated.
Inline Power
The Inline Power object was enhanced to include the following general slots: Turbine Release, Max Turbine Release, Plant Capacity Fraction, Bypass, Min Bypass, and Hydro Capacity. The addition of the Max Turbine Release slot will cause existing models (that use the Inline Power object) to abort. A Max Turbine Release value must be input in order to fix the model. The user should be aware that the units for all of the new slots will be standard RiverWare units and users must configure them accordingly.
Reach GainLoss with Time Lag Routing
Two of the GainLoss Calculation methods on the Reach object, Seasonal GainLoss Flow Table and Interpolated Flow GainLoss, are no longer valid methods when Time Lag Routing is the selected routing method on the reach. The reason for this change is that it is impossible to get the same answers solving upstream and downstream when using Time Lag Routing with one of these loss methods. Therefore, we disabled these two methods when Time Lag Routing is selected. If an existing model has a reach with both Time Lag Routing and one of the two loss methods mentioned above, RiverWare will give the following warning message when loading the model in the 4.1 release: “The <loss method name> method is no longer available when using timeLagRouting. You will need another reach to do the Gain Loss calculations. ...” If this happens, the GainLoss method on the reach in question will be changed to No GainLoss. You will need to create a separate reach object to do the Gain Loss calculations.
 
Name Conflicts in Rulesets
Several new predefined functions have been added to the rules palette. Since these are very general functions, and have very general names, there is a possibility for naming conflicts with existing rulesets. For example, one of the new functions is call “Sum”. If an existing ruleset contains a user defined function or variable called “Sum”, the ruleset will not load in the new release. The user will get an error message when loading the ruleset. The message explains exactly where the conflict is located. In order to load the ruleset in the new release, the user will need to modify the ruleset to alleviate the conflict. This is done by changing the name of the user defined function or variable.
GainLoss Specification on Pass Through Accounts
There are two ways to compute the GainLoss slot on Pass Through Accounts. One way is to specify a GainLoss coefficient on the account. This will compute GainLoss as a percentage of the inflow to the account. The other way is to set GainLoss directly using an object level accounting method. Prior to this release, the user could theoretically give a GainLoss coefficient and set the GainLoss slot with a method. Obviously this is an overdetermination. However, instead of giving an error, RiverWare just ignored the GainLoss coefficient. In the 4.1 release, this will result in an error. If this is happening, the user needs to either turn off the method, or remove the GainLoss coefficient.
Model Loading
Ruleset Loading
Rulesets now have file versioning so that ruleset files can be matched with model files. This allows RiverWare see which release was last used to save the ruleset. The first time a ruleset is loaded into RiverWare Release 4.1, RiverWare will not recognize the ruleset version (because an existing ruleset will not have one yet) and the user will see the following RiverWare notice.
Even though the dialog box says that the file cannot be recognized as a RiverWare ruleset, it will recognize it when the Continue button is clicked. Then, once the ruleset is saved in the new release, it will have a version number and you will not see this message again.
Name Conflicts in Rulesets
Several new predefined functions have been added to the rules palette. Since these are very general functions, and have very general names, there is a possibility for naming conflicts with existing rulesets. For example, one of the new functions is call “Sum”. If an existing ruleset contains a user defined function or variable called “Sum”, the ruleset will not load in the new release. The user will get an error message when loading the ruleset. The message explains exactly where the conflict is located. In order to load the ruleset in the new release, the user will need to modify the ruleset to alleviate the conflict. This is done by changing the name of the user defined function or variable.
Unit Changes
Enhancements were made to the way RiverWare handles units. Part of this enhancement includes a more rigorous method of enforcing valid units and unit types. As a result of this change, it was noticed that some older models have slots that have either invalid units or invalid unit types. When RiverWare encounters these slots, it resets the units and prints the following warning message when loading the model:
Invalid <unit type> units “old units” changed to “new units”.
If a slot has invalid units, and it has gone undetected by the user this long, then most likely this is a slot that is not used in modeling (and therefore probably doesn’t contain any values). In that case, the warning message can be ignored. However, it is probably safest to look at the slot mentioned in the warning and verify that the units and unit type are now correct.
Reach GainLoss with Time Lag Routing
Two of the GainLoss Calculation methods on the Reach object, Seasonal GainLoss Flow Table and Interpolated Flow GainLoss, are no longer valid methods when Time Lag Routing is the selected routing method on the reach. The reason for this change is that it is impossible to get the same answers solving upstream and downstream when using Time Lag Routing with one of these loss methods. Therefore, we disabled these two methods when Time Lag Routing is selected. If an existing model has a reach with both Time Lag Routing and one of the two loss methods mentioned above, RiverWare will give the following warning message when loading the model in the 4.1 release: “The <loss method name> method is no longer available when using timeLagRouting. You will need another reach to do the Gain Loss calculations. ...” If this happens, the GainLoss method on the reach in question will be changed to No GainLoss. You will need to create a separate reach object to do the Gain Loss calculations.
Some “SeriesSlots” changed to “AggSeriesSlots”
Some SeriesSlots have been converted to AggSeriesSlots. When loading old models, diagnostics messages may be generated as old slot types are automatically converted to new slot types:
Trying to convert former slot type (“SeriesSlot”) to new slot type (“AggSeriesSlot”).
Do not be concerned by these messages. You do not need to make any changes to your model. The use and functionality of these slots has not changed.
RiverWare for Windows 2000
RiverWare is now available and supported for Windows 2000 (it will also run on NT but CADSWES is supporting Windows 2000). The user should be aware of the following differences that exist in RiverWare for Windows:
Differences in RiverWare for Windows
• Middle-mouse features such as QuickLink or rearranging the rows in the run analysis dialog are activated with the combination (pressed in this order): Alt + right mouse button + left mouse button.
• QuickLink can also be activated using the right-mouse button.
• The Windows DMI executable can be a DOS batch file or any other windows executable that can be run directly from a command shell.
Problems/Bugs in RiverWare for Windows
• The Locator View window often gets in a bad state when you resize the main workspace.
• It is possible that the objects may get shifted off the workspace if the workspace window is resized in certain ways. In order to make the objects visible again, you must save the model then reload it. Reloading the model will shift the model so that all objects are visible on the workspace.
Saving Model Files and Rulesets
• When saving model files or ruleset files that you intend to move between windows and unix systems, always save with the .gz extension. This saves the model/ruleset in a binary format that is the same on windows and unix.
Enhancements to RiverWare for Windows
• Plotting is now available for the Windows version of RiverWare. RiverWare uses PrestoPlot for all plotting that takes place on the Windows platform. This is intended as a temporary solution until a better cross-platform plotting solution can be found.
• Optimization is now supported on Windows. You will need a Windows CPLEX license to run optimization on Windows. Contact CADSWES for this.
General RiverWare
Multi-Object Method Selector
Before the Multi-Object Method Selector dialog box was available, a user had to select engineering methods for each object individually, using the Open Object dialog for each separate object. If a new RiverWare release brought a new engineering method to the Slope Power Reservoir simulation object, for example, a user would have to select this new method on each Slope Power Reservoir object in an existing model. For large models, this could be a tedious and time-consuming task. The purpose of the Multi-Object Method Selector is to allow the user to set a current engineering method for a potentially large group of objects from a single dialog.
This task is complicated by the fact that all objects of the same type do not necessarily have the same engineering methods or method categories available. So, for example, it is not always possible for a user to select a given method on all Level Power Reservoirs. The currently selected engineering methods on an object determine the currently available methods and method categories.
To overcome these difficulties, this dialog indicates which objects have a given method category available and therefore which objects will need to be re-configured in order to make the given category available. The dialog similarly indicates which engineering methods are available on each object for a given category. Once an engineering category and method is selected, the dialog only changes the engineering method on objects which have the desired category and method available.
• Open the Multi-Object Method Selector from the main RiverWare menu: “Workspace” -> “Objects” -> “Select Methods on Objects...”
• Add objects to the object list by pressing “Add Objects...” then select objects in the object selector and press “Apply.”
• Select a category from the category list.
• Verify that the category is available on all desired objects by inspecting the “Current Method” column in the object list.
• Select a new method using the “New Method” option menu.
• Verify that the selected method is available on all desired objects by inspecting the “Available” column in the object list.
• Apply the new method to all the objects by pressing the “Apply New Method” button.
• Verify that the objects listed in the confirmation dialog are the objects you intend to affect, and press “OK.”
This is just a general description of how the dialog is used. If you need more detailed user instructions, contact CADASWES.
DMI Importing
Importing with New Start Date After Existing End Date
Prior to this release, if a DMI was importing data into a Series Slot, and the new Start Date for the slot was later than the existing End Date on the slot, the import would abort unless both a new Start Date and End Date were specified. In the RiverWare 4.1 release, it is only necessary to specify a new Start Date for the slot. When this happens, RiverWare moves the Start Date ahead to the new date and then resizes the slot based on the amount of data being imported.
Importing to Aggregate Series Slots
The DMI input files for Agg Series slots now allow comments. Anything following a # symbol will be treated a comment and ignored. Also, blank lines are now ignored. However, all other white space is significant. For example, if the Agg Series slot has 10 columns and the input is:
1 2 3 4 5 6 7
8 9 10
this will result in an error because the end of the line after 7 means that you are trying to enter 7 values for one timestep and 3 values for the next timestep. Each row must be complete and represent a single timestep. A blank line is ignored now as if it was not there. Before, a blank line meant that the last row had been entered.
Command Line Options
A new command line option was added. The --log option is used to write all console output to a file. This is useful when running RiverWare in batch mode because all diagnostic output is written to the terminal/console window in that case. All of the command line options are explained by typing riverware --help.
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.
Data Objects Now Have Different Colors
A new enhancement to the Data Object allows the user to set the color of the object. The Data Object’s color can be set by selecting Edit->Set Icon Color from the Open Object dialog.
Inline Power
The Inline Power object was enhanced to include the following general slots: Turbine Release, Max Turbine Release, Plant Capacity Fraction, Bypass, Min Bypass, and Hydro Capacity. The addition of the Max Turbine Release slot will cause existing models (that use the Inline Power object) to abort. A Max Turbine Release value must be input in order to fix the model. The user should be aware that the units for all of the new slots will be standard RiverWare units and users must configure them accordingly.
The Turbine Release, rather than the Inflow, is now used for the power calculation. The Plant Capacity Fraction is used when the plant is not operating at full capacity. The Bypass slot is set to a user input Min Bypass value plus the spill. A new dispatch method, solveMB_givenOutflow was added to allow the object to solve upstream. A new method category, called Solution Direction, was added to allow either upstream and downstream solving, or solving in the downstream direction only.
Also, methods for calculating spill cost and turbine ramping cost were included for use in optimization models.
Reach
Negative Outflow Warnings Removed
Prior to this release, if a reach object computed a negative outflow it would print a warning message to the diagnostics window. In Rulebased Simulation models, reaches often solve several times per timestep. While some of these solutions may result in a negative outflow, the final result is usually a positive outflow. This results in several warning messages that are insignificant because the final answer is not negative. Furthermore, these messages clutter the diagnostics window and are generally annoying. In RiverWare 4.1 these warning messages have been removed. Since most users ignored these messages for the reasons given above, this is generally not a problem. However, if some users were relying on these warning messages to catch modelling errors, they need to be aware of this change and find this information some other way.
GainLoss Methods with Time Lag Routing
Two of the GainLoss Calculation methods on the Reach object, Seasonal GainLoss Flow Table and Interpolated Flow GainLoss, are no longer valid methods when Time Lag Routing is the selected routing method on the reach. The reason for this change is that it is impossible to get the same answers solving upstream and downstream when using Time Lag Routing with one of these loss methods. Therefore, we disabled these two methods when Time Lag Routing is selected. If an existing model has a reach with both Time Lag Routing and one of the two loss methods mentioned above, RiverWare will give the following warning message when loading the model in the 4.1 release: “The <loss method name> method is no longer available when using timeLagRouting. You will need another reach to do the Gain Loss calculations. ...” If this happens, the GainLoss method on the reach in question will be changed to No GainLoss. You will need to create a separate reach object to do the Gain Loss calculations.
Reservoir
Plant Power Equation
A new method, Plant Power Equation, has been added to the Power Calculation Category. This method computes power based on the Water Power Equation:
where power is the plant power, turbine release is the flow through the turbines, H is the net head across the turbines, e is the plant efficiency expressed as a decimal percentage, and the Power Plant Capacity Fraction is the fraction of full capacity at which the plant is operating.
Peak Power Equation
A new method, Peak Power Equation, has been added to the Power Calculation Category. This method computes power based on the Water Power Equation:
where power is the plant power, peak flow is the peaking flow rate through the turbines, H is the net head across the turbines, e is the plant efficiency expressed as a decimal percentage, and the Power Plant Capacity Fraction is the fraction of full capacity at which the plant is operating. Once the peak flow and the power have been determined, the method computes the peak time. This is the amount of time the turbines were running at peak power.
CurrentSurfaceAreaPanAndIce
A new evaporation method, called CurrentSurfaceAreaPanAndIce, has been added to all reservoir objects. This evaporation method is identical to the PanAndIceEvaporation method except that is uses the current surface area instead of the average surface area.
Input Bank Storage
A new method, Input Bank Storage, was added to the bankStorageCalcCategory on all reservoir objects. This method allows the user to input a time series range of bank storage values.
AggDistribution Canal Elements
Input Seepage
A new method, Input Seepage, was added to the Canal Seepage category on Distribution Canal Elements. This method allows the user to input the seepage losses from the canal elements.
Rulebased Simulation
New Palette Functions
Following is a brief description of the new rules palette functions (Predefined Functions) available for use in the RiverWare Policy Language for writing rules. Details on the use of these function and the syntax involved are available in the Rulebased Simulation documentation online.
HypLimitSim
This function is used to find the greatest control slot value which doesn’t cause another specified slot to exceed a given value during a given time range. For example, this function could be used to find the constant outflow value, over some time period, that will keep the pool elevation from exceeding a given value. This function is similar to the HypTargetSim function except that instead of finding a control slot value that leads to the target slot value at a particular timestep, it finds a control slot value which leads to the limit slot value not exceeding a limiting value over a range of dates.
HypLimitSimWithStatus
This function is used to find the greatest control slot value which doesn’t cause another specified slot to exceed a given value during a given time range. For example, this function could be used to find the constant outflow value, over some time period, that will keep the pool elevation from exceeding a given value. This function is similar to the HypTargetSim function except that instead of finding a control slot value that leads to the target slot value at a particular timestep, it finds a control slot value which leads to the limit slot value not exceeding a limiting value over a range of dates. This function returns a LIST. If a solution cannot be found with the given min and max values, it will return the closest answer it can find and a FALSE boolean value to let the user know that it failed. If the function succeeds it will return true.
Note: this function is very similar to HypLimitSim: the only difference is that HypLimitSim fails if it can not find a satisfying control slot value, whereas this function does not fail, rather it still returns a value, along with the indication that this value does not achieve the limit.
TargetHWGivenInflow and TargetSlopeHWGivenInflow
These functions are used to perform a lumped mass balance across several timesteps. Given a target range and the total inflows over the target range, it will compute the outflow required to meet the given target pool elevation at the target date. This is analagous to the target operation in Simulation. The TargetSlopeHWGivenInflow function needs to be used when performing a target operation on a Slope Power Reservoir.
Floor
This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the largest integer multiple of “factor” which is not greater than the converted “value”.
Ceiling
This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the smallest integer multiple of “factor” which is not less than the converted “value”.
Fraction
This function takes a NUMERIC “value” and a NUMERIC “factor” as arguments. The “value” is converted into the units of “factor”. Then the function returns the fractional portion of this converted “value” after is has been divided by “factor”.
GetSlot
Returns a slot given a STRING that represents a slot name.
GetElementName
Given an OBJECT which is an element in an aggregate object, this function returns the name of that element as a STRING and without the name of the aggregate object at the beginning.
IntDivision
This new predefined function replaces the DIV button on the rules palette. It returns the integer portion of the division of two numbers.
Modulus
This new predefined function replaces the MOD button on the rules palette. It returns the remainder of the integer division of two numbers.
NextDate
This function takes a partially specified date/time and a fully specified reference date. The function resolves the partially specified date/time into one that is fully specified. The specified fields of the partial date/time are copied into the return date, and the missing fields are filled in so that the resulting date is the closest date possible to the reference date. If the partial date cannot be resolved to the reference date, it is resolved into the next date in the future which works. For example, if the partially specified value is “May 10”, and the reference date is the current timestep, the function will return the fully specified date that corresponds to the next May 10th that occurs after the current timestep.
PreviousDate
This function takes a partially specified date/time and a fully specified reference date. The function resolves the partially specified date/time into one that is fully specified. The specified fields of the partial date/time are copied into the return date, and the missing fields are filled in so that the resulting date is the closest date possible to the reference date. If the partial date cannot be resolved to the reference date, it is resolved into the previous date in the past which works. For example, if the partially specified value is “May 10”, and the reference date is the current timestep, the function will return the fully specified date that corresponds to the previous May 10 that occurred before the current timestep.
AnnualEventStats, AnnualEventCount, and AnnualEventLastOccurance
Three functions were added which analyze a slot’s value over some number of years, noting the occurrence of certain "events". The functions all have the following set of arguments:
• o SLOT slot
• o DATETIME analysis period start date
• o DATETIME analysis period end date
• o DATETIME event period start date (year, if specified, is ignored)
• o DATETIME event period end date (year, if specified, is ignored)
• o NUMERIC value threshold
• o BOOLEAN value threshold is upper bound (else lower bound)
• o NUMERIC subevent count threshold
• o BOOLEAN subevent count threshold is upper bound (else lower bound)
The analysis period start and end dates define the period during which the analysis will be performed. Within the analysis period, only the timesteps which occur on or between the day and month of the event period start and end dates are considered. Each of these periods within the analysis period is called an event period. At each event period, an event can either occur or not. An event is defined by the value threshold and comparison type and the subevent count threshold and comparison type. At each timestep within an event analysis period, the slot’s value is compared to the threshold value. If the value threshold is an upper bound and the slot’s value is greater than the value threshold, then a subevent is said to have occurred at that timestep; similarly, if the value comparison is a lower bound and the slot’s value is less than the value threshold, then a subevent is said to have occurred. After the subevents within an event analysis period have been noted, then they are counted up and compared to the subevent count threshold. If the subevent count threshold is an upper bound and the number of subevents which occurred in an event analysis period is greater than the subevent count threshold, then an event is said to have occurred, and similarly, if the subevent count comparison is a lower bound and the number of subevents which occurred in an event analysis period is less than the subevent count threshold, then an event is said to have occurred. For example, a user might define an event as outflows from a particular reservoir of greater than 10,000 cfs on five days between March 1 and July 31 of each year in the analysis period.
The three new functions are:
• LIST AnnualEventStats(...)
The return list contains the following items (listed in order, with index):
– (0) the total number of event periods.
– (1) the number of events which occurred.
– (2) the number of event periods which occurred after the last event.
If no events occurred, then this is the number of event periods.
• NUMERIC AnnualEventCount(...)
The return value is the number of events which occurred.
• NUMERIC AnnualEventLastOccurrence(...)
The return value is the number of event periods which occurred after the last event. If no events occurred, then this is the number of event periods.
TableInterpolation3D
A three column table interpolation function has been added to the list of pre-defined rules functions. If the user has a three column table that relates three different variables (for example, time of the year vs. flow rate vs. loss coefficient), the function will take values for two of the columns and will perform a three-dimensional, linear interpolation to find the corresponding value in the third column.
Sum
This function returns the sum of a LIST of NUMERIC values.
SumByIndex
Given a LIST of lists and an index, this function will sum the values at the given index in each list.
MaxItem and MinItem
These functions return the maximum/minimum number in a LIST of NUMERIC values.
DateMax and DateMin
These functions are passed in two DATETIME arguments. They return the greater/lesser date of the two.
LeapYear
This function returns true if the given date is a leap year.
GetDatesCentered
This function returns a LIST of dates, separated by a given interval, and centered at a given date. If desired, dates not within the run duration are filtered out.
IsEven
Returns true if the value is an even number
IsOdd
Returns true if the value is an odd number
GetNumbers
This function returns a sequence of values in a given range with a given offset.
GetTableRowValsSkipNaN and GetTableColumnValsSkipNaN
These functions are just like GetTableRowVals and GetTableColumnVals except that if a NaN is encountered, it is skipped and left out of the return list instead of causing the rule to terminate early.
New Palette Functions For Use With Accounting
WaterTypes
This function returns a list of the names of all user-defined Water Types defined in the model.
WaterOwners
This function returns a list of the names of all user-defined Water Owners defined in the model.
ReleaseTypes
This function returns a list of the names of all user-defined Release Types defined in the model.
Destinations
This function returns a list of the names of all user-defined Destination Types defined in the model.
ReleaseTypesFromObject
This function returns a list of unique names of ReleaseTypes of all Supplies which represent outflows from an Object.
DestinationsFromObjectReleaseType
This function returns a list of unique names of Destinations of all Supplies which are of the indicated Release Type (possibly “all” or “none”) and which represent outflows from the indicated Object.
AccountNamesByWaterType
This function returns a list of names of Accounts on the specified Object that are of the specified Water Type. The Water Owner Argument can be “none”.
AccountNamesByWaterOwner
This function returns a list of names of Accounts on the specified Object that are of the specified Water Owner. The Water Owner Argument can be “none”.
AccountNamesFromObjReleaseDestination
This function returns a list of names of Accounts on the specified Object that have Supplies which are of the indicated Release Type (possibly “all” or “none”) and Destination (possibly “all” or “none”) and which represent outflows from the indicated Object. Supplies which represent “internal flows” between two Accounts on the Object are not considered.
Functions Returning Supply Names
The first Argument of the following eight functions -- “SourceList” or “TargetList” -- is a list (ListValue) of {OBJECT, ACCOUNT NAME} pairs, each represented by a two-element ListValue. (The Account Name item is a StringValue). That is, the first Argument is a ListValue of constrained ListValues.
Values passed in for the second and third Arguments -- ReleaseTypeString and DestinationString -- can be “all” or “none.” (“None” corresponds to Supplies which have the default ReleaseType or default Destination).
There are two sets of functions in this section:
• SupplyNamesFrom SupplyNamesFrom1to1
• SupplyNamesFromIntra SupplyNamesFromIntra1to1
• SupplyNamesTo SupplyNamesTo1to1
• SupplyNamesToIntra SupplyNamesToIntra1to1
Each function in the first group returns a ListValue of SupplyNames (StringValues) corresponding to the {OBJECT, ACCOUNT NAME} pairs in the SourceList or TargetList argument.
The functions in the second group (whose names end in “1to1”) return an ordered ListValue of SupplyNames (StringValues) where exactly ONE SupplyName value corresponds to each of the {OBJECT, ACCOUNT NAME} pairs in the SourceList or TargetList argument. If there is no Supply that meets the criteria, an empty string (““) is returned to correspond to the Source/Target item. If there is MORE THAN ONE Supply that meets the criteria, a run-time error is reported.
SupplyNamesFrom
This function returns a ListValue of names of Supplies which represent outflows from the Objects, from the indicated Accounts. THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Source List.
(See general section comments, above).
SupplyNamesFromIntra
This function returns a ListValue of names of Supplies which represent internal flows on the Objects, from the indicated Accounts (to other Accounts on the same Object.) THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Source List.
(See general section comments, above.)
SupplyNamesTo
This function returns a ListValue of names of Supplies which represent inflows to the Objects, to the indicated Accounts. THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Target List.
(See general section comments, above.)
SupplyNamesToIntra
This function returns a ListValue of names of Supplies which represent internal flows on the Objects, to the indicated Accounts (from other Accounts on the same Object.) THIS function does NOT impose the restriction that zero or one Supplies matches the criteria for every item in the Target List.
(See general section comments, above.)
SupplyNamesFrom1to1
This function returns an ordered ListValue of names of Supplies which represent outflows from the Objects, from the indicated Accounts. EXACTLY one Supply Name (or "") is returned for each Account in the Source List.
(See general section comments, above).
SupplyNamesFromIntra1to1
This function returns an ordered ListValue of names of Supplies which represent internal flows on the Objects, from the indicated Accounts (to other Accounts on the same Object.) EXACTLY one Supply Name (or "") is returned for each Account in the Source List.
(See general section comments, above.)
SupplyNamesTo1to1
This function returns an ordered ListValue of names of Supplies which represent inflows to the Objects, to the indicated Accounts. EXACTLY one Supply Name (or "") is returned for each Account in the Target List.
(See general section comments, above.)
SupplyNamesToIntra1to1
This function returns an ordered ListValue of names of Supplies which represent internal flows on the Objects, to the indicated Accounts (from other Accounts on the same Object.) EXACTLY one Supply Name (or "") is returned for each Account in the Target List.
(See general section comments, above.)
New Palette Buttons
FIND
This is used to find the index of a given item in a list. If the item is not contained in the list, a “-1” is returned.
STOP_RUN
This new RPL operator takes any type of argument. When it is evaluated, it aborts the run with an error message which contains the argument as part of the message. For example:
WITH (index = FIND 100.0 WITHIN getOutflows()) DO
IF (index < 0)
STOP_RUN “Expected an Outflow of 100”
ELSE
index
ENDIF
ENDWITH
IF ... ELSE ...
An IF-THEN-ELSE button has been added to the rules palette. This simplifies the creation of IF-THEN-ELSE expressions. Prior to this release, users had to separately use the IF button and the ELSE button.
 
Changes to Existing Palette Functions
Log and Ln
The previous use of these to functions was error prone. Two calls to one these functions which are equivalent but in different units will give different results. Therefore it is necessary to include the unit type that should be used to perform this operation. The Log function now takes two arguments, both NUMERIC. The Log function takes the first argument, converts it into the units of the second argument, and then returns the base 10 logarithm of the converted value. The Ln function converts the first NUMERIC into the units of the second and then returns the natural logarithm of the converted value.
If these functions are used in existing rulesets, they will continue to be used in the old way and will be renamed OldLog and OldLn. We encourage users to updated their rulesets to use the new functions.
Single Object SubBasins for HypSim Functions
There are several rules predefined functions which simulate the behavior of a SubBasin of objects into the future without changing those objects (HypSim, HypTargetSim, HypTargetSimWithStatus, HypLimitSim, and HypLimitSimWithStatus). The first argument to all of these functions is a string, which has been interpreted as the name of the SubBasin on which to perform the hypothetical simulation. We have generalized these methods to also accept the name of an object as the first argument. If the first argument is not the name of a SubBasin but is the name of an object, then the hypothetical simulation is performed on just that object. This eliminates the need to make several single object subbasins.
Searching Within Rulesets and Policy Groups
RiverWare 4.1 has the ability to search for strings in the name, descriptions and definitions of groups, functions and rules. Users can access the search functionality through the "Find..." menu items in the Group and Ruleset editors.
Rearranging Rules Within the Group Editor
Rules can now be rearranged within the Policy Group Editor dialog. Previously, rules could only be rearranged through the main Ruleset Editor.
Compressing Rulesets
Rulesets are now able to be compressed and saved with the .gz file extension. If moving rulesets between UNIX and Windows, the ruleset files must be compressed.
Rules Palette Redesign
The rules palette has been re-designed for ease of use. Below is a screen shot of the new palette. The palette buttons are still located on the main palette view. However, now there are separate tabs for the rules functions. The first tab is the main palette view, the second tab is for User-Defined Functions (added to the ruleset by the user), and the third tab is for pre-defined functions in RiverWare. These are now grouped by type instead of listed in alphabetical order. The user can switch between the group view and the function view using the Functions menu. Also in the Functions menu is a search mechanism which will search for a string in a function’s name, description, and/or definition.
Water Accounting
Supplies Manager
The new Supplies Manager dialog box provides an overview of the accounting Supplies in a RiverWare model. This dialog box can be accessed by selecting Accounting->Supplies Manager from the main RiverWare menu. The user can limit the set of supplies displayed to those to particular types of accounts (storage, pass through, diversion), and to those that are related to a particular engineering object - that is, supplies that are inflows to the object, outflows from the object, and/or flows between different accounts on the object. Color annotation of supply data is used to indicate a certain supply configuration, error condition, and the relationship of supplies to a particular object. The information displayed about each supply, and the order of the supplies presented in this dialog box are configurable by the user. From the Supplies Manager, the user can delete supplies and open various dialog boxes about the two accounts connected by a supply or those accounts’ respective engineering objects. For more information, or details on how to use this dialog, call CADSWES for help.
Transfer In and Transfer Out Slots
Two new slots, Transfer In and Transfer Out, were added to the Storage Account. These slots should be used for transfers that take place between accounts on the same reservoir. This allows the user to distinguish between outflows from accounts that are going downstream, and transfers that are staying in the reservoir but going to a different account.
New Supply Attributes: Release Type and Destination Type
Supplies can now be assigned a release type and a destination type. Basically, this is a way to group supplies together so they can be accessed easily by rules or viewed through the Supplies Manager. This is similar to labelling an account to have a specific water type and water owner (except this applies to supplies instead of accounts). In general, a release type represents the purpose for the release and the destination type represents the ultimate destination for the release from the account. By default, all supplies have a default of NONE for both the release type and the destination types. Release types and destination types are created, deleted, and added through the Water Accounting System Configuration Dialog. This dialog is accessed by selecting Accounting->Account System Configuration from the main RiverWare menu. Once supply types have been created, supplies can be assigned a type either through the Supplies Manager or the Supplies page of the Account Configuration Dialog (see below). If using the Supplies Manager to set supply types, the types must be displayed in Column1 and Column 2 of the dialog.
Accounts on Distribution Canals
The Distribution Canal object has been enhanced to allow Pass Through Accounts. The accounts function in the same manner as Pass Through Accounts on a Reach object.
GainLoss Specification on Pass Through Accounts
There are two ways to compute the GainLoss slot on Pass Through Accounts. One way is to specify a GainLoss coefficient on the account. This will compute GainLoss as a percentage of the inflow to the account. The other way is to set GainLoss directly using an object level accounting method. Prior to this release, the user could theoretically give a GainLoss coefficient and set the GainLoss slot with a method. Obviously this is an overdetermination. However, instead of giving an error, RiverWare just ignored the GainLoss coefficient. In the 4.1 release, this will result in an error. If this is happening, the user needs to either turn off the method, or remove the GainLoss coefficient.
Supply Slots in the SCT
Accounting supply slots can now be selected and used in the Simulation Control Table (SCT).
Optimization
• The Inline Power object has been enhanced. The enhancements have been motivated by the desire to model Ocoee2 at TVA as an Inline Power object. The main enhancements are to add a bypass slot and to allow optimization.
• The Constraint Editor has been enhanced to allow the user to close a goal or group by double-clicking on a constraint row under a goal or a group. In goal view, the user can double-click on the empty left-most column (open/close) or the fourth (goal-type) column to close the goal. In group view, the user must double-click on the left-most column (open/close) to close the group.
• The calculation of cumulative value of storage has been enhanced in two ways. First, flows in reaches that have not yet reached a reservoir by a given timestep are added to the reservoir storage to create a new slot, Anticipated Storage. The linearization of cumulative value is now done as a function of anticipated storage instead of storage. The second enhancement is to calculate the initial anticipated storage and the cumulative value of that anticipated storage. The suggested use of this initial value is to subtract it from the objective, e.g. " - Thermal Object.Total Cumulative Storage Value [0]". Thus, the new objective becomes Maximize avoided operating cost + NET increase in cumulative storage value. An attempt was made to include anticipated storage in the simulation calculations as well. This proved very difficult because of the interactions with object dispatching. This effort was abandoned, but the differences between optimization and simulation are very small. Still, the inclusion of these terms in optimization had a noticeable effect on flows during testing. In particular, flows at the end of the run were comparable to flows during the rest of the run, as desired.
• The automatic generation of a BWL point representing the initial conditions has been deactivated when the method generating "reducing" constraints is turned on; this point was interfering with the reducing constraints. The optimization now recognizes when lambda variables are implicitly fixed at zero, freezes appropriate variables and constraints, and passes the information to the OptAnalyst.
• The approximation error in spill constraints for level power reservoirs has been reduced by extrapolating spill tables in terms of storage rather than pool elevation.
• This release contains a large improvement in numerical stability. One fairly reliable measure of numerical stability is the condition number of the optimal basis. During a goal program there are a series of optimal bases and the condition numbers generally, if not monotonically, increase as optimization progresses. Prior to this work the condition number were roughly 1e+10 for one of the recent models with a long run time on "No Spill" constraints. After this work, the condition numbers are approximately 1e+6. While ILOG, the makers of CPLEX, suggests that ideally the condition numbers should be less than 10e+5, this improvement is still considerable.
The improvement is due to several factors. The initial effort focused on revising the units used in formulating the problem for CPLEX, the so-called OPT_UNITS. In the literature this kind of work falls under the more general category of scaling matrices. While the importance of scaling is widely accepted and easily demonstrated with small matrices, optimal scaling of matrices remains more of an art form than a science. With that in mind, we followed the general guidance that numbers close to one are preferable, and choosing "natural" units is advisable. The last piece of advice had been previously confirmed when SI units proved numerically on small problems where TVA’s user units worked fine. After trying several sets of units we converged on one set that we were unable to improve upon. Here is a sample of some of those units:
– Length: 10 m
– Area: 1e+7 m2
– Volume: 1e+8 m3
– Flow: 1000 cms
– Power: 1000 MW
– Energy: 1000 MWH
– Value: 1e+5 $
This task took somewhat longer than expected because, the optimization code had hidden assumptions about units in it. Those assumptions caused bugs, and they have been removed.
• Examining the optimization units led to several other enhancements that contributed to the reduction in the condition numbers. First, the precision of floating point numbers given to CPLEX has been made consistent. Second, an existing tolerance on minimum matrix coefficients has been used throughout optimization. Third, the Z variables introduced by RiverWare are now scaled based on the constraints of each priority. This last change required reworking the reporting of the satisfaction levels, and as part of that effort the satisfaction levels are now reported in terms of percentages, e.g. 100 means the constraints are fully satisfied.
The final optimization solution is checked for numerical instability based on 33 measurements. These measurements are compared against anticipated values and large differences are reported. The anticipated values will probably be refined as more models are run. The new tests added about 20 seconds to the runtime on a Sparc Ultra 5.
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.
 
14
22
172
173
182
183
189
214
220
231
235
239
240
241
242
298
306
322
383
499
514
592
691
738
797
807
833
896
942
1334
1521
1538
1839
1853
1966
2090
2101
2103
2104
2118
2132
2166
2183
2200
2228
2242
2304
2326
2364
2392
2427
2434
2469
2487
2528
2532
2535
2545
2589
2597
2626
2638
2656
2668
2728
2750
2777
2781
2806
2807
2828
2831
2833
2836
2837
2839
2840
2857
2871
2880
2890
2899
2900
2901
2902
2914
2917
2919
2949
2950
2955
2958
2959
2963
2965
2967
2969
2972
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2992
2993
2996
2997
2998
2999
3000
3001
3002
3003
3004
3006
3007
3008
3009
3010
3011
3012
3013
3014
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3033
3034
3035
3036
3037
3038
3039
3040
3042
3043
3044
3045
3047
3048
3049
3051
3052
3053
3054
3055
3056
3058
3059
3060
3063
3065
3069
3070
3071
 
 
 
 
Revised: 06/03/2019