This document describes new features, enhancements, and changes included in RiverWare Version 3.0, released on February 18, 2000. These changes are new to the executable since the release of RiverWare Version 2.1 on March 10, 1999.

Please direct questions to RiverWare Technical Support at (303) 492-0908 or support@cadswes.colorado.edu.

Users moving from RiverWare 2.1 or earlier must make the following changes for models using the sequential linking structure on the Aggregate Diversion Site object (changes have already been incorporated in RiverWare 2.1.1, 2.1.2 and 2.1.3. Users of these versions may disregard this notice):

1. The Total Unused Water slot must be linked to the Return Flow slot on the object from which water is being diverted.

2. The link between Total Available Water and the Incoming Available Water slot on the first Water User element must be removed.

If a large number of objects require these changes, ModelConvert_2.2 (located in the same directory as the RiverWare executable) can automatically perform the tasks.

Models using the muskingumRouting method on Reach objects must use the Input K and X Values method in the Routing Parameters method category. Users of the variable Muskingum Routing method should note that this method has been automatically changed to muskingumRouting. This is due to the creation of a new method category, Routing Parameters, which eliminates the need for the variable Muskingum Routing method.

TimeLagRouting on Reach objects now accommodates monthly lag times. This change requires the following:

1. If the timestep is monthly the lag time must be in months.

2. If the timestep is not monthly the lag time cannot be in months.

The variable TimeLagRouting method on Reach objects was modified to calculate Variable Lag Time using 3-D table interpolation. This requires only one table slot, the Variable LagTime Table (older models required four slots for this calculation: Date Range, Flow Range, Number of Seasons and Variable Lag Time Table). Models using this method need to add data to this new slot. The old slot used in this method, Variable Lag Time Table, no longer exists. This is conveyed by use of a warning message posted during model loading. More information about these changes can be found under the Reach heading below.

The Date Range slot on the Reach object has been changed to allow a range of days from 1 - 366 rather than the 0 - 365 range found in earlier versions of RiverWare. To obtain the same results, models using the Date Range table slot in the Seasonal GainLoss Flow Table method in the GainLoss Calculation category will need to add 1 to each value in the Date Range slot.

A new slot, Pumped Flow, was added to the Pumped Storage object. Models using this object must delete the link between the Reservoir object’s Flow TO Pumped Storage slot and the Pumped Storage object’s Inflow slot. This link must be replaced by a new link between Flow TO Pumped Storage and the new Pumped Flow slot. In addition, the Inflow slot (a required known) needs to be set to zero to achieve the same results.

The Maximum (Total) Supplemental Request slots on Water User and lumped AggDiversionSite objects are now dependent on a method selected in the Maximum Supplemental Request category. If using these slots, the user must select the Input Maximum Request method in the Maximum Supplemental Request category (which is dependent on the Supplement Diversion method of the Conjunctive Use calculation category) to get the same model results.

The calculateFutureValue method in the FutureValueCalcCategory on Reservoir and Pumped Storage objects has been altered to use a different set of slots. The Future Value of Water slot has been replaced by a slot called Marginal Storage Value Table. The calculation of Spill Cost and Future Value of Used Energy use this new slot. Models using the calculateFutureValue method must assign values to the Marginal Storage Value Table to avoid a table interpolation error.

AggDiversionSites operating under the Lumped linking structure no longer set the Total Diversion Requested to 0.0 by default. All existing models that were using this default must now input zeros for the models to run correctly.

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:

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.

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 variableTimeLagRouting method has been modified to use a 3-D table interpolation to determine the Lag Time instead of a table lookup. This is accomplished through the use of a new tableslot, Variable LagTime Table. The Lag Time is computed based on a double interpolation involving the day of the year and the flow rate in the reach. Previous models using this method will no longer calculate Lag Time. New data is required in the Variable LagTime Table slot. Detailed documentation of this method may be found in the Simulation Objects Documentation online.

A new user method, Interpolated Flow GainLoss, was added to the Gain Loss Calculation category. This method (which is similar to the Seasonal GainLoss Flow Table method) uses values input according to the day of the year. Gain Loss is then determined by a three-dimensional table interpolation. Detailed documentation of this method may be found in the Simulation Objects Documentation online.

