ResSim 4.0 Known Issues

Overview

HEC-ResSim 4.0 beta versions have been been applied to a few select projects since 2022, and has been known to be stable. That beta modeling, however, has not covered the full range and depth of ResSim features, so the ResSim team has been dedicated to testing and cleaning up features and issues for the past few years. ResSim 4.0 is being released with some known issues and some features in early development that have not yet been widely used. As with the 2024 release of version 3.5, we have aimed to address all major and show-stopping issues, but there remain are many smaller, known issues that were not addressed prior to release due to funding and timing.  We have documented the most significant of those issues on this page. We have also commented on some cases where an issue in version 3.5 has been addressed in version 4.0.

If you encounter any undocumented issues within version 4.0, please report them!

Important Computational Issues

These issues have the potential to cause a significant impact on results, but can be handled with informed modeling, such as proper input, work-arounds, or in some cases refraining from using certain features.

Potential Miscalculation of Physical Maximum Release Capacity

The determination of the maximum release capacity of a reservoir and its outlets is an important piece of the release decision logic in ResSim, but it is also a computation that is harder to produce accurately than you might expect.  You see, at any instant of time, the release capacity is a function of the pool elevation, so what is the release capacity for a timestep?  Is it the capacity at the start of the timestep, or at the end of the timestep , or is it an average over the timestep?  The first option, at the start, is easy because we “know” the elevation at the end of the previous timestep - which is the elevation at beginning of the current 0timestep. But, don’t know the elevation at the end of the timestep because we still need to make decisions that will result in the elevation at the end of the timestep. Depending on the release we decide to make, the pool elevation during the timestep could vary substantially. But to make that decision, we need to know the maximum release capacity (PhysMaxCap) – you can see it is a vicious circle. 

The algorithm that ResSim currently uses to determine PhysMaxCap for each outlet (and for the reservoir) assumes that each outlet is releasing at its starting capacity for the timestep. ResSim uses the mass balance equation to calculate the resulting change in storage from which it then looks up the ending elevation for the timestep.  Because each outlet has been assumed to be releasing at its starting capacity, a lot of water will be assumed to have left the reservoir, resulting in a potentially very low ending elevation. ResSim then averages the beginning and ending elevations and looks up the release capacity for that average elevation and calls that average PhysMaxCap. 

Thus, this problem manifests as an unexpectedly low PhysMaxCap due to a low estimate of average elevation. Unfortunately, the longer the timestep, the worse this estimate of PhysMaxCap may be, especially in reservoirs with small pools and large release capacity.  We are aware of this limitation in the algorithm but, as of this release, we have not settled on a better approach. [NOTE: this estimate of ending elevation is only used for the PhysMaxCap calculations and is not stored nor used elsewhere in the program.  In fact, ResSim uses a very different calculation to estimate ending elevation for the purposes of the rules and other operational decisions.]

This bug was originally reported for ResSim 3.5, and has been investigated but not addressed for 4.0

How to Address: Workarounds for this problem are usually model specific because what works for one might not work for another – or causes other problems.  But here are some workarounds we employed with some success:

• Use a smaller timestep.
• Consider the function of the reservoir and the impact or importance of storage. Is the reservoir a storage project, or is it a “run of river” project? 
  • Run-of-River project: we have seen this problem most in run-of-river reservoirs where the storage is small but the release capacity is large so that the reservoir can pass large events without concern. In such a reservoir, the storage of the pool is essentially irrelevant because the operations keep the pool level.  So, give it a fictional huge pool, or give it a constant release capacity, or both.
  • Storage project: this kind of reservoir is harder to find an effective workaround for but the options are still related to the definition of the storage pool and the definition of the outlet capacity. 
    • Try adding volume to the pool without changing its relative change in storage across the operating range. In other words, add 1,000,000 acft to each entry in the elevation-storage table, then add a new zero row at the top, and set the elevation of that zero storage fictionally low (10’-100’ below the actual bottom of the pool).  In this test, you are looking to see if the larger overall storage allows the estimate of PhysMaxCap to be more appropriate to the operations.  To check before and after, the PhysMaxCap is stored to the simulation.dss file as //reservoir-name-outlet-name/FLOW-MAXLIM/…/
    • Try setting the capacity of your outlet(s) to a constant. Although you can check on /FLOW-MAXLIM/, what’s more important is that your operations reflect the desired operation and do not release more than they should.  If you must model your outlets with a constant capacity curve, you can impose the physical capacity constraint on them with a maximum release rule, function of previous or period average elevation, and put the original capacity curve in there as the function.

Mod Puls Routing Mass Balance Error

