By: Leila Ostadrahimi, Ph.D., P.E.

Introduction

The Reservoir System Simulation (HEC-ResSim) software, developed by the U.S. Army Corps of Engineers' (USACE) Hydrologic Engineering Center (CEIWR-HEC), is a powerful tool used to model and simulate the operations of reservoir systems. It assists water resource managers by evaluating how reservoirs should be operated to meet various objectives like flood control, water supply, and hydropower generation, especially under differing hydrologic conditions. The software is widely used for planning studies, creating detailed regulation plans, and providing real-time decision support for major river systems in the United States and international river basins. Its capabilities include rule-based operational modeling, advanced simulations, and recently, water quality and temperature modeling, making it a comprehensive tool for water management.

Background

The history of HEC-ResSim began in January 1996 as the "Next Generation" model to replace its predecessor, HEC-5. The first official version, HEC-ResSim 1.0, was released in September 2001. The software underwent steady development, with version 2.0 released in September 2003 and version 3.0 in May 2007, marking significant advancements. The 3.x series continued to evolve between 2007 and 2024, culminating in the release of version 3.5.1 in December 2024. Work started on HEC-ResSim 4.0 in 2017 and continued in parallel with the 3.x series for many years. However, starting in January 2025, development focused solely on HEC-ResSim 4.0 and the inaugural version was released in September 2025. 

HEC-ResSim Timeline- 25 years since release of HEC-ResSim 1.0

HEC-ResSim 4.0 - A Modern ResSim

The HEC-ResSim 4.0 release marks a significant advancement in our development process, as it is the first HEC-ResSim version developed on HEC's modern DevOps infrastructure. This particular codebase has been evolving since 2017, parallel to development on the version 3.x series. As a result of these software development enhancements, HEC is transitioning to a faster and more frequent release schedule. These software updates are complemented by our web-based user guides, which will now also be updated on a continuous basis, ensuring documentation is always current.

Version 4.0 represents a major step forward, introducing new foundational capabilities and implementing substantial under-the-hood changes to our development process that improve reliability and set the stage for faster improvements. This major-version reset from 3.5 provides a clean line, allowing us to shift to a more frequent and iterative release schedule. We will now deliver incremental improvements regularly, releasing new features in stages to be refined over time with real-world user feedback, which can be provided via our continuously updated web documentation. Our immediate priority is to focus on stability and maintainability by addressing technical debt, which may mean fewer major new features in the short term.

New Features

HEC-ResSim 4.0 introduces a major new capability, a Water Quality (WQ) analysis tool which can be turned on when building a new watershed or when adding WQ modeling to an existing watershed. This feature is explored comprehensively in the other article available at DRAFT HEC-ResSim 4.0, WQ Feature-LO 2026-03-19.  In addition, several new features, as well as enhancements to existing features, have been added to the program. The new and updated features are listed below, along with short descriptions.  

  • Updated File Organization: The file structure has been reorganized. HEC-ResSim networks and their related files are now located in a dedicated "networks" folder. Additionally, state variable and scripted rule scripts have been moved to a separate "/scripts/" folder within each network's directory for easier access and management outside of the main program.
  • Enhanced Model Documentation: A new "Watershed Info" feature has been added to assist with model documentation. This feature creates a WatershedInfo.md file in the main watershed directory, allowing modelers to log comments, changes, and other important information in a consistent location. Modelers are strongly encouraged to use this feature to document their models and changes, in addition to putting info in the description fields throughout the interface.  
  • Default to DSS Version 7: HEC-ResSim 4.0 now defaults to using DSS version 7 (DSS7) files for both reading and writing data. While it can still read from DSS version 6 (DSS6), DSS6 is being phased out and is no longer supported.
  • Expanded Water Supply Capabilities: The water supply features have been significantly enhanced. This includes improvements to the yield analysis calculations and the addition of two new tools: a "Reverse Yield Analysis" to determine the storage needed for a given demand, and a "Reservoir Storage vs. Yield Analysis" to help create a trade-off curve between storage and firm yield.
  • New "Smart Diversions" Feature: A new "Smart Diversions" feature has been introduced in its initial phase. This allows modelers to create different operation sets for various alternatives, complete with rule stacks and conditional logic, similar to how reservoir operations are configured.
  • Flexible Routing Settings: Routing calculations for reaches and diversions can now have different settings based on the compute time step being used. This eliminates the need to create separate networks for simulations with different timesteps.
  • Improved Variants for CWMS and HEC-WAT: The functionality of "Variants" has been improved for users integrating HEC-ResSim with CWMS or HEC-WAT. This allows for different time series mappings and global variable values to be saved for the standalone program versus when it is used within the larger platforms.