A new method category, Routing Parameters, is available when muskingumRouting is selected in the routingMethodCategory. This new category contains methods for inputting muskingum coefficient data as either K and X values or C0, C1, and C2 coefficients (scalar or time series). The variableMuskingum routing method has been eliminated. Users of this method should select muskingumRouting and the Input Time Series K and X method in the Routing Parameters category to attain the same results. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

Changes were made to timeLagRouting to conserve volume when using a monthly timestep and a monthly lag time. These changes require the user to use a monthly lag time if the timestep is monthly. Conversely, if the timestep is not monthly, a monthly lag time cannot be used.

A new method category, Reach Bank Storage Calculation, was added. Two methods are available: No Bank Storage and Average Flow Bank Storage. The Average Flow Bank Storage method is used to simulate hyporheic zone storage and return based on the flow rate in the reach. Detailed documentation of this method may be found in the Simulation Objects Documentation online.

The Date Range slot, used in the Seasonal GainLoss Flow Table method, is now one-based instead of zero-based. Users are required to increase the values in this slot by an integer of one to attain the same answers as in older models.

A new method, Interpolated GainLoss Uncertainty, was added to the Reach Uncertainty Calculation category. This method enables users to perform uncertainty calculations based on the uncertainty of the gain/loss coefficients and is available only when the Interpolated Flow GainLoss method is selected in the GainLoss Calculation category. Detailed documentation of this method may be found in the Simulation Objects Documentation online.

Diversions may now be input on the Water User. This allows the object to solve given either Diversion or Diversion Requested. An additional dispatch method was added to accommodate these changes. The object may now dispatch with one of the following two methods: solveStandAlone_givenDivReqDepReq or solveStandAlone_givenDiversion.

There are some limitations to this design. If the user is using rules to set both Diversion and Diversion Requested at different priorities (for the same timestep), the object must always resolve using the same dispatch method. For example, suppose that Diversion Requested is set by a rule and the object dispatches given Diversion Requested. Then, a higher priority rule sets Diversion. The object should re-dispatch given Diversion. However, it will be forced to re-solve with the same dispatch method. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The returnFlowSplitCalculation methods now include the Supplement Return Flow as well as the Return Flow if Supplement Diversion is selected in the Conjunctive Use category. If Supplement Return Flow is being calculated, a new slot, Total Return Flow, is used to represent the sum of the Return Flow and Supplement Return Flow. It is the Total Return Flow that is split into surface and groundwater components. If Supplement Return Flow is not being calculated, the Total Return Flow slot is not visible and only the Return Flow is split. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

Two new user methods, Population Requests and Regional Requests, were added to the Diversion and Depletion Request category. Population Requests is used to compute Diversion Requested and Depletion Requested based on the number of individuals in a population and the use rate per individual. Regional Requests is used to compute Diversion Requested and Depletion Requested based on the rate of water use for a region and the percentage of the region that applies to that particular rate. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

Also, the name of the Agricultural Requests method was changed to Irrigation Requests.

A new method category, Max Supplemental Request, was added to enable the user to calculate values for the Maximum Supplement Request slot based on groundwater elevation. Three methods are contained within this Category: None, Input Maximum Request, and GW Elevation Maximum Request. The new method category is dependent on the Supplement Diversion method in the Conjunctive Use method category. Models previously using the Maximum Supplement Request slot must use the Input Maximum Request method to get the same results. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

Diversion may now be input on the AggDiversionSite. This allows the object to solve given either Total Diversion or Total Diversion Requested. An additional dispatch method was added for both the lumped and sequential linking structures to accommodate these changes. For the sequential structure, the object may now dispatch with one of the following two methods: processSequential_givenDivReq or processSequential_givenDiversion. For the lumped linking structure the two dispatch methods are: processLumped_givenDivReq and processLumped_givenDiversion. As a result of these modifications, an AggDiversionSite object operating under the lumped linking structure no longer sets the Total Diversion Requested to 0.0 by default. All existing models that were using this default must now input zeros for the models to run correctly.

