RiverWare is a new river basin modeling software tool which can load and run models built with PRSYM. This document describes new features, enhancements and changes that are included in RiverWare Version 1.0, released on May 7, 1997.

These changes are new to the executable since the release of PRSYM Version 3.1 on July 29, 1996.

Direct questions to CADSWES Technical Support at (303) 492-0908 or e-mail: usersupport@cadswes.colorado.edu

Many slots on Aggregate Diversion Site and Water User Objects have been renamed. In order to preserve the data in Aggregate Diversions of existing models, a conversion script, included with this release, must be run. The Perl language script is called modelConvert1.0, which is executed by typing the script name followed by the file name to be converted. Until the script is run or the model file is saved under the new executable, a confirmation window will be generated at load time warning that conversion may be necessary. For more details on this procedure, see“Renaming of Slots”.

Names of objects, slots, and DMIs are now limited to lowercase and capital letters, spaces, and underscores. Existing models which contain illegal characters in object and/or slot names will have these characters automatically converted to a legal text representation when the model is loaded. Expression slots, DMIs, and rules, however, will not automatically be updated to reflect the new names. Explicit updating of these references may be necessary.

A bug which prevented Level Power Reservoirs dispatching given Energy and Inflow from iterating to a proper Outflow has been fixed. Reservoirs dispatching under this dispatch method may also have incorrectly mass balanced. Differences in solutions should be expected between RiverWare Version 1.0 and versions of PRSYM when models contain any Reservoirs dispatching under this condition.

The Locator View, described in detail below, does not properly refresh the view of the workspace outside of the highlighted rectangle when objects or links are rearranged on the workspace with the Locator View dialog open. The dialog may be forced to refresh by closing and then re-opening it.

The menus at the top of the SCT can be made to “freeze” through a specific series of steps. This results in the menus’ sub-items not being displayed when the heading is selected. This situation will only occur if a run is initiated by dragging from the Run menu down to Start Run... before releasing the mouse and highlighting a cell during the run. When model execution ends, the menus will be frozen. To restore the use of the menus, select any heading and drag the mouse laterally to another heading. This is a GUI environment bug and may not manifest itself with all X window systems.

Running RiverWare under the Open Look environment causes several GUI peculiarities. The most notable problem is that confirmation dialogs are generated with only one option, the Yes button. In order for the GUI to behave similarly to XWindows, Galaxy users should launch the executable with an OpenLook “look and feel” command line argument:

Names of objects and slots are now limited to lowercase letters (a through z), capital letters (A through Z), spaces ( ), and underscores (_). Models previously built under versions of PRSYM may contain illegal characters in their slot or object names. These characters are now converted to legal text representations during model loading. A List Notice window is generated to indicate the illegal names detected.

The converted names are displayed in the Diagnostics Output Window next to the old names. The RiverWare assigned names may be changed to any other legal name once the model is loaded. Renaming automatically updates expression slots, but will not update constraints, DMIs, or rules. A regular expression search-and-replace is recommended to easily update external files. Illegal characters are converted to the character name surrounded by underscores as below:

The Model  Save command now saves the workspace over the currently loaded file without invoking a file chooser. Output values are saved with the model by default. To save the model under a different name, or to prevent output values from being included in the model file, select Model  Save As..., and follow the Saving procedure as in previous versions of PRSYM. The last Save As... parameters are then used for all subsequent Save commands. This new behavior is consistent with other standard software packages, but may confuse long-time users of PRSYM. It is recommended to write-protect important model files to protect them from accidental loss.

A new Summary Info... command is available from the Model menu in the main RiverWare workspace window. The command generates slot instantiation diagnostics and memory usage statistics in the Diagnostics Output Window. The messages provide information on the number and visibility status of instantiated slots as well as the number of slot proxies for each object on the workspace. Summary Info also provides total model memory usage statistics for each type of slot, including their total number and the memory required for an empty slot.

Failed table interpolations now abort the simulation run in addition to producing a diagnostic warning message. Previously, table interpolation errors allowed the run to continue, often causing fatal errors later in the simulation. A diagnostic warning message provides the interpolation lookup value, the table column at which the lookup failed, the data range of this column, and the row number where missing data was expected.

Values in Data Object slots marked Read Only are no longer cleared at the beginning of a run. Previously, values at timesteps flagged as OUTPUT were automatically reset to NaN. In order to preserve values which may be needed for future scenarios, slots marked as Read Only no longer have their outputs cleared.

RiverWare now aborts a simulation with an error when an attempt is made to write a value to an invalid timestep. This occurred most commonly in the Thermal Object’s Adjusted Load slot. The Thermal Object calculations write data to this slot at hourly intervals regardless of the model run timestep. This bug has been fixed, but there may be other instances where an attempt is made to write a value to an invalid timestep. When such an attempt is made, RiverWare will now abort simulation with the message “Failed to set value to: value because the date is not contained within the time series.” This error may be prevented by setting a single input value in the erroneous slot at the initial timestep. The input value will ensure that the user-configured timeseries is not reset to match the run control during run initialization.

The range of allowable timeseries dates has been expanded to include all years between 1800 and 2300 A.D. All simulation calculations and/or value assignments performed within this range are valid.

The Yearly timestep has been enabled as a valid simulation timestep. This step may be selected in the Run Control and slot Time Series Range dialogs.

The results of changing run times in the Run Control dialog have been updated to be more consistent. A change to the Initial, Finish, or Duration parameter now affects the run times as follows:

The behavior of the Run Control buttons has been revised. The Start button is no longer active during a paused run, and the Start and Step buttons now execute from the initial timestep when a run is stopped. The current behavior of all of the buttons is:

The Simulation Run Status window has been expanded to include the execution state Loading. This state is displayed if the Run Status window is open while a model is loading. Once the model has completed loading, the status reverts to Loaded.

A run may now be stopped during the initialization timestep. Previously, the Stop command would only be processed at the end of the timestep. In large models, this initialization could often take a significant amount of time to execute. The Stop command now intervenes to abort the run during this timestep.

The Target Operation code was rewritten to include a flag marking the Beginning of Target. A user-defined Beginning of Target timestep is marked with a TB, or Target Begin, flag in the Storage or Pool Elevation Edit Slot dialog. When solving a target operation, RiverWare searches backwards from the Target time until it finds a valid Target Begin flag. The Target Operation is solved using the value from the timestep prior to the Target Begin flag as an initial condition. If the timestep prior to the Target Begin does not have a valid Storage or Pool Elevation, or a valid input value exists between the Target Begin and the Target, the simulation aborts with an error. Likewise, if the Target Begin or Target timestep is already determined, simulation aborts. If no Target Begin flag is specified, RiverWare searches backwards to the first valid value and solves the Target Operation with this initial condition.

When a beginning of target is assumed in this manner, RiverWare marks the timestep where the Target Operation actually begins with a tb (lowercase) flag in the Open Slot dialog. This flag is treated as an output, and is automatically cleared at the start of the next run. Setting a Target Operation from an SCT generates both the Target and Target Begin flags, and clears any previous Target Operations which overlapped with the new range.

Models previously built under PRSYM do not have Target Begin flags. These models will solve as they did before. RiverWare searches backwards until it finds a valid value and assumes a Beginning of Target time immediately after the valid value. In certain cases, however, models may have previously been overdetermined. Some older models may be overwriting Inflows or Outflows set by a Target Operation earlier in the run. This is caused by the Target Operation searching backwards too far for a beginning of target value which is not yet known. Due to dispatching order and other Target Operations, new Inflows or Outflows may be calculated which invalidate the original Target Operation. These modeling errors will now produce a “Setting Slot from multiple sources” message and abort simulation. The Target Operation may be corrected by explicitly setting a Target Begin flag at a timestep following the overdetermination.

The TargetOperationCalculationCategory has been expanded to all Reservoir objects. This Category was previously available only on Power Reservoirs. The noTargetCalc Method, which performs no calculations, has also been added to the two existing Methods and is now the default Method for this Category. Setting a Target Operation with the noTargetCalc Method selected will produce an error and abort simulation.

A new User Method called noHydrologicInflow has been added to all Reservoirs. This is now the default Method for the HydrologicInflowCalculationCategory. This Method is used to model Reservoirs without the influence of hydrologic inflows, instantiates no slots, and requires no data.

The solveHydrologicInflow Method is no longer available on SlopePowerReservoirs and PumpedStorageReservoirs. Although the Method was previously selectable, it would not solve for timesteps where Hydrologic Inflow was not given on these Reservoirs.

The inputHydrologicInflow User Method has been modified not to initialize any linked slots at the Beginning of Run. The method previously initialized any unspecified Hydrologic Inflows and Hydrologic Inflow Adjust values to zero, and calculated the Hydrologic Inflow Net. It now checks that these slots are not linked prior to making any assignments. This allows values to propagate from other objects before dispatching.

A new User Method Category called Sediment Calculation has been added to all Reservoirs. The Category is used to enable algorithms which adjust reservoir Elevation Volume and Elevation Area relationships in response to sediment inflow. There are two Methods available for selection within this Category, the default No Sediment Calc and CRSS Sediment Calc. The default Method performs no computations. Models previously saved under PRSYM will produce identical results when the default No Sediment Calc Method is selected.