This bug was originally reported for ResSim 3.5, and has been investigated but not addressed for 4.0

Scenario: Occurs when Mod Puls storage-outflow relationship does not start with a zero flow entry

How to Address: provide complete and valid input data.

A user discovered a problem in the mass balance (conservation of mass) while performing a network connectivity and mass balance check. They setup an alternative using a constant 1cfs inflow time series at each inflow location in their model.  Most routing reaches in the model were using Modified Puls routing. When they reviewed the flows throughout the network, they found the downstream-most outflow was ~504 cfs when it should have been ~4cfs - the system was creating water somewhere!  The user isolated the problem to a Mod Puls routing reach below the lowest reservoir; it had a storage-outflow relationship whose smallest outflow value was 500 cfs.  By setting the routing to NULL in this reach, the 500 cfs difference in expected outflow disappeared.  Further testing at HEC revealed that by entering an additional row into the top of the storage-outflow table with a zero outflow value, the reach produced a much more appropriate routed flow and the outflow at the mouth of the network was the ~4cfs that was expected.

The moral of the story:  When doing table lookups, ResSim will NOT extrapolate beyond the edges of the data provided in the table. If you haven't heard us tell you this before, well, you have now.  Thus, ResSim's Mod Puls routing method will not produce a routed flow smaller than the smallest flow in the reach's storage-outflow table (or larger than the largest outflow in the table). So, start all your Mod Puls storage-outflow tables with a zero flow entry or a flow entry that is lower than any value you would ever expect to see flowing through your routing reaches. And end these same tables with an outflow entry larger than you would ever expect, even in a 1000 year or dam-break event. 

HEC plans to add messaging and a data check to catch this potential issue at the start of each compute, but that has not been implemented as of this release.  However, the onus will remain on you, the user, to provide ResSim with complete and valid data.

Decreasing Flow Rate of Change Rule may Impact Guide Curve Operations.

A user discovered a problem when analyzing the impacts of a decreasing flow rate of change rule on the operations of one of the reservoirs in his watershed.  In this case, he believed that the rate of change rule was preventing the reservoir from "staying on the guide curve" even though the value of the decreasing rate of change limit was such that it should not have limited the operation.  He performed several subsequent tests to verify his conclusion including removing all rules from the reservoir except the decreasing flow rate of change rule.  His tests isolated the problem - in his watershed - to:

• the reservoir needed to be part of the network with the other reservoir
• the reservoir had to have the decreasing rate of change rule in it
• the reservoir was not part of a system of reservoirs operating for a common objective (downstream control).
• the model had the option to include rate of change constraints in evaluating the guide curve release (this is the default).

If any of the above conditions was false, the reservoir was able to properly operate to meet guide curve operation, i.e., the problem behavior was not observed.

There was one interesting and unusual feature in the reservoir in question - it's guide curve was not a simple function of elevation, instead, it was a function of a state variable and thus a "computed" guide curve.  We have not determined if this could in any way have been related to the problem behavior.

Tests were performed in two other complex watersheds with multiple reservoirs and system operations.  We were unable to replicate the reported behavior in either watershed so we are unsure if the problem is specific to the watershed it was found in and we did investigate further before ResSim 3.5 was released.

How to Address: If you are suspicious that this problem is impacting the operation of your model, here are some workarounds that you can employ:

• turn off the option to evaluate the impacts of Rate of Change rules on Guide Curve logic: 

• or include the reservoir with one or more other reservoirs in a common compute block.  This can be through the use of a common downstream control rule or a "dummy rule" that's a function of the flow at a common downstream location.

FIXED - IF-Block Conditional Expressions that utilize Date/Time entries do not evaluate correctly.

Discovered in version 3.5, conditional expressions that utilized a Date/Time entry to compare against the current runtimestep did not result in a correct evaluation of TRUE or FALSE during all or most of the time window. This error was fixed in both versions 3.5.1 and 4.0.

Prescribed Release Rule Issues

These issues were first reported in version 3.5 and remain in 4.0, except where specified.

The Prescribed Release Rule is a fairly new rule in ResSim.  It was designed to be a “hand regulation” rule that acted a bit like a release or elevation override but that was included in the standard rule stack and prioritized against other rules.  This rule’s setup is a list of prescriptions – each of which is defined by a time window over which it applies and an operator with an associated value (if needed).  The list of available operators depends on the release element you apply the rule to.  The following figures show the list of available operators for an outlet defined with a range of gate settings, for the reservoir pool, and for an outlet defined with only a maximum capacity curve.

Some Operators Should not be Options