There are some limitations to this design. If the user is using rules to set both Total Diversion and Total Diversion Requested at different priorities (for the same timestep), the object must always resolve using the same dispatch method. For example, suppose that Total Diversion Requested is set by a rule and the object dispatches given Diversion Requested. Then, a higher priority rule sets Total Diversion. The object should re-dispatch given Diversion. However, it will be forced to re-solve with the same dispatch method. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The Sequential linking structure was modified so that Total Diversion is calculated as the lower value of Total Diversion Requested and Total Available Water. The Total Diversion is now propagated to the Incoming Available Water slot on the first WaterUser element. The Total Unused Water slot now represents the return flow from the Water User elements. Therefore old models must be updated in the following manner: 1.) Total Unused Water must be linked to the Return Flow slot on the object from which water is being diverted, 2) The link between Total Available Water and Incoming Available Water on the first WaterUser element must be deleted.

A new method category, Max Supplemental Request, was added to the AggDiversion Site for the lumped linking structure. This method category enables the user to calculate values for the Maximum Total Supplement Request slot based on groundwater elevation. Three methods are contained within this Category: None, Input Maximum Request, and GW Elevation Maximum Request. The new method category is dependent on the Supplement Diversion method in the Conjunctive Use method category. Models previously using the Maximum Supplement Request slot must use the Input Maximum Request method to get the same results. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The storage calculations on the Groundwater Storage object were modified to prevent a negative Storage from being calculated. If the Outflow exceeds the flow rate required to drain the aquifer in a timestep, the Outflow is decreased to that flow rate. If calculating Percolation and the sum of the Outflow and Percolation exceeds the flow rate required to drain the aquifer in a timestep, then both Outflow and Percolation are proportionally decreased so the sum of the two is equal to that flow rate. If however, Percolation is input, only Outflow is decreased. Detailed documentation of these calculations is available in the Dispatch Methods section of the Simulation Objects Documentation .

A new method category, Previous Elevation Calc, enables the user to input or calculate the previous timestep’s water table elevation based on the previous storage. The Previous Groundwater Elevation slot is used in conjunction with the Water User to determine the Maximum Supplement Request. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The Confluence object may now dispatch before the start of the run. The object checks upstream to obtain the earliest timestep at which an upstream object dispatches. Provided that its dispatch conditions are met, the Confluence may then dispatch at the earliest dispatch timestep of any upstream object.

Old models may be adversely affected by this change. If the Confluence object contains data before the start of the run, it may now solve and propagate data to other objects. Likewise, if the Confluence receives data from an upstream object it may now try to solve in an overdetermined state. In either case, the result is an overdetermination error expressed by one of the following error messages:

“Object is overdetermined”

“Attempting to set slot from multiple sources”

These errors may or may not be generated from the Confluence itself. The problem is fixed by deleting the excess data on the Confluence object for all pre-simulation timesteps.

A new method category, Diversion Request Calculation, is available on the Diversion Object. The default method, Input Diversion Request, performs no calculations. The Percent of Available method computes Diversion Requested as a specified percentage of the available water. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The solveMB_givenInflowReleaseRegSpill dispatch method was changed to solveMB_givenInflowRelease. The Regulated Spill slot is no longer a required known for the object to dispatch with this method. Also, the dispatch method is available regardless of the spill method in use. Detailed documentation of these methods may be found in the Simulation Objects Documentation online.

The Best Power Coefficient and Max Power Coefficient tables are now used whenever the BEST or MAX flag is set on Energy (regardless of whether or not the Power Coefficient is input).

The Pumped Storage Object is now able to model inflows from upstream. This enhancement required a change in slot notation. The flow into the reservoir as a result of pumping is accounted/calculated for in the Pumped Flow slot. The Inflow slot is used to represent inflow into the reservoir from upstream. Currently the object is only allowed to solve downstream (i.e. Inflow must be input and cannot be calculated). Old models using this object require three changes: the link between Inflow and Flow TO Pumped Storage must be removed, a link must be created between Pumped Flow and Flow TO Pumped Storage, and Inflow must be set to zero. Detailed documentation of this object may be found in the Simulation Objects Documentation online.