The CRSS Sediment Calc Method is a reservoir sediment distribution algorithm based on the US Bureau of Reclamation’s Empirical Area Reduction Method. Sediment distribution is calculated by an iterative loop in which a total volume loss is derived from an assumed top of sediment elevation. The volume loss and top of sediment elevation are recalculated at each iteration, until the volume loss is equal to the given sediment inflow. The loss at each iteration is determined by an algorithm which utilizes elevation/area and elevation/volume data for the reservoir in conjunction with an empirical equation. This equation requires user-specified parameters to indicate the portion of total area which is taken up by sediment at any given elevation. The equation dictates the shape of the accumulated sediment and has a close relationship to the elevation-volume and elevation-area characteristics of the reservoir. The new elevation/area and elevation/volume data is stored in a polynomial coefficient table. This table is recalculated after each timestep. The actual Elevation-Area and Elevation-Volume tables used by RiverWare are adjusted following convergence of the solution, but prior to the hydrologic simulation.

The CRSS Sediment Calc Method is modeled after sedimentation calculations performed by the US Bureau of Reclamation’s Colorado River Simulation System (CRSS) model. The Method is initialized during TIMESTEPBEGINRUN. The User Input Elev Area Data is used to create the initial Elevation Volume and Elevation Area Tables which are required by the simulation. The elevation increments at which the two tables’ values are generated are determined by the Elevation Vol_Area Table Increment slot value. The Method initialization also uses the User Input Elev Area Data to create the Elevation Area Table Used and Elevation Volume Table Used. These tables are used solely for recalculating sediment distribution in later timesteps. The elevation increments for these tables are equal to those of the User Input Elev Area Table. Variable table increments allow sedimentation parameters to be calculated with a different precision than that used for the general Elevation Area and Elevation Volume Tables.

Input data is critically important for this Method. The close relationship between the empirical area reduction equation and the shape of the reservoir (reflected in the elevAreaTableInput table) makes this Method very sensitive to input data. The physical characteristics of the given reservoir must be considered when choosing empirical parameters for this Method. The Bureau of Reclamation currently considers four types of reservoirs, each having a corresponding set of empirical area reduction parameters. The reservoir type classification is based on shape, the manner in which the reservoir is to be operated, and the size of the sediment particles to be deposited, with the primary emphasis on shape. Tables are used to classify the reservoirs based on these characteristics. Once the type has been established, the parameter values for that type can also be taken from tables in the literature. An incorrect set of parameters for a given reservoir will lead to an inability to achieve convergence on the sediment distribution.

It is also important to note that this Method does not recalculate Elevation Area or Elevation Volume Tables during time horizon dispatching such as Target Operations. Models which do not solve chronologically may produce errors due to incorrect Elevation Area and Elevation Volume Tables. Contact CASDWES staff for additional information before implementing this new Method.

Following is a list of slots relevant to this method, which includes the slot name in bold type, the (slot) as it appears in the code in parentheses, the slot type (Multislot, etc.), the unit type(s) in all caps (LENGTH, FLOW, etc.), a brief description of the slot in italics, and additional comments in plain type.

The following function is called within TIMESTEPBEGINRUN on the Reservoir object.

getInitialTable() This function performs initialization of the tables to be used in sediment calculations. The user-input elevAreaTableInput table is used in conjunction with the function simple_poly (see “Sediment Functions”) to generate a series of coefficient arrays. These coefficient values are then used in the following polynomial equation to calculate incremental volumes at given elevation points:

where ΔElev is the change in elevation between points in the elevAreaTableInput table. These volume values are used to create the initial Elevation Volume Table, required for initialization calculations in RiverWare. For consistency, incremental area values are recalculated using the same coefficient values in the function area_from_coeff (see below). These area values are then used to create the initial Elevation Area table, also required for initialization calculations.

The following functions are called within TIMESTEPBEGINTIMESTEP on the Reservoir object.

create_area_reduction() This function is called at the beginning of the area_reduction function (see below). It allocates memory storage for the local arrays used in subsequent calculations and copies elevation-area and elevation-volume data from the existing slots to these arrays. Slots are not used in the iterative calculations. This function then calls the relative_sediment (see below) function to calculate the proportion of the reservoir slice which consists of sediment for each elevation point.

area_from_coeff() This function is used to calculate areas at given elevations using the coefficients calculated in simple_poly (see “Sediment Functions”). It is called in both getInitialTable and area_reduction. The polynomial for calculating area values at elevation i is:

The area correction term is calculated within this function based on the elevation increment size and the coefficient values.

relative_sediment() This short function applies the empirical area reduction equation, using the user-input parameters, to calculate the proportion of the total area at a given elevation which is taken up by sediment. The equation uses a relative depth (depth of the given slice / total depth of the reservoir) passed in from the external call.

area_reduction() This function is the heart of the sedimentation calculations. It contains the iterative loop which distributes sediment in the reservoir until the estimated additional volume of sediment is equal to the sediment inflow at the current timestep.

create_area_reduction is first called to create and initialize the local variable arrays. Once elevation-area and elevation-volume data is in local arrays and relative sediment values are calculated for each elevation, the iterative convergence begins. A sediment elevation equal to the middle of the reservoir is used to seed the iteration for each timestep. This sediment elevation corresponds to the base of the distributed sediment load in the reservoir. A total area for this elevation is then calculated by the function area_from_coeff. For each elevation point above the sediment elevation, sediment areas are calculated. These sediment areas are determined from the relative sediment values previously solved in create_area_reduction, normalized to the relative sediment of the current base elevation guess. All area slices above the base elevation are adjusted to account for the space taken up by the current sediment load in the reservoir. All area slices below the base elevation are set equal to their total area.

Once the sediment has been distributed for the current sediment base elevation guess, the total volume of sediment is calculated using incremental elevation differences multiplied by the average sediment area for each increment. The estimated total sediment volume for the given timestep is equal to the sum of the incremental sediment volumes. This total volume is compared to the sediment inflow volume for the current timestep (the previous timestep’s sediment load). If the difference between the two volumes is within the convergence criterion, the iterative loop is exited. If the difference is not within the convergence criterion, the sediment elevation estimate is adjusted. If the calculated volume is greater than the actual volume, the sediment elevation is reduced by a fraction; if it is less than the actual volume, the sediment elevation is increased by a fraction. The steps described above are then repeated with the new sediment elevation.

Upon convergence, the Elevation Volume and Elevation Area Table slots are adjusted to reflect the new sediment distribution. This is done by subtracting the sediment areas and sediment incremental volumes from the existing areas and volumes in the tables.

revise_table() This function eliminates meaningless rows below the sediment elevation from the Elevation Volume and Elevation Area Tables.

simple_poly() This function calculates the polynomial coefficients (e.g. coeff[i]a1) that are used to determine area and volume values at given elevations. These coefficients are calculated based on elevation-area data, initially supplied by the User InputElev Area Data table and subsequently supplied by the existing Elevation Area Table slot.

area_table_increment() / vol_table_increment() These functions use interpolation to adjust the Elevation Area and Elevation Volume Table slots to the elevation increment specified by the user. It is generally expected that this increment will be smaller than that used in the calculations described above; the above calculations use the Elevation Volume Table Used and Elevation Area Table Used, which are incremented according to the User Input Elev Area Data table. The option of specifying a finer increment to be used by all other RiverWare hydrologic calculations saves computing time in the more approximate sedimentation calculations.

A new flag has been added to compute the maximum possible Outflow from a Reservoir on a given timestep. Setting the Max Capacity flag on a Reservoir Outflow slot forces the Outflow to equal the sum of the maximum (Turbine) Release and the maximum Spill. This flag should be used with great care, as its effects may cause downstream reservoirs to exceed their operating ranges. The use of this flag also depends heavily on having a reliable and accurate Regulated Spill Table and Max Turbine Q or Max Release table in order to attain reasonable Outflow values.

The Max Capacity flag is set by highlighting a simulation timestep on the Outflow slot of a Reservoir and selecting Timestep I/O  Max Capacity. RiverWare places an M at the selected timestep to indicate that the flag is active. This flag is treated as an INPUT, but does not require a value. If a valid Outflow value is present at the flagged timestep, it is ignored in the simulation; a new Outflow value is calculated and displayed at that timestep. This behavior is similar to the Max Capacity and Best Efficiency flags of the Energy slot and the Drift flags of the Regulated Spill and Bypass slots. A Reservoir which has the Outflow Max Capacity flag set may dispatch under any of the “givenOutflow” dispatch methods:

The Outflow Max Capacity flag may NOT be used on Reservoirs linked to a Canal, when solving for Hydrologic Inflow, or when solving a Target Operation.

The Outflow Max Capacity solution is iterative. The exact sequence of calculations in each iterative loop is dependent on the type of Reservoir and the selected Spill Calculation Method. In all cases, the maximum Spill and maximum controlled Release are calculated individually, then summed. If the selected Spill Method includes Regulated Spill, the current or previous Pool Elevation is used to look up the maximum Regulated Spill from the Regulated Spill Table. This value is set in the Regulated Spill slot, and the selected Spill Calculation Method is called. Any input Bypass and/or required Unregulated Spill are considered within the Spill Method. Next, the maximum release is calculated. If the Reservoir is a Power Reservoir, the selected Tailwater Calculation Method is executed to determine the Operating Head. This Operating Head or the Pool Elevation (in the case of Storage Reservoirs) is used to look up the maximum release from the Max Turbine Q or the Max Release table, respectively. Finally, the maximum release and the calculated Spill are added to determine the total maximum Outflow. This Outflow is used to mass balance the Reservoir. The iteration is repeated until Convergence is met or Max Iterations is exceeded.