The list of operators for an outlet group should be the same as those for an outlet with only a maximum capacity curve, but that’s one of the “bugs” we didn’t get addressed before release – the list is not as filtered as we’d like.  In other words, it includes Hold Previous Gate, Hold Starting Gate and Set Gate, when it really shouldn’t since an outlet group doesn’t really have gate setting information, even if all the outlets in the group do. 

Date and Time Specification Confusion

Another Prescribed Release Rule issue that did not get addressed is how ResSim uses the Date and Time entries with some of the operators – specifically the Hold Previous operators.  The issue was identified with Daily timestep alternatives.  The problem was described as: the prescription starts 1 day prior to the selected start date/time and uses the release or gate setting from 2 days prior. Investigations revealed that this may not be a “bug” as much as a misinterpretation of the date/time specified for the start time – but whether that misinterpretation is on the part of the program or the modeler, we hesitate to say.  But since it was confusing for those of us who designed the rule, we do feel that we need to do something to clear things up.  So, until this is addressed, be careful of how you define your prescriptions and verify that ResSim in doing what you intended (or adjust the prescription accordingly).  The original bug report also noted that the prescription was also ending one day before the end of the prescription, but we could not verify this; the prescription was ending right where we expected. 

FIXED - Date and Time Requirement without Warning

Discovered in v3.5: The Prescribed Rule Delta Elev and Target Elev operators require a start and end date/times to be specified, but they could be left unspecified, in which case ResSim would ignore the rules and give no warning.  This has been addressed in 4.0, and the user must specific the date/time values or they will get an error. 

FIXED - Release Allocation Issues

The UI for specifying the Release Allocation Options changed significantly with ResSim 3.5. And as sometimes happens with when we try to make things better, we add in problems.  But let’s start with the good stuff: The release allocation feature now allows you to define one or more release allocation strategies or sets and give each a name, but only one allocation set can be active per operation set. However, you can now create a Release Allocation IF-Block and define various IF and ElseIF conditional expressions; each IF, ElseIF, and Else clause in your IF-Block can then be assigned a different release allocation set.

The issues that were identified during 3.5 testing and which were scheduled and fixed in 4.0 include:

• Duplicate Allocation Set names - now being prevented. 
• The current implementation of the Allocation IF-Blocks only allows the creation of one Allocation IF-Block. - addressed
• If you have created a release allocation with an IF-Block, you cannot switch back to a single allocation set unless you delete the IF-Block. - addressed
• User Interface gaffs such as typos and incorrect tooltips - addressed.

Global Variables Issues & Limitations

Only a minimal initial implementation of Global Variables was done in ResSim 3.5 and 4.0.  Many of the planned features are incomplete or expected to be added later. The existing features are not all fully polished. Some of the most significant issues with Global Variables are as follows:

Global Variables Tables Issues

Improper Date/Time Entry is Possible

The Global Variable Tables will allow dates to be entered in non-chronological order. It is not known how improperly entered Date/Time data will affect model runs. Use caution with this datatype and enter it into tables carefully.

Exceptions can be thrown with incomplete data entry

Limited Application of Global Variables

Only Timeseries Global Variables can be used in IF Statements

Only Timeseries Global Variables can be used to define zones

Operation Support Interface (OSI) Issues and Limitations

Many small bugs and limitations were identified with the initial implementation of the OSI in HEC-ResSim. We also have a scope for numerous enhancements for real time modeling with ResSim, including many in the OSI. These plans are projected after release of 4.0. ResSim 3.5 has only a few bug fixes since version 3.3.

Use Caution with Timesteps

Use caution when editing local flow timeseries with a timestep that is different than the compute timestep.  ResSim will interpolate an input local flow timeseries to the timestep of the compute (e.g. 15MIN to 1DAY), but users may experience unexpected behavior when editing that interpolated timeseries.  For best performance, ensure all timeseries that will be edited in the OSI use the same timestep as the ResSim compute timestep.

In Progress - Preprocess Observed Data for use in OSI

Time series identified in ResSim's Alternative Editor Time Series tab is processed during the standard data extraction to ensure it uses the correct time interval and data type to match the alternative settings. However the OSI does not process observed timeseries. Modelers who wish to use observed data within the OSI must first make sure the observed data time series referenced uses the correct time interval and data type (period-average or instantaneous).  

Ensemble Bugs

Ensemble Plotting Issues

There remain some issues with plotting ensembles, but in ResSim 4.0 fixes were made such that ensemble multiple traces are plotting and observed data is no longer being plotted as part of the ensemble. Other plotting issues can be added to the wishlist.

Selecting the Ensembles using * is not supported in CAVI

Whether using multi-threading or not, specifying "*" ensembles causes a compute failure in CAVI because it is not a supported function. It works in ResSim standalone only.