Documentation is now available for the pre-defined functions used in Rulebased Simulation. The documentation is reached by selecting Browse Rulebased Simulation Documentation from the online help menu.

A loaded ruleset is no longer allowed to be closed while remaining loaded. If a loaded ruleset is closed, the ruleset is automatically unloaded. The user will be asked to confirm this action upon closing the ruleset.

PRINT statements now always execute when their containing rule executes, regardless of whether or not any other statements within that rule succeed or not. Also, PRINT statements failing will not cause the containing rule to fail. E.g., if a PRINT statement encounters a NaN, a diagnostic is issued noting this fact, but the rule containing that print statement continues execution (as if nothing had happened).

When a RuleExpr is printed out by a PRINT statement or by a diagnostic, the RuleExpr’s text should be more readable, but could be different from what the user would see if they looked in a model file containing the same expression.

All NumericValues now have units. If none are specified then units of NONE are added. Textual representations of NumericValues with units of NONE do not have any unit string.

For the user this means they no longer need to type in units if there aren’t any. Units will now default to NONE, and units of NONE will never show up. This means that users now need to be a bit more careful about units because we aren’t as likely to notice when they forget and leave off units.

Checking was added to prevent the same name from being used multiple times in the same namespace. This was done to prevent the user from accidentally “hiding” a variable in an outer scope by declaring a variable of the same name in an inner scope.

An example of what is not allowed:

WITH (x = 1.0) DO

WITH (x = 2.0) DO

x

ENDWITH

ENDWITH

 

Did the writer really intend to refer to the innermost x? Maybe not. This problem can be corrected by changing either variable name:

WITH (x = 1.0) DO

WITH (y = 2.0) DO

x

ENDWITH

ENDWITH

This problem will be detected and reported by RiverWare whenever a ruleset is validated (to the CONSISTENT level), i.e., when the user explicitly asks to validate a rule or when the ruleset is executed.

Note that this change actually applies to all named objects, meaning variables as well as functions. If a function is accessible (may be called) from an expression, then its name may not be used as the name of a variable.

There is now a check for division by zero; both normal division and integer division (==- “/” and “DIV”). If the divisor is zero, then an error is issued (at evaluation time) and the rule fails.

IsNaN is now a built-in function of the Rule Language and not a predefined function (i.e. it is now represented by a button on the palette). It returns true if a NaN is encountered anywhere in the evaluation of the operand expression, false otherwise. Before it only returned true if the operand was a simple expression involving only an object/slot lookup. If it was more complicated and a NaN was encountered, then the execution failed (reporting that a NaN was encountered).

Returns a list which is identical to the given list except the item at the given position has been removed (positions begin with index 0).

Returns a list which is identical to the given list except the item at the given position has been replaced with the specified expression.

This defines variable, binds it to the value resulting from the evaluation of the “variable expression”, then returns the result of evaluating the “body expression” within the scope of this value.

Two 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 Simulation Objects Documentation online. Following is a list of new predefined functions:

The pre-defined function NetSubbasinDiversionRequirement now uses the MinBypass slot on the reach (if it exists and is known) as the minimum flow. Detailed documentation of this method may be found in the Rulebased Simulation Documentation online.

The NetSubbasinDiversionRequirement and NonShortDiversionRequirement functions now work with the Diversion Object as well as AggDiversionSites.

Import Object(s) and Export Object(s) menu items were added to the Model menu in the main workspace menubar. A new submenu was added to the Workspace menu. WorkspaceObjects contains all options that apply to objects on the workspace.

The appearance of the Open Object dialog has changed slightly. The most notable difference is the addition of a date/time field. The numbers shown in the Value field (to the right of the Slot Name field) are the slot values for the timestep expressed in the date/time field above. The left and right arrows in the date/time field can be used to move the date forwards or backwards. The number shown in the Value field will change accordingly. The figure on the following page shows the new appearance of the Open Object dialog.

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.