The CRSSBankStorageCalc User Method has been modified so that negative Bank Storage values are reset to zero. This change was made to more precisely match the Bureau of Reclamation’s CRSS solution method. Users should be aware that the Change in Bank Storage slot is NOT adjusted when the Bank Storage is reset to zero. Since the Change in Bank Storage is used in the Reservoir mass balance, the reported Bank Storage value may not agree with Reservoir conditions.

A new User Method, called PanAndIceEvaporation has been added to the Evaporation and Precipitation Method Category of all Reservoirs. The Method is used to calculate evaporation from a reservoir whose surface may be partially covered with ice. The Method uses the Pan Ice Switch slot as an indicator of whether ice is present on the surface of the reservoir. A default 0.0 value in the Pan Ice Switch triggers the Method to solve for Evaporation as the product of the Pan Evaporation Coefficient, Pan Evaporation, and average Surface Area over the timestep. A value of 1.0 in the Pan Ice Switch triggers the Method to solve for Evaporation as the product of the Surface Area not blocked by Surface Ice Coverage, the average of the Min and Max Air Temperature, and the K Factor. In both cases, the Precipitation is calculated as the product of the Precipitation Rate and the average Surface Area over the timestep.

Following is a list of slots relevant to this method, which includes the slot name in bold type, the (slot) as it appears in the code in parentheses, the slot type (Multislot, etc.), the unit type(s) in all caps (LENGTH, FLOW, etc.), a brief description of the slot in italics, and additional comments in plain type.

A new getHydroCap utility has been designed to calculate Hydro Capacity more accurately. Previously, HydroCapacity was calculated as the product of the Maximum Power Coefficient and the maximum Turbine Release at the current Operating Head. A shortcoming of this approach was that the Operating Head used to determine the Power Coefficient and maximum Turbine Release did not reflect the changes brought about by the Turbine Release itself. For the purpose of computing Hydro Capacity, an iterative solution accounting for the changes in Operating Head as a result of the Turbine Release-affected Tailwater Elevation is necessary.

The iterative solution uses the maximum Turbine Release at the current Operating Head to calculate the Tailwater Elevation. This value is then used to compute a new potential Operating Head. The iteration continues until the difference in Operating Head is less than Convergence or the Maximum number of Iterations is reached. The Maximum Power Coefficient is then looked up in the Max Power Coefficient table using the new theoretical value for Operating Head. The advantage to using this potential value for Operating Head compared to using the actual Operating Head of the current reservoir at that timestep should now be apparent. In addition, if the current reservoir’s Tailwater Base Value is linked to the Backwater Elevation of a downstream Slope Power Reservoir, getHydroCap will now solve for the Backwater Elevation of the downstream reservoir and use that value as the Tailwater Base Value when calculating Tailwater Elevation. Finally, if the Turbine Release prior to the start of Hydro Capacity calculations is equal to the value in the Max Turbine Q table for the current Operating Head, or if Energy is flagged as MaxCapacity, Hydro Capacity is explicitly set to the value in the Power slot.

As might be expected, this iterative solution process may produce significantly different Hydro Capacity values than the PRSYM executables. These differences are most pronounced in cases where Hydro Capacity is explicitly set to the value in the Power slot and when the Tailwater Base Value of the current reservoir is linked to a downstream Slope Power Reservoir’s Backwater Elevation. The user will not notice any changes in the GUI as a result of this modification. This utility requires no new data.

The unitGeneratorPowerCalc Method now allows a maximum Power generation Limit for each generator type to be specified. The power calculated for the generator type(s) using this method may not exceed the user-specified Power production Limits for that type(s). Power is calculated in the same manner it was before; however, turbine power may be reduced to remain within the Limit. Reductions in power have no effect on Turbine Release. Flow is routed through the turbines regardless of the maximum Power generation Limit. The Generators Available table series slot has been modified to accommodate the new data: it is now an aggregate series slot named Generators Available and Limit. This slot contains two columns for each unit—one for the availability and one for the power limit of the particular generator type.

The way in which individual Pump and Generator Unit Types are defined has been modified for Pumped Storage and Power Reservoirs, respectively. The Pump Unit Types table and Generator Unit Types table now contain a single column. The Pump/Generator Number is no longer input into the first column; it is now automatically specified by the row label. The Pump/Generator Type is now specified in the first column. As rows are appended, the type of each new unit may be defined.

Checks are now performed during run intitialization to ensure that the number of units in the Pump/Generator Unit Types table matches the number of blocks in the Available Pumps/Generators Available and Limit tables. The number of unit types must also match the number of blocks in the Head vs. Pump Flow, Head vs. Pump Power, Best Generator Flow, Best Generator Power, Full Generator Flow, and Full Generator Power tables. If any of these criteria are violated, RiverWare aborts the run with a diagnostic error message.

Modifications were made as follows:

A new User Method Category called Gate Setting has been added to Pumped Storage Reservoirs. The new Category is used to enable a Method which looks up a Gate Setting based on the current Operating Head. There are two Methods available for selection within this Category: the default No Gate Setting Calc and Calculate Gate Setting. The default Method performs no computations. Models previously saved under PRSYM will produce identical results when the Calculate Gate Setting Method is selected.

Two slots are instantiated for the Calculate Gate Setting Method:

A new GroundWaterStorage object has been added to allow modeling of groundwater recharge, storage, and flow due to irrigation activities. The object is a simple underground storage container which fills with the groundwater portion of WaterUser return flow and spills based on a selected User Method. No attempt is made to account for Darcyian or aquifer properties. The Groundwater Object may be created by selecting its icon in the Palette and dragging it onto the workspace.

There are three general, or non-Method specific slots on the GroundWaterStorage object. Following is a list of slots relevant to this method, which includes the slot name in bold type, the (slot) as it appears in the code in parentheses, the slot type (Multislot, etc.), the unit type(s) in all caps (LENGTH, FLOW, etc.), a brief description of the slot in italics, and additional comments in plain type. They are:

The GroundWaterStorage object currently solves under one dispatch method only, solveGWMB_givenInflow. This dispatch requires that the current Inflow be known to solve. The Inflow may be input or linked to the GW Return Flow slot on a Water User Element. The calculated Outflow may be linked to the Return Flow or Local/Hydrologic Inflow slot on a Reach or Reservoir.

A User Method Category called GWOutflowCalc is available on the GroundWaterStorage object, used to enable algorithms which calculate Outflow. There are four Methods available for selection within this Category: the default none, TableFlow, LinearFlow, and ExponentialFlow. The default Method performs no computations and is not a valid selection.

The Table Flow Method iterates a mass balance calculation and a table lookup for Outflow based on the Storage, seen below, during the timestep. The iteration continues until Max Iterations is surpassed or the outflows found by both methods differ by less than Convergence.

The Linear Flow User Method calculates Outflow as a linear function of the previous timestep’s Storage. This Outflow is then used in a mass balance to determine the new Storage. If a Max GW Capacity has been entered and the new Storage exceeds it, the excess Storage is reallocated. Any excess volume of water is added to the previously computed Outflow.

The GW Alpha Param has no units. The value input into this slot must be in terms of the proper units to convert from Storage to Outflow (unit type of TIME-1), given the user units for each of these slots. For example, when Storage and Outflow are displayed with user units of acre-ft and cfs, respectively, the GW Alpha Param value must be in units of cfs/acre-ft. No enforcement of units is performed in this Method.

The Exponential Flow User Method calculates Outflow as an exponential function of the previous timestep’s Storage. This Outflow is then used in a mass balance to determine the new Storage. If a Max GW Capacity has been entered and the new Storage exceeds it, the excess Storage is reallocated. Any excess volume of water is added to the previously computed Outflow.

The GW Alpha Param has no units. The value input into this slot must be in terms of the proper units to convert from Storage to Outflow (unit type of TIME-1 x (LENGTH3)β-1), given the user units for each of these slots. For example, when Storage and Outflow are displayed with user units of acre-ft and cfs, respectively, and the GW Beta Param is 2, the GW Alpha Param must be in units of cfs/acre-ft2. No enforcement of units is performed in this Method.

The existing Reach code has been revised to improve efficiency, structure, and readability. Most changes relate to the internal structure of the Reach object and will be completely invisible to users. The visible changes and enhancements which are of concern to users are listed below:

Slots are now dependent on the user-selected routing Method. Only the slots required by the chosen routing Method will now appear in the Open Object slot list. This alleviates some previous confusion caused by unused slots in the object. Reaches are now consistent with all other RiverWare objects in only displaying slots which are required input or calculated within the method.

The hydrologicInflowCalculationCategory, its User Methods, and the slot Hydrologic Inflow, have all been changed from “hydrologic” to “local” Inflow. This was done to be consistent with Reservoir objects which already used the “local” nomenclature. The User Methods are now named inputLocalInflow and calcLocalInflow. The renamed localInflowCalculationCategory is now dependent on the NoRouting User Method, since it is the only Routing Method which accounts for local inflows.