FIXED - Selecting the Ensembles using a range does not work fully

ResSim 4.0 now gives a warning if the data for any of the selected ensemble members is not available. It then moves on to the next ensemble member.

FIXED - Overrides do not consistently work for Ensembles

In ResSim 3.5, the Overrides editor sometimes lost the connection between the active reservoir and the selected outlet causing changes made to one get saved to another. This was addressed for version 4.0.

Monte Carlo Bugs

Numerous issues were found with the Monte Carlo feature in late stage v3.5 testing. This feature is not widely used, and thus has not undergone the same level of functional testing as most of ResSim. Some Monte Carlo applications may work, while others have user interface bugs or computational bugs, and they are not always reproducible. Key issues that were present in v3.5 have now been addressed for v4.0, but we still recommend caution with this feature.  

How to Address: Please reach out to the HEC ResSim team if you run into any issues or would like to discuss your Monte Carlo modeling options.

Input Variable Filter Buggy

The filter for selecting an input variable has some buggy behavior, where the selected timeseries may not match the one chosen. Manage this by reviewing the selection for surprises.

FIXED-Monte Carlo Script Option

FIXED IN V4.0Script option was previously not working and hidden from v3.5.1. It is working for v4.0.

FIXED-Monte Carlo Input Timeseries

Input timeseries now work and can have natural variability or knowledge uncertainty. 

FIXED-Input Variable Empirical Distribution UI Issues

CAN'T REPRODUCE V4.0The MC Input variable empirical distribution table does not work correctly. Sometimes the table inverts. In any type of sorting user will get the “Empirical Distribution Data is not valid. Distribution values must be strictly monotonically decreasing” error message. Sometimes the probability values is changed in the first or last row.

FIXED-Random Variable Wizard Distribution UI Issues

FIXED IN V4.0The Random Variable Wizard displays various UI issues, including nonresponsive buttons and disappearing tables.

FIXED-Input Variable "Edit" Button Launches Wrong Wizard

FIXED IN V4.0This issue is not present in 4.0. The Monte Carlo Input variable Edit Button does not allow editing.  Instead, it launches the Random Variable Wizard and adds a new Variable

FIXED-Exceedance Probability Precision Issues

FIXED IN V4.0 This issue was present in v3.5 but fixed in 4.0. 

Some exceedance probabilities appear to be displaying all digits out to limit of double floating point precision. This might only occur in the seasonal table.

FIXED-Changes to Settings cause Compute Failure

FIXED IN V4.0If the user changes Monte Carlo settings, such as the output variable, between computes in a simulation, the compute will fail with an error about being unable to get DSS data:

"Monte Carlo Compute Data Errors: Simulation does not have active Monte Carlo convergence variables." In order to clear this, the user must change the option on the `MC Controls` tab to `clear previous MC...` before they can run the simulation again. 

CAUTION-Save To/From Base Potentially Misses some Settings

CAN'T REPRODUCE V4.0The Alternative "Save to Base" or "Replace from Base" options in the Simulation Module may not reliably copy all the Monte Carlo settings. We were not able to reproduce these issues in ResSim 4.0, but still encourage caution. Please report any instance of failure to the HEC-ResSim team.

FIXED-"Inflow Multiplier" check box is required to see all variation of MC results

FIXED IN V4.0In 4.0 ResSim will not allow the user to compute the Monte Carlo run if the necessary Inflow Multiplier setting is not selected. It will warn the user that the Inflow Multipliers need to be turned on when necessary.

Lower Risk Issues

API Issues

Beware that some methods shown in the Scripting API do not work.

getLookbackTimeSeries() 

The getLookbackTimeSeries() function is located in the State Variable Editor's Application Programming Interface (API) Tree, under StateVariable in the API branch. This function currently throws an error that the object has no attribute. Recommend modeler use getTimeSeries() in the interim, if needed.

ResSim will override the starting pool elevation if user provided elevation is below zero storage.

ResSim intentionally overrides a starting pool elevation below zero storage, but users should be warned. Background: Pure flood-control reservoirs (dry dams) often exclude the through‑channel from the pool definition. As a result, the zero‑storage elevation starts at or above the bank, while the lowest outlet invert typically matches the stream invert. During low flows, measured pool elevations taken in the channel can fall below the model’s zero‑storage level. Because the original computations assume water must exist to release water, this led to nonphysical results. The override was added to prevent starting mass balance from “negative storage.” Ideally, modelers should include channel storage in the pool definition; the override is a safeguard until then.

FIXED - Water Account Sets may appear more than once in the account set selector of the Alternative Editor.