Polished Features

Several features that were new or updated in version 3.5 have been refined in version 4.0.

  • Refined Release Allocation Sets: The Release Allocation Sets and If Blocks feature, which was introduced in version 3.5, has been polished in version 4.0 with several bug fixes.
  • Improved Operation Support Interface (OSI): Following the look and feel improvements in version 3.5, the OSI has undergone further polishing and bug fixes.
  • Polished Lookback Options: The Expanded Lookback Options feature, which applies to elevation and release, has been polished and improved.

Removed Feature

The Vertical Datum feature has been removed from HEC-ResSim 4.0. Although initially designed to allow users to view data in their preferred vertical datum and used successfully by some beta testers, the feature became unreliable due to changes in HEC's shared code. By the release of version 3.5.1, it was evident that the feature was causing significant issues, particularly for users upgrading to DSS 7. After considerable effort to find a solution failed, the feature was completely turned off, with the development team noting that user-created scripts provide a reliable alternative.

HEC-ResSim 4.1 

After the release of version 4.0, the HEC-ResSim team began addressing other issues, with the goal of releasing version 4.1 by the end of February 2026. Version 4.1 includes several bug fixes and improvements, highlighted by the following three main tasks completed to enhance the Operational Support Interface (OSI).

Add Observed Data to the OSI Variable Editor 

While HEC-ResSim plots can include observed data for an alternative, there was no way to do this for an OSI Variable in the graphic editor. This capability has been added in the OSI Variable Editor.

Add Observed Data to the OSI Variable Editor


New On-The-Fly Fill Editor for Editable OSI Variables

Editing reservoir releases in the HEC-ResSim OSI is inefficient and slow, as it requires manually editing of potentially hundreds of individual time-step cells for a single forecast. This is particularly challenging for CWMS users who need to make rapid forecast simulations and decisions. To streamline this process, a new on-the-fly data filling capability has been added to make data entry in the OSI more efficient.

New On-The-Fly Fill Editor for Editable OSI Variables

New Options for the OSI Table Fill Options Dialog

Currently, right-clicking on selected cells in the main OSI data editing table opens a "Fill..." dialog with five functions. Four new fill functions have been added to this dialog, improve the existing interface, and include tooltips to explain what each function does.

New Options for the OSI Table Fill Options Dialog


User Support 

For those looking to use HEC-ResSim 4.0, helpful documentation and training materials are available. The primary resource is the HEC-ResSim Documentation page, which provides comprehensive user manuals (HEC-ResSim User's manual), including a specific manual for the new water quality features in version 4.0 (HEC-ResSim WQ User's Manual).  Release notes are available (HEC-ResSim 4.0 Release Notes), as are tutorials to guide users through various aspects of the software (HEC-ResSim Tutorials and How-to Guides). For a more hands-on approach, HEC provides training materials from PROSPECT course #098 for Reservoir System Analysis with HEC-ResSim (#098 ResSim PROSPECT (Feb FY26)), which can be valuable for understanding the software's core functionalities.  Additionally, a "Known Issues" page (ResSim 4.0 Known Issues) informs users of any potential software bugs. These resources, combined with the software downloads (HEC-ResSim 4.0), provide a solid foundation for both new and experienced users to effectively utilize HEC-ResSim 4.0.

For issue reporting, troubleshooting questions, and opportunities to share lessons learned USACE modelers can report issues to the ResSim Discourse Bug (Discourse). Also, USACE and non-USACE modelers can report issues to the ResSim help mailbox (ResSim Help Mailbox).