Certain Routing Methods are inherently stable in their numerical schemes while others may be subject to considerable error. For conditionally unstable solution techniques, acceptable operating ranges may be determined analytically. Both the Muskingum-Cunge and the Macormack Methods now have stability checks based on user input parameters. An error message appears if the user has input values which could lead to instability.

A new check has been added to prevent Reaches from drying up due to large Diversions in the kinematicRouting, muskingumCungeRouting, and macCormackRouting methods. RiverWare now aborts simulation with an error message when the Diversion from a Reach is equal to its Inflow in any of these Methods.

Potential overdetermination is now being checked in TimeLagRouting. The checks compare the mass balance calculated values against the existing input slot value. If the values differ, this is taken as an indication of competing solutions. An overdetermination error message appears, and the simulation is aborted. The checks take place after each mass balance calculation in the TimeLag User Method.

When solving for Outflow in the variableTimeLagRouting Method, unknown Diversion and Local Inflow values prior to the first simulation timestep are now assumed to be zero. These values are required to solve for the side flow contribution to the Reach Outflow. Consistent with the Diversion and Local Inflow of Reservoirs, these side flows now default to zero if not input.

A new routing Method, SSARRrouting, has been created for Reaches. This routing Method is a simple storage routing with storage time calculated based on a user-input polynomial. It calculates outflow based only on user input or linked inflow values. It does not use local inflow, diversion, or return flow for the calculation.

The Impulse Response Routing Method now flags an error and aborts the run if the Inflow at the previous timestep is not known. A previous Inflow is required by this routing solution type and should be input or calculated.

A new User Method Category called stageVolumeCalculation has been added to Reaches objects. The Category is used to enable algorithms which calculate the water surface elevation at the top and bottom of a Reach as well as the volume of water contained in that reach. It is anticipated that this calculation will be used to determine the maximum diversion from gravity flow structures. The Category is only available when the timeLagRouting Method has been selected. There are two Methods available for selection within this Category, the default noCalc and tableLookUp. The default Method performs no computations. This Method Category is executed after the Reach Routing Methods and currently does not influence mass balance in any way.

The tableLookUp User Method calculates the Inflow Stage and Outflow Stage of a reach if these values are neither linked nor INPUT. The Inflow Stage Table and Outflow Stage Table are used to look up the water surface elevation based on the flow through the channel at that point. Once both Inflow and Outflow Stages have been computed, the Reach Volume is calculated based on the previous volume of water in the reach and the difference in Inflow and Outflow over the current timestep. An initial Reach Volume must be specified to solve this Method.

The default display precision for values in the Mannings Roughness n and Energy Slope slots has been increased to 5. These parameters are traditionally on the order of 10-2 and 10-3. The 5 digits beyond the decimal point are necessary to view the full precision of these parameters.

The Aggregate Diversion Site and Water Users have been extensively modified. Models previously built under PRSYM which contain Aggregate Diversions will need to be converted before running correctly under RiverWare Version 1.0. Several modifications are necessary.

Seven slots on the Aggregate Diversion Site Object and the Water User Object have been renamed. In order to preserve the data in models previously built under PRSYM, a conversion script must be run before loading these model in this release. The Perl script, called modelConvert1.0, is included in the executable package for RiverWare Release 1.0. A Perl language interpreter is required to run this script. If you do not have Perl on your system, contact CADSWES for assistance in converting model files. The conversion script changes the following slots:

The script is executed by running it with the name of the model file to be converted as an argument. For example, to convert the model MyModel, simply type:

The model is converted, and a backup of MyModel is created with the name MyModel.old.

A new User Method Category called returnFlowCalculation has been added to Aggregate Diversion Site Water User elements. The Category is used to enable algorithms which calculate the quantity of Return Flow from Water Users when the noStructure or sequentialStructure LinkStructures are selected. When the lumpedStructure LinkStructure is selected, Return Flow is not calculated for each Water User element; it is calculated on the Aggregate Object by subtracting the Total Depletion Requested from the Total Diversion Requested. There are four Methods available for selection within the returnFlowCalculation Category: the default None, Fraction Return Flow, Proportional Shortage, and Variable Efficiency. The default Method performs no computations, and no Return Flow is generated. It is not a valid selection.

The Fraction Return Flow Method calculates Return Flow as a fraction of the Diversion delivered.

The Proportional Shortage Method calculates Return Flow as the difference between the Diversion delivered and the Depletion Requested, scaled if a shortage exists. If the entire Diversion Requested is delivered, the Depletion is simply the Depletion Requested. If the Diversion Requested cannot be met, the Depletion is the Depletion Requested, scaled by the percentage of shortage in Diversion. The Depletion is a constant proportion of the Diversion, regardless of shortage. The Return Flow is the difference between the Diversion and the Depletion.

The Variable Efficiency Method calculates Return Flow as the difference between the Diversion delivered and the Depletion Requested, up to a Maximum Efficiency. The theoretical efficiency of the requested depletion is the ratio of the Depletion Requested to the Diversion. If this theoretical efficiency is less than the Maximum Efficiency, the Depletion is granted. If the theoretical efficiency is greater than the Maximum Efficiency, the actual Depletion is reduced to exactly correspond to the Maximum Efficiency. Return Flow is the difference between the Diversion and the Depletion.

A new User Method Category called returnFlowSplitCalculation has been added to Aggregate Diversion Site Water User elements. The Category is used to enable algorithms which calculate the proportions of Surface Return Flow and GW Return Flow. This Category is only valid when a returnFlowCalculation Method is selected. There are three Methods available for selection within the returnFlowSplitCalculation Category: the default No Split, Split Return Flow Fraction, and Split Return Flow Efficiency. The default Method performs no computations. The Split Return Flow Efficiency Method is only valid when the Variable Efficiency returnFlowCalculation Method is selected.

The Split Return Flow Fraction Method splits Return Flow into surface and groundwater components according to the Fraction GW Return Flow.

The Split Return Flow Efficiency Method splits Return Flow into surface and groundwater components according to the computed Efficiency, Maximum Efficiency, and the GW Split Adjustment Factor. This method is based on the USBR return flow split calculation. The groundwater portion of the Return Flow is found by:

Water Users and lumped structure Aggregate Diversion Sites now assume a Diversion Requested of zero if not set by the user. This allows the object to dispatch in cases where the user has not supplied enough data.

Negative Return Flow values may now be calculated for Water Users when their Diversion Requested is zero. This situation occurs when the Consumed Flow is set to a value larger than the Diversion Delivered. Negative Return Flows were previously calculated only when Diversion Requested was non-zero.

The slots Total Diversion Requested and Total Depletion Requested have been added to Aggregate Diversion Sites for all Linking Structures. These MultiSlots sum the diversion and depletion requests from individual Water User elements. The slots will not contain a value if any of the element values at that timestep are invalid. The slot values are not adjusted during shortages, when the diversion and depletion requests may not be met.

The slot Total Depletion has been added to Aggregate Diversion Sites for Lumped and Sequential Structures. This SeriesSlot is set equal to the sum of the Depletion slots of individual Water User elements. The Total Depletion slot will not contain a value for any timestep at which any of the element Depletion values are invalid. The slot value reflects any adjustments made to individual Depletions in time of shortage.

Water Quality may now be enabled as a Post Process when the Rulebased Simulation Controller is active. The same WQ Constituents, WQ Solution Approaches, and User Methods which are available with the Simulation Controller may be selected for Rulebased Simulation. To invoke the window for enabling Water Quality, select the View Controller Specific Parameters button in the Run Control dialog.

The Distributed Annual Salt Loading User Method has been modified to internally calculate the annual mass and monthly non-shortage return flow salt mass. Previously, the monthly data was calculated by the user and input directly into the Non Shortage Return Flow Salt Mass slot through the data management interface (DMI).

Three new slots have been added to implement the change. The annual salt mass for the current year is stored in the new Non Shortage Annual Return Flow Salt Mass slot. This value is calculated in January by summing the products of each month’s Return Flow volume and Return Flow Salinity Pickup. Since this value is only valid for the current year of the simulation, it has been made invisible to the user. A monthly non shortage salt mass is calculated each month by multiplying the annual salt mass by the percentage for that month specified in the new Percent of Annual Mass table. The monthly value is stored as a local variable during execution of the method. The monthly diversion demand has also been converted from a user input series slot to an internally calculated value. The equivalent annual shortage is computed by dividing the percent of shortage in a month’s diversion by the percentage of annual demand for that month. This value is specified in the new Percent of Annual Demand table. The remainder of the method is unchanged.

The check for minimum flow in the Distribute Annual Salt Loading is no longer hard wired at 10 acre-feet per month. It now uses the Min value on the Outflow slot of the Reach to which the Diversion is linked. This value is scaled from its acre-feet/month units based on the number of days in the current month. Simulation aborts with an error if this value has not been set by the user.

The check for outflow minimum salt concentration in Variable Salt Pickup With Debting is no longer hard wired at 50 mg/L. It now uses the Min value on the Outflow Salt Concentration slot of the Reach to which the Diversion is linked. Simulation aborts with an error if this value is needed and has not been set by the user.

A new Bank Storage Salt User Method Category is available to specify whether or not to account for Bank Storage effects in Salinity calculations. The two user-selectable Methods in this Category are No Bank Storage Salt and Bank Storage Salt. No Bank Storage Salt may be selected regardless of whether or not Bank Storage is calculated for the Reservoir. Bank Storage Salt may only be selected if Bank Storage is calculated for the reservoir.

A new User Method Category called Optimization Spill Computation has been added to all Reservoir objects. This Category is only available when the independentLinearizations Method is selected in the Optimization Power Computation Category. The Optimization Spill Computation Category contains six Methods for the linearization of spillway physical constraints. The selected Method should reflect the number and types of spillways being modeled and must be the same as the selected Method in Simulation. The physical data for all selected spillways is combined into a single Storage vs. Spill table. This table is then linearized according to the linearization Method selected in the Spill Lower Bound MTLE Category and the Spill Upper Bound MTGE Category. The available Methods for the Spill Lower Bound MTLE Category are Piecewise and Line. The only available Method for the Spill Upper Bound MTGE Category is Line.

All of the Methods solve by generating a composite Spill Bounds Linearization Table from the points in the Unregulated, Regulated, and/or Bypass Spill Tables. The first column of the Spill Bounds Linearization Table contains monotonically increasing Storage values. These values correspond to the combined set of Pool Elevation data points in the Spill Tables relevant to the selected Method. The second and third columns are the Spill Lower Bound and Spill Upper Bound at each of these Storage values. The Spill Lower Bound is equal to the required Unregulated Spill at the given Storage, or zero, if the selected Method does not include Unregulated Spill. The Spill Upper Bound is equal to the sum of the required Unregulated Spill, the maximum Regulated Spill, and the maximum Bypass at the given Storage, whichever apply.

Since the Storage data points are taken from the combined set of Pool Elevations in all applicable tables, some of the Storage points may not have a corresponding Pool Elevation in one or more of the individual tables. In these cases, a spill value for the table is linearly interpolated from the two Pool Elevations which most nearly correspond to the given Storage. This ensures that the resolution of the Spill Bounds Linearization Table is at least as fine as that of the most precise individual Spill Table.

The Spill Bounds Linearization Table is linearized according to the parameters specified in the Spill Upper Bound LP Param and Spill Lower Bound LP Param tables. The Spill Upper Bound LP Param table requires two Storage values (in rows) to linearize with the Line Method. The Spill Lower Bound LP Param table requires either two Storage values to linearize with the Line Method or more than two Storage values (in rows) to linearize with the Piecewise Method. The optimization physical constraints for Spill are generated from these linearizations in terms of reservoir Storage. The slots which require inputs or receive output for all Spill methods are:

In addition, the slots which require inputs for individual spill Methods are:

This Method requires no input and generates constraints for zero Spill.

This Method generates constraints for total Spill equal to the required Unregulated Spill.

This Method generates a constraint for total Spill less than the maximum Regulated Spill.

This Method generates two constraints: total Spill greater than the required Unregulated Spill, and total Spill less than the sum of the Unregulated Spill and the maximum Regulated Spill.

This Method generates a constraint for total Spill less than the sum of the maximum Regulated and Bypass Spills.

This Method generates two constraints: total Spill greater than the required Unregulated Spill, and total Spill less than the sum of the Unregulated Spill, maximum Regulated Spill, and maximum Bypass Spill.

A new User Method Category called Optimization Power Computation has been added to Power Reservoir objects. This Category contains two Methods for the generation of power production optimization constraints, the default independentLinearizations and lambdaMethod. Both Methods are used to optimize the Outflow and Power (Energy). independentLinearization was the only available solution in PRSYM executables.

independentLinearization optimizes power production through linearizations of Turbine Capacity, Best Turbine Flow, and Power. Each of these parameters may be linearized differently depending on the context in which they appear within a constraint. The possible constraint contexts for each of the three parameters are: STLE (single term less than or equal to), STGE (single term greater than or equal to), MTLE (multi-term less than or equal to), and MTGE (multi-term greater than or equal to). These combinations give rise to 12 new User Method Categories for which a linearization Method must be selected. The available Methods for each Category may include: Line, Tangent, Piecewise, and Substitution, depending on the Category. For more information on Independent Linearization solutions, see the Technical Reference Manual or contact CADSWES staff.

Selection of the new lambdaMethod User Method also requires selection of a tailwater calculation Method. The Optimization Tailwater Computation Category contains four User Methods: the default optTWValueOnly, optTWBaseValueOnly, optTWBaseValuePlusLookupTable, and optTWStageFlowLookupTable. These Methods are analagous to the existing Simulation Methods with the same names, and require the same data. If a Simulation run is to follow Optimization, both should use the same tailwater Method to guarantee accurate results.

The Power Lambda calculation selects the maximum Turbine Release within the region defined by legal operating points called lambda points, which consist of a combination of values (called Lambda Coefficients) for Pool Elevation, OperatingHead, Turbine Release and other related quantities corresponding to a physically realizable scenario. The lambda points are implicitly specified by the user through values in the Power Lambda Coefficients Params table and explicitly computed during the Optimization Beginning of Run. A set of physical constraints is generated by multiplying each Coefficient with a lambda variable. These lambda constraints are used by CPLEX to force the lambda variables to coincide with the other model variables.

The Power Lambda Coefficients Params (PLCP) table is the only slot requiring user input, other than the physical data normally required to solve plantPowerCalc with the Simulation controller. At least one realistic Pool Elevation and Tailwater Base Value must be specified in the PLCP table. Outflow values may be optionally specified. An Outflow is implicitly supplemented with zero, the Best Turbine Q, and the Max Turbine Q. A lambda point is computed by RiverWare for every possible combination of parameter values in the table columns. Each of the combinations corresponds to a unique operating state, whose other parameters may be calculated by iterating plantPowerCalc with the selected Optimization Tailwater Calculation Category. If a combination of values does not correspond to a feasible operational state, it is omitted from consideration.

The computed Lambda Points are stored in the Power Lambda Coefficients (PLC) table. The first two columns of the table correspond to the Coefficients from the first two columns of the PLCP table. The remaining columns in the PLC table are the calculated Optimization parameters: Tailwater Elevation, Operating Head, Spill, Turbine Release, Power, Best Turbine Flow, and Hydro Capacity. Every row in the PLC table represents a valid lambda point.

The lambdaMethod uses the following slots in addition to those required for the selected Optimization Tailwater Calculation Method and plantPowerCalc:

A new User Method Category called Optimization Backwater Computation has been added to Slope Power Reservoir objects. The Category contains two Methods for the generation of backwater curve optimization constraints: the default independentLinearizations and lambdaMethod. Both Methods are used to optimize Storage, Backwater Elevation, and Intermediate Backwater Elevation. independentLinearizations was the only available solution for PRSYM executables.

This method optimizes the reservoir backwater by linearizing Backwater Elevation and Wedge Storage. Each of these parameters may be linearized differently depending on the context in which they appear within a constraint. The possible constraint contexts for Wedge storage are: STLE (single term less than or equal to), STGE (single term greater than or equal to), MTLE (multi-term less than or equal to), and MTGE (multi-term greater than or equal to). The possible constraint contexts for Backwater Elevation are: STLE (single term less than or equal to) and STGE (single term greater than or equal to). A linearization Method must be selected for each of the six resulting User Method Categories. The available Methods may include: Line, Tangent, Piecewise, and Substitution, depending on the Category. For more information on Independent Linearization solutions, see the Technical Reference Manual or contact CADSWES staff.

The new lambdaMethod User Method optimizes Storage and Backwater Elevations within the region defined by legal operating points called lambda points. A lambda point consists of a combination of values (called Lambda Coefficients) for Backwater Elevation and other related quantities which corresponds to a physically realizable scenario. The lambda points are implicitly specified by the user through values in the Backwater Lambda LP Parameters table and explicitly computed during the Optimization Beginning of Run. A set of physical constraints is generated by multiplying each Coefficient with a lambda variable. The lambda constraints are used by CPLEX to solve for reservoir Storage and Outflow.

The Backwater Lambda LP Parameters (BLLPP) table is the only slot requiring user input, other than the physical data required to solve SlopePowerReservoirs with the Simulation controller. At least one realistic Headwater Elevation must be specified in the BLLPP table. Also at least one Inflow and/or Outflow for each segment is required, depending on the Reservoir’s configuration. The maximum and minimum Hydrologic Inflows during the run are automatically considered as potential Lambda Coefficients in addition to any user input Hydrologic Inflows in the BLLPP table. A lambda point is computed by RiverWare for every possible combination of Parameter values in the table columns. If a combination of values does not correspond to a feasible operational state, it is omitted from consideration. In certain cases, however, Inflow, Outflow, or Hydrologic Inflow values may not be required; the irrelevant columns in the BLLPP table are then omitted from the lambda point calculation. If any values are input into irrelevant columns, a warning message is issued at run time. The cases for which values are not required are:

Inflow is unnecessary if the a Profile Coeff Table parameter is zero for all segments. In this case, Inflow does not influence the backwater curve.

Outflow is unnecessary if the b Profile Coeff Table parameter is zero for all segments. In this case, Outflow does not influence the backwater curve.

Hydrologic Inflows are unnecessary if either the a or the wc Profile Coeff Table parameters are zero for all segments. In this case, Hydrologic Inflows do not influence the backwater curve. The minimum and maximum values are not treated as Lambda Coefficients.

The computed Lambda Points are stored in the Backwater Lambda Coefficients (BLC) table. The first columns of the table correspond to the Coefficients from the BLLPP table plus additional columns for time lagged Inflows and Outflows. The number of Inflow and Outflow columns is determined by the number of impulse response coefficients in the Profile Coeff Table. The remaining columns in the BLC table are the calculated Optimization parameters: Storage, Backwater Elevation, and Intermediate Backwater Elevations for each reservoir segment. Every row in the BLC table represents a valid lambda point. There is a row for each possible combination of Lambda Coefficients, including the lagged flows. The number of lambda point rows grows very quickly when multiple time lag columns compound the combinations. Since an excessive number of lambda points is unnecessary and affects performance, the number of lambda points is limited to 1,000.

The lambdaMethod uses the following slots in addition to those required for backwater calculation with the Simulation Controller:

RiverWare now automatically creates an output file when an infeasible optimization model is run. The file, called OPT_cplex_prob.*.iis, contains the “irreducibly inconsistent set” which represents the smallest infeasible problem from the failed run. This is typically a small set of inconsistent equations from which the erroneous constraint(s) can be deduced. The generation of this file is accompanied by a message window, indicating the exact name and path of the output file.

RiverWare-generated optimization files which begin with OPT_ are no longer saved in the RiverWare executable directory. All of these files, including those selected in the Optimization Controller Parameters dialog, are now saved in a sub-directory tree designed to facilitate management of this important debugging information.

The directory into which the files are saved is determined as follows:

Within this directory, a sub-directory is created as:

Within this directory, an optional sub-directory may be created as:

For example: user johndoe running optimization with the RiverWare_OPT_DIR environment variable set to /RiverWare/Optimization, and the File Directory: set to run1, would generate OPT_ files as:

If the File Directory: were then deselected, and the RiverWare_OPT_DIR environment variable were unset, OPT_ files would be generated as:

In all cases, the directory to which optimization files are written is displayed as a green highlighted message in the Diagnostics Output Window.

The PrsymOptParams file which contained optimization parameters for versions of PRSYM, has been divided into two files. The optimization parameters which are used exclusively by RiverWare are now contained in a file called goals.par. The optimization parameters which are required by the CPLEX solver are now contained in a file called cplex.par. The cplex.par file is passed directly to the solver as a command line argument, allowing a solution to be duplicated outside of the RiverWare executable. This is useful to access solver debugging capabilities which are unavailable during a RiverWare run.

The CPLEXPARFILE environment variable must be set as the path to the cplex.par file in order for this file to be located by the CPLEX solver. The path may be specified as an absolute path or a relative path from the directory set as the RiverWare_HOME environment variable.

Multiple term (MTLE & MTGE) Piecewise linearized functions are now checked for consistent curvature during Optimization runs. Violation of concavity or convexity is indicated by a warning message of the type:

The check to ensure that convexity or concavity is preserved is performed given the user approximation points, piecewise slopes, intercept, number of user approximation points, and the linearization context class of each table. The appropriate curvature is dependent upon the context, where MTLE and MTGE cases should yield convex and concave functions, respectively.

Two dimensional table values are checked by substituting the independent value into the piecewise function where the corresponding dependent value is computed. Since three-dimensional tables are linearized with respect to only one z point, their values are checked by examining independent values which are greater and less than the specified z point wherever an interpolation for the z approximation point is required. This provides a means with which to check for erroneous data which could potentially be used during actual interpolation. The appropriate independent values are then checked by substitution into the piecewise function where the corresponding dependent value is computed.

For both two-dimensional and three-dimensional tables, the dependent value is then compared to the table value to determine if the expected curvature is violated. In addition, piecewise slopes are checked relative to one another; convex and concave functions should yield slopes which are increasing and decreasing relative to one another, respectively.

There is now the ability for Rulebased Simulation to solve mass balances on Reservoir objects at any timestep. This was accomplished by adding three new mass balance methods on the Reservoir class that can be called from within a rule:

Reservoir:massBalanceSolveInflow (double out, double stor, double storPrev, Date_Time *dateTime, double &in)

Reservoir:massBalanceSolveOutflow (double in, double stor, double storPrev, Date_Time *dateTime, double &out)

Reservoir:massBalanceSolveStorage (double in, double out, double storPrev, Date_Time *dateTime, double &stor)

These functions differ from the standard massBalance functions in that they solve for the desired value in two steps. First, the given Inflow, Outflow, or Storage, as well as the Previous storage, and the time step (variables in, out, stor, storPrev, dateTime) provided by the Rulebased Simulation are converted to local variables of the MethodInfo class. Then, these functions execute the standard Reservoir:massBalanceSolve... (MethodInfo *LocalInfo) function which solves the mass balance. This standard method is the one used in the regular Simulation mode. The value computed by the massBalanceSolve... (MethodInfo *LocalInfo) function is then passed back to the rule as the desired &in, &out, or &stor.

Several new Tcl-based functions have been added to the RuleBased Simulation language which access the new SubBasin functionality from within rules. They are:

C_GetAllNamedBasins

C_GetObjectsInBasin basinDesignator

C_AggOverTime basinDesignator slotName aggFunc aggFilter scale units <startDate <endDate>>

C_AggOverObj basinDesignator slotName aggFunc aggFilter scale units <startDate <endDate>>

C_AggOverTimeObj basinDesignator slotName aggFunc1 aggFunc2 aggFilter scale units <startDate <endDate>>

C_AggOverObjTime basinDesignator slotName aggFunc1 aggFunc2 aggFilter scale units <startDate <endDate>>

Where the arguments to the above functions are specified as:

Two new functions have been added to facilitate unit conversions. They are:

C_GetStepSeconds <dateTime>

C_ConvertValue fromValue fromScale fromUnits toScale toUnits <dateTime>

A new function has been added which computes the Diversion required to satisfy the Diversion Requests of all WaterUsers of an AggDiversionSite at any timestep of the simulation. This function may be called from within a rule for AggDiversionSites using the Sequential Linking Structure only. In order to perform the calculation, the algorithm executes the selected returnFlowCalculation and returnFlowSplitCalculation Methods on each WaterUser. These account for all possibilities of Return Flow linking and quantities when computing the variable totalReq, which represents the Diversion requirement for satisfaction of all WaterUser requests. The function is defined as:

A toolbar has been added to the main RiverWare Workspace window. It contains buttons for accessing commonly used commands and dialogs. The buttons are:

Many of the keyboard shortcuts for commonly used commands have been modified to be consistent between different RiverWare dialogs, to conform to accepted software standards, and to eliminate conflicts arising from duplicate shortcuts. In dialog menus, keyboard shortcuts appear to the right of the commands they execute. The shortcuts are:

The main RiverWare Workspace menus are now pinnable. Clicking on the dashed line at the top of an open menu converts the menu into a free window. This allows repeated commands to be executed without first having to re-open the menu. To close a pinned menu, kill the Xwindows frame in which it resides by clicking twice on the upper left corner of the window.

The placement and size of the main Workspace window is now preserved from one RiverWare session to the next. The location in the Xwindows monitor and the size of the window are saved in the.vgalaxy.1.vr file in the user’s home directory. The placement and location are applied when the RiverWare executable is initially launched and are then automatically saved from the current configuration when the session is ended.

A new function has been added to facilitate movement around the workspace of large models. Selecting the Locator View... command from the Workspace menu creates a miniature representation of the entire workspace in a new window. A highlighted frame indicates the portion of the workspace over which the main RiverWare window is currently located. Dragging this frame to a different part of the workspace shifts the main RiverWare window’s field of view to match the locator. A specific object may be also be brought into view by selecting it from the Locate menu heading on the locator window.

The View Methods and View Slots buttons on the Open Object dialog have been converted to an option menu. This menu is labeled as View:. It indicates the currently selected dialog view from two options, Slots and Methods. Slots view is the default.

A SubBasin is a collection of workspace simulation objects which are grouped under a single name. For example, it may be convenient to specify a SubBasin named “Main River” whose members are all of the Reach and Reservoir objects along the main stem of a riverbasin. The name of the SubBasin may then be used to efficiently represent all of its member objects in calculations. Currently, the use of SubBasin names is only supported for Expression Slots and Optimization Constraints. This functionality will be expanded to the Rulebased Simulation Structured Editor in upcoming releases.

SubBasins and their memberships are set through the SubBasin Manager. This dialog is invoked by selecting Edit SubBasins... from the Workspace menu heading. The default SubBasin is the “Entire Network.” This SubBasin may not be deleted, modified, or renamed. It contains all of the objects on the workspace with the exception of Data Objects. Data Objects may never be included in any SubBasin membership.

Selecting the tree-view arrow to the left of a SubBasin name will display the list of its members. If any Aggregate Objects are members of the SubBasin, selecting the tree-view arrow to the left of their name(s) will display a list of their member Elements. Each of these Aggregate Elements is included in the SubBasin. Elements may not be individually included or excluded from a SubBasin definition. The name of a SubBasin may be changed by selecting its existing name and typing a new name into the resulting edit window. The commands available from the Edit SubBasins dialog are:

File  Close to close the SubBasin Manager dialog. This is the same as clicking the Close button at the bottom of the dialog.

SubBasin  Insert New Before to define a new SubBasin with the selected objects on the workspace and to insert the name before the currently highlighted SubBasin name.

SubBasin  Insert New After to define a new SubBasin with the selected objects on the workspace and to insert the name after the currently highlighted SubBasin name.

SubBasin  Append New to define a new SubBasin with the selected objects on the workspace and to insert the name at the end of the SubBasin list.

SubBasin  Update From Workspace to redefine the currently highlighted SubBasin. The membership will be cleared and replaced by the selected objects on the workspace.

SubBasin  Select on Workspace to highlight the members of the currently selected SubBasin on the workspace.

Object  List SubBasin Membership to bring up a new window displaying the SubBasin(s) to which the selected object belongs.

The Remove button will delete the currently selected SubBasin or member.

The Close button closes the SubBasin Manager dialog.

An object’s membership may also be directly displayed without invoking the Edit SubBasins dialog. To do this, first highlight a single object on the workspace. Next, select Workspace  List SubBasin Membership from the main RiverWare menu bar. A new window appears listing all SubBasins to which the selected object belongs.

The dialog for determining which slot is displayed in an SCT row has been updated. Selecting Rows  Set Slot... now brings up the SCT Row Type slot selector only if there are objects on the workspace. The Object types: option menu has been improved to list only the object types of which at least one member exists on the workspace. These object types are listed in alphabetical order. To facilitate building an SCT, the SCT Row Type dialog is invoked with a default selection corresponding to the object and slot of the last row to have been configured. This allows many rows to be assigned to slots on the same object without having to reselect the object type and object for each occurrence.

The view of row detail values may now be toggled when Editing: is turned OFF. This provides access to detail timesteps for changing their values. The summary type of a row’s detail values may also be changed by selecting Values  Summary Type.... These additional functions provide flexibility in non-Edit mode, while safeguarding the configuration of the original SCT.

Setting detail values in a closed row through the Values  Set Detail Values command is no longer supported. This functionality was dangerous, as it allowed values and flags to be overwritten without any visual confirmation of the effects. Detail rows must now be open for this command to be enabled. The old behavior will continue to exist in SCTs until the first time their rows are toggled and the SCT is saved.

Although DMIs may now exit with a -1 return status, DMI generated error messages will not be properly interpreted by RiverWare. For proper handling of errors and messages, the accepted exit codes are:

Valid keyword=value pairs have been expanded to include flags. This keyword can enable the importing or exporting of the SeriesSlot flags at every timestep, in addition to the slot values. The possible values for this keyword are true and false.

A keyword=value of the type:

will cause SeriesSlot flags (INPUT, OUTPUT, TARGET, TARGET_BEGIN, BEST_EFFICIENCY, MAX_CAPACITY, and DRIFT) to be imported or exported with the data. This is an optional keyword=value pair which defaults to false if not specified.

Values may no longer include spaces (  ), colons (:), or exclamation points (!). Due to changes in the parsing of DMI control files, these characters are now used as delimiters. Their use within a value field will cause a syntax error and prevent proper execution of the DMI. As there are no known DMIs currently using this punctuation, the change should not affect any existing models.

Control File Object and Slot Wildcards have been expanded to include subBasins and dispatch slots, respectively. An object.slot specification of the type:

will match any <slot(s)> within the subBasin <basinname>. Similarly, an object.slot specification of the type:

will match any dispatching slot in the given <object(s)>. These new object.slot wildcards may be used in conjunction with the flags=true optional keyword=value to import or export all of the values and flags for the dispatching slots of a subBasin. This type of DMI allows the information required to uniquely reproduce a scenario to be moved between subBasins of different models. For more information on using DMIs towards this end, contact CADSWES staff.

Rulesets for Rulebased Simulation may now be loaded using the RiverWare Command Language. The syntax for this new command is:

where ruleset is a valid file pathname to a ruleset.

Functionality has grown extensively over the past several releases. In order to put new features into perspective, an overview of the existing state of the expression slot is presented here.

To create a new expression slot, open a Data Object and select Slots  Add Expression Slot. The new slot is appended to the slot list with the name ExpressionX (where X is the smallest integer needed to make this name unique, beginning with 00000), and marked with the expression icon above. To open an expression slot, double-click on its name.

Expression Slots may be renamed through the Name: field in the Open Slot dialog. Expression Slots are initially created with the Run Control’s Initial: time only. When the expression is evaluated, the time range of the slot is expanded to mirror the time horizon in the Run Control dialog.

The units and Display Units label, scale, and precision of values displayed as the result of an Expression Slot may be changed through the Configuration menu. Expression Slots may display all RiverWare defined unit types, but default to a unit type of NONE. When the NONE unit type is selected, a Display Units field is available to enter a display label. This label is saved in the model file, but is not exported through DMIs in the same manner as RiverWare defined units. Any Expression Slots with Unit Type of NONE is written to DMIs with User Units of NONE. The label is only cosmetic, and in no way affects the calculation of the expression or scaling of the display value. When a unit type other than NONE is selected, an option menu appears for the user to select a RiverWare defined unit. These units ensure a consistency of labeling for exported data.

Expressions are only calculated based on the display values of the slots they reference. No attempt is made to reconcile varied units or carry them through an expression. The user is responsible for verifying that display values in referenced slots are consistent with the nature of the expression. Unit conversions may be performed after an Expression Slot has computed, by changing the Expression Slot’s units in the Configuration menu. Any such conversion will only be performed when changing from one RiverWare defined unit to another. The converted value is retained only as long as the Expression is not recalculated. When the expression is recalculated, the computed value will be assumed to be in the currently selected units.

The expression itself is displayed in the scrollable Expression: window. To create a new expression, select the Editor button or select View  Expression Editor. The Expression Editor is a syntax-directed editor designed to assist in the construction of complex syntactically correct expressions within the RiverWare environment. The editor works by maintaining a partially constructed expression and allowing the user to manipulate unfinished portions using a collection of selection lists and text entry boxes. To use this dialog effectively, it is important to formulate the expression in its entirety (perhaps on paper) before beginning. The Expression Editor does not allow editing of previously determined portions of the expression. Errors in specifying an expression must be corrected by clearing the existing expression and beginning anew.

Initially, the editor contains a single ? indicating a portion of an expression which has not yet been completed. Clicking, without releasing, on the ? brings up a term selection list. Scrolling down to a term and releasing the mouse, inserts the selected term in place of the ?. Terms may contain additional ?s, to expand the complexity of the expression. One of two selection lists is available from any ?. These fall into two categories: General Terms and Range Terms. General Terms include algebraic manipulations, variables (slots and user-defined variables), and actual values. Range Terms indicate the range over which an expression is computed. This may be a collection of slots, a SubBasin, or a set of timesteps.

Expression slots have been expanded to utilize the new SubBasin functionality previously described. It is now possible to iterate over user-defined SubBasins as well as object types. SubBasins will appear in the expression editor’s menu list when summing or averaging values. Note that any change in the membership of a SubBasin will be reflected in the calculations of any Expression Slots which reference it.

Expression slots may now be linked to other slots on the workspace. This is useful for propagating a set of calculated values into a dispatching Series Slot prior to simulation. Propagation across a link occurs every time an Expression slot is reevaluated, which may be done outside of a run by selecting Control  Reevaluate Expression Slots from the main workspace menu bar, or by using the <Control>-e keyboard shortcut. Reevaluation of Expression slots may not be forced during a simulation run, but will still be done automatically at the conclusion of the run. Linking an Expression slot to a Simulation slot which receives a computed value during a run will cause an error and abort the run when the value propagates to the expression slot.

A new Dispatch Information utility has been created to provide post-run diagnostics regarding object dispatching and known values of dispatching slots for every timestep of the simulation. The Dispatch Information dialog is invoked by selecting Dispatch Information... from the Utilities menu heading in the main RiverWare workspace window or by clicking on the Dispatch Information shortcut button on the toolbar.

The Dispatch Information tool provides dispatch information at two levels of detail. At the workspace level, the dispatch state of each object for each timestep of the model run is visible. At a more detailed level, the tool allows an object’s dispatch table entries and known slot values at the end of each timestep to be viewed.

The Dispatch Information dialog displays the workspace-level view of dispatch conditions. This dialog consists of a two-dimensional matrix with workspace objects on one axis and model run timesteps on the other axis. Each cell in the matrix shows the dispatch state of an object at the indicated timestep. Dispatch entries are made automatically during run initialization, so no dispatch information is available until a run is completed. Because they never dispatch, Data Objects and Snapshot Objects are not included in the list of Objects. An Object has one of four possible dispatch states:

Not Dispatched. The known and unknown slots for the timestep did not meet the requirements of any method on the dispatch table for the Object.

Dispatched. Conditions of a single method on the dispatch table were met; the method dispatched, and the Object solved.

Dispatched But Not Solved. Conditions of a single method on the dispatch table were met; the method dispatched, but the Object did not solve completely.

No Dispatch Entries. The Object has no entries on its dispatch table; the Object is a Thermal Object, or the model has not been run.

Selecting an Object/timestep cell displays its dispatch state in text form at the bottom of the Dispatch Information dialog. If the Object dispatched at that timestep, then the name of the method under which it dispatched is also displayed.

The Dispatch Information dialog may be reformatted from its original configuration. If the lists holding the names of Objects and timestep are too narrow to read, they may be expanded by clicking on the double-arrow buttons. This will alternately increase and decrease the size of the headers between an abbreviated length and one which accommodates the longest Object/timestep name. The view in the Dispatch Information dialog can also be transposed so that timesteps appear along the side of the dialog and Object names appear along the top. To transpose the view, select View  Time On Side or View  Time On Top from the menu bar.

Finally, the order in which Objects appear in the dialog may be rearranged from its original alphabetical order. This is useful to match the river topology or any order with which you are more familiar. To rearrange an Object, select its name with the middle mouse button and drag the resulting frame to a new location. Releasing the middle mouse button will place the Object just beyond the Object over which the frame is located; above when moving an Object up, below when moving an Object down.

Please note: new formats are only saved with the model file, so be sure to re-save the model after changing the Dispatch Information.

The Dispatch Information dialog may be used to disable or enable dispatching for individual Objects. Disabling dispatching prevents the object from dispatching at any timestep, regardless of what slots are known. This functionality is useful to debug models. To disable dispatching for an Object, select its name and select Object  Disable Dispatching from the Dispatch Information dialog menu bar. The Object name is shaded with red diagonal lines to indicate that it will no longer dispatch. The Object’s Beginning of Run behavior, however, may never be disabled. To re-enable dispatching, select the name of the Object for which dispatching has been disabled and select the Object  Enable Dispatching. The red diagonal lines disappear from the Object name, and it is allowed to dispatch when the model is run.

The Dispatch Detail dialogs allow the entries in the dispatch table and the known slots at the end of each timestep to be viewed for each object. To open a Dispatch Detail dialog, double-click on a cell in the Dispatch Information dialog which represents the desired object and timestep. One of the following occurs, depending on the dispatch state of the selection.

If the Object has no dispatch conditions, or the model has not yet been run, a warning message is displayed.

If the Object did not dispatch during the selected timestep, the Dispatch Detail dialog appears showing a list of slots. Each of the displayed slots is a required known and/or a required unknown for an entrie(s) in the Object’s dispatch table. The checkmarks indicate which slots were known at the end of the selected timestep.

If the object did dispatch during the selected timestep, the Dispatch Detail dialog appears showing a list of methods from that Object’s dispatch table. The method which dispatched at the selected timestep is marked with the dispatched symbol and is opened to show its dispatch conditions. Notice that all of the slots are checked as known, even those required to be unknown. This occurs because the object solved correctly for all slots, making them known by the end of the timestep. We know that the dispatch conditions requiring unknowns were met at the time of dispatching because the method could not have dispatched otherwise. This may seem slightly confusing, but remember that the known/unknown status of particular slots is truly of interest only if the object failed to dispatch at the selected timestep. If the object did indeed dispatch, all of the conditions must have been met.

In models with hourly, daily, or monthly timesteps, the Dispatch Detail dialog contains a date spinner which moves the detail view forward and backward over the range of the model run. Clicking on the up arrow of the date field spinner moves the dialog view one timestep forward in the run. Clicking on the down arrow moves the view one timestep backwards in time. This is useful to determine how the set of known slots changes from timestep to timestep.

The Diagnostics Output Window now contains windows for Contexts and Messages that are independently scrollable. The scroll bars along the bottom of each window may be used to view information which extends beyond their right borders. The scroll bar along the right side of the dialog scrolls both windows simultaneously. The width of each window may be modified by clicking in the space between the two headings and dragging the outline of the heading bars to the new desired location. Message lines are now separated by a horizontal rule to increase their legibility.

The Diagnostics Output Window has been reformatted to be more efficient. Display allocation in the window is now done in increments of 50 lines. This significantly decreases model run time when many diagnostics are enabled. This does not, however, completely alleviate the potential for “freezing” RiverWare when too many diagnostics are enabled. Users should still exercise prudence in selecting only the appropriate categories and filters for diagnostics.

The name of the toggle for enabling diagnostics information has been changed from Include General Information to Enable Informational Diagnostics. As before, this toggle has no effect on Errors and Warnings produced during a run. Errors and Warnings are not user-configurable. They are always displayed in the Diagnostics Output Window, regardless of whether Informational Diagnostics are enabled.

New functionality exists for saving and combining plots of output values from several different slots and runs. The Snapshot Management dialog is used to create and review snapshots of selected slot values over multiple runs.The Plotter Management dialog is used to create composite plots for display or printing.

The Snapshot Management dialog is invoked by selecting Utilities  Snapshot Management.... It allows snapshots of selected slot values to be taken after different runs. This tool is useful for saving the values to compare the effects of various operating strategies or reproduce a particular run.

Slots to be included in a snapshot are selected by clicking on the Add Data... button, which invokes a Slot Selector dialog. Newly selected slots are added to any existing slots in the Data Available: window. These selections may be cut, copied, pasted, and cleared through the Data menu. Slot selections may also be copied between the Snapshot Management and the Plotter Management dialogs. This greatly facilitates configuration of plots and preparation of snapshots for preconfigured plots.

Snapshots of the selected slots’ current values are taken by clicking on the Take Snapshot button. Each time a snapshot is taken, the Snapshot Manager creates a new Snapshot Data Object to contain its data. The new object is added to the bottom right of the workspace, and its name appears in the Snapshots Taken: window. Snapshot Objects are initialized with the name Snapshotn, where n is the smallest number, beginning with 0000, which makes the object name unique. The selected slots are copied into the Snapshot Object, retaining their unit and display configurations. These slots are initialized with the name of the object and the name of the slot from which they were copied, separated by an underscore. For example, a snapshot of the Inflow slot on the Big River Reach appears as “Big River_Inflow.” While snapshot slot names may not be changed, Snapshot Object names may be changed by entering a new name in their Name: field.

Selecting a selected slot name in the Data Available: window highlights any snapshot objects in the Snapshots Taken: window, which contain a snapshot of that slot. Double-clicking on a Snapshot Object name in the Snapshots Taken: window automatically brings up that Snapshot Object. Double-clicking on a selected slot name in the Data Available: window brings up that object and the slot’s current model values.

The Plotter Management dialog is invoked by selecting Utilities  Plotting Management....

The Plotter Manager maintains a list of all existing Plot Pages, which may be created, opened, deleted and refreshed from this dialog. To create a new Plot Page, select Plot Page  New..., or select the New... button. To open an existing Plot Page, highlight it and select Plot Page  Open... or select the Open... button.

The Plotter dialog is used to select the number and orientation of graphs to be displayed on one page, as well as what slot data will appear in each individual graph. Plot Pages are initialized with the name Plottern, where n is the smallest number, beginning with 00000, which makes the Plot Page name unique.The plotter name is changed by typing into the Plot Page: field. The number and layout of graphs is selected through the Graph Layout: selector bar. Up to nine graphs may be generated on a single page, with graph layout referenced according to row-column notation. For example, a 2 x 1 layout consists of two rows with one graph per row. The layout is represented graphically in the Select Graph: region.

Individual graphs are selected by clicking on their icon in the Select Graph: region. Graphs which contain at least one set of data, display a data line in their icon, and the names of the included slots appear in the Slots to Graph: window. Empty graphs display only axis lines in their icon and <no data exists> in the Slots to Graph: window. To add data to a selected graph, select Data  Select Slots... or select the Select Slots... button. This invokes a standard RiverWare Slot Selector with which to chose the slots to display. Newly selected slots are added to any existing slots in the Slots to Graph: window.

A graph may show current values of selected slots only, or current and previous values of selected slots for which a snapshot(s) exists. This is determined by the For Selected Graph, Show: toggle. Selected slots of which a snapshot image exists are indicated by a blue snapshot icon to the left of their name. Selected slots which are selected in the Snapshot Management’s Data Available: list but are not part of a snapshot, are indicated by a grey snapshot icon to the left of their name. Clicking on a selected slot name in the Slots to Graph: window highlights any snapshots in the Snapshots of Slots to Graph: window which contain an image of that slot.

The XMgr session which displays the Plot Page may be invoked by clicking on the Show Plotter Page button. Once the XMgr window appears, it must be populated with the selected data by clicking on the Refresh All Graphs button. If new snapshots are taken, or the data in the Plot Page is changed, the existing Plot Page may be updated by re-clicking on the Refresh All Graphs button.

Display Units for any slot may now be changed without converting the slot’s values. This feature allows data which were mistakenly imported with the wrong display units or scale, to be reassigned without having to re-import them. The Configuration menu for each slot now contains a toggle to “Convert slot values to new User Units and Scale.” The toggle is ON by default. When the toggle is ON and User Units and/or scale are changed, the displayed values are converted and scaled so that the underlying internal values remain the same. This was the traditional behavior for previous PRSYM versions. When the toggle is OFF, the displayed values are not converted or scaled. This new behavior actually changes the internally stored values so that the displayed values appear the same.

The automatic conversion and scaling should only be turned OFF to rectify improperly imported data. Normal changing of display units with the toggle OFF will corrupt the slot’s data. This toggle is column specific and resets to ON any time a different column is selected or the Configuration dialog is re-opened.

The Unit Converter has been modified to display only twelve significant digits in calculated values. All slot values in RiverWare memory and model files are stored with twelve significant digits of precision. The previously unscaled Unit Converter results could have implied a greater precision in calculated values than was actually possible. Results have also been reformatted to display in either floating point notation or scientific notation, whichever is shorter.

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.