Best practices for setting up, configuring, and running models in the HEC-RTS environment.

Login

For Corps users, when connecting to the CWMS Database and Cumulus, ensure selecting the proper certificate, especially right after CAC renewal. 

Also, here are instructions for cleaning up expired certificates to reduce the number of selectable certificates in the login prompt:

  1. Click on the Start menu, type in Internet Options, click on Internet Options in the results.
  2. Click on the Content tab, then Certificates button.
  3. Sort by Issued By by clicking on the column header.
  4. Remove certificates that meet ALL of the following criteria:
    1. Issued By begins with DOD
    2. Are expired or near expiration
    3. The Friendly Name DOES NOT begin with CN=

CAVI

Handling an Unresponsive CAVI

If the CAVI becomes unresponsive, use HEC-RTSTaskList.exe (found in the CAVI folder) to terminate all related processes before restarting the application.

Viewing Multiple Forecast Runs within Map Windows

When working with multiple forecast runs in a forecast, only results from a single run can be shown in the map window at a time. To view results from a different forecast run:

  1. Right-click on the desired forecast run.
  2. Select Display in Map.
  3. Choose between:

    1. Replace the existing map window's display.

    2. Open a new map window to show the selected forecast run's models and results.

Adjusting Logging Levels

CWMS uses the Java Util Logger framework for logging. By default, the log level is set to INFO, but you can customize logging levels to suit your needs. For detailed instructions, refer to Logging Levels or HEC-RTS Debug Logging and -D Flag Options. 

Managing Memory and Display Settings

For guidance on creating a personal configuration file, refer to the Creating Personal CAVI Config File tutorial. 

To optimize performance:

  • Increase the maximum memory allocation in your configuration.
  • Disable certain graphical settings by editing the cavi.config file in a text editor such as Notepad.

Under the Graphical Issues section, comment out the following lines:

  • #vmparam -Dsun.java2d.d3d=false
  • #vmparam -Dsun.java2d.nodraw=true
  • #vmparam -Dprism.order=sw

Disabling these options may improve performance or resolve rendering issues.

Importing Models

All models should be developed using their native software applications before being imported into HEC-RTS. Avoid building models directly within HEC-RTS, as it is not intended for model development. Instead, use HEC-RTS solely as a platform for integrating and running pre-developed models.

HEC-MetVue

Importing HEC-MetVue Projects

Create the HEC-MetVue project outside the watershed before importing it into HEC-RTS. The project folder should include a maps directory containing polygon shapefiles for basin average calculations. Each polygon shapefile must have a Name field in its attribute table with clear, descriptive location names.

Setting Up HEC-MetVue Projects in HEC-RTS

To create an HEC-MetVue alternative, you must have an HEC-MetVue Session and corresponding Map Windows within the HEC-MetVue project. Linking input data directly in the input Map Window(s) of the base HEC-MetVue project is optional because input data definitions are primarily handled in the MetVue Alternative Editor. However, adding sample data in the base project is highly recommended. This helps customize gridset spatial extents (clipping), contour display settings (scales, color palettes), and temporal transformations.

Application Settings in HEC-RTS

Set spatial read extents when not rotating/transforming data to improve performance.

Trim spatial extents to avoid unnecessary data outside basin boundaries.

For watersheds not in GMT, use the time zone write constraint in the basin average time series dialog to ensure data compatibility downstream.

Updating HEC-MetVue Projects and Model Alternatives

When modifying the watershed’s HEC-MetVue project or model alternative:

  1. Make changes in the base copy via the Setup module.
  2. Update the Model Linking if needed.
  3. Use Replace-from-Base to propagate updates to forecast copies.

Data Types and Durations

When configuring the HEC-MetVue alternative, specify correct durations and parameter types for input and output datasets:

  • SWE and Temperature: Usually instantaneous. Set input duration to 0 and output parameter type to INST-VAL.
  • Precipitation: Typically period cumulative. Set input duration to the number of hours (e.g., x-hours) and output parameter type to PER-CUM.

HEC-MetVue Temporal Transformation Tool

By default, the HEC-MetVue model applies uniform weighting to gridded data. Using the Temporal Transformation Tool to apply peaked weighting patterns can improve precipitation volume distribution within specific input intervals.

Input Data Time Window Controls for Hamon ET Support

When linking HEC-MetVue to an HEC-HMS model using the Hamon Evapotranspiration method, provide extra temperature data one day before and after the simulation window by:

  • Setting the observed Temperature Extract list to start at -1 Day offset from the Lookback Time.
  • Applying a Start of Simulation (SoS) -1 Day offset to the Lookback Temperature Map Window.
  • Setting the forecast Temperature Extract list to extend +1 Day past the Forecast Simulation end.
  • Applying an End of Forecast (EoF) +1 Day offset to the Forecast Temperature Map Window.

Input Data Time Window Controls for SWE and QPF

Input datasets may have timestamps that don’t align exactly with the forecast simulation times (e.g., SWE at 0600 daily; QPF at 0000/0600/1200/1800). To ensure sufficient data coverage, buffer the time windows in the Extract Lists by adding reasonable offsets before and after the forecast start and end times.

HEC-HMS

Proper File Storage

Store all necessary HEC-DSS records inside the HEC-HMS project folder. This ensures HEC-HMS can locate required data when opening the project or starting a simulation. It also prevents prompts for missing DSS files if the project is moved or opened on a different computer. Use the Global File Reference Table and Visual Cues for File Reference tools to verify all files are correctly linked.

Keep all shapefiles and ModClark grid cell files needed by the model inside the HEC-HMS project folder.

Ensure all referenced files in the watershed folder contain valid data. Upon opening, HEC-HMS checks all time-series, paired, and grid data for correct types and units. Missing or invalid data will require manual cleanup before running forecasts. To avoid extra work, maintain sufficient valid data in the base watershed project.

Minimize data volume in the HEC-HMS project folder. Remove unnecessary components, DSS records, and old simulation results. Because the entire project folder is copied for each new forecast, reducing file size decreases duplication time and storage requirements.

Terrain File

Previously, it was suggested to remove the terrain file from the HEC-HMS project, but this is no longer recommended and may cause errors in HEC-HMS 4.12. HEC-HMS no longer copies terrain files from the watershed folder to forecast folders, so keep the terrain file in your project directory. For hydrology purposes, NED 30m terrain data is generally sufficient.

Using HEC-HMS within the CAVI

Avoid having HEC-HMS open when switching between forecasts or navigating between the Modeling and Setup tabs in the CAVI. Doing so can cause issues like losing calibration values in the combined parameter editor.

HEC-HMS Compute Aborts Without Error Messages

If HEC-HMS aborts a forecast compute with no error message, validate the grids used in the model. Use the HEC-HMS Grid Validator tool (link here) to check for discrepancies that might cause failures. HEC-HMS does not provide specific grid error messages during compute; the validator tool is essential to identify grid-related problems.

HEC-ResSim

Spaces in Alternative Names

While HEC-ResSim permits spaces in alternative names, it is not recommended, especially when using those alternatives within CWMS.

The HEC-ResSim plugin uses a feature called variants, which are separate copies of an alternative’s time series mapping .fits file, to enable an alternative to function properly in multiple contexts (such as standalone use, CWMS forecast runs, or WAT simulations).

However, if you create multiple program orders in CWMS and use an HEC-ResSim alternative with spaces in its name across different forecast runs, the alternative may fail to select the correct variant .fits file during computation. This can lead to errors or unexpected results.

HEC-RAS

Avoiding Multiple Instances of HEC-RAS

If you open a CAVI watershed while a standalone HEC-RAS instance is running, the CAVI will take control of that HEC-RAS session. This causes the current HEC-RAS project to close immediately, terminating any ongoing computations, and then opens the watershed’s HEC-RAS project instead. To prevent this, always close all HEC-RAS instances before opening a CAVI watershed.

Proper File Storage

Make sure your base HEC-RAS model includes all necessary data (input HEC-DSS files, terrain data, projections, land use, etc.) within the watershed folder. Verify all file references are correct, and store these files in a Data folder inside the ras directory.

Boundary Conditions for 1D Storage Areas

If multiple boundary conditions share the same 1D storage area in your model, each boundary condition must have a unique name. To assign unique names:

  1. Open the Unsteady Flow Data Editor.
  2. From the Options menu, select Boundary Condition Names.
  3. Enter distinct names for each boundary condition linked to the same 1D storage area.

You can then verify correct model linking for each boundary condition within the Setup tab.

Observed Data

If your HEC-RAS alternative includes observed data, updating to a new HEC-RAS version may break links to that data. To ensure observed data displays properly during forecasts, you may need to fix these links.

To fix observed data links:

  1. Copy an example forecast.dss file containing observed data into the watershed’s base directory.
  2. In the HEC-RAS Unsteady Flow Editor, edit the observed data for the base model and set the source to the example forecast.dss file.

HEC-RAS stores these paths as relative paths, so forecast runs will correctly reference the appropriate forecast.dss file.

HEC-FIA

Upgrading Models from Older Versions

HEC-FIA cannot open projects created in version 3.0 or earlier directly. To upgrade an older HEC-FIA project:

  1. Open the project first in HEC-FIA 3.2.1 (or an earlier compatible version) and save it.
  2. Then open the saved project in HEC-FIA 3.3 or newer to complete the update.

Model Linking

After upgrading to a new CWMS version, it’s best practice to verify and set up the HEC-FIA model linking in the base watershed before creating new forecasts.

Testing New Forecast Runs

When creating a new forecast run (e.g., a Flood Damages Reduced forecast), it’s recommended to run test computations for both the HEC-RAS and HEC-FIA alternatives in the base watershed.

Start by copying an existing forecast.dss file from a previous forecast that completed a HEC-ResSim run. Adjust the HEC-RAS time window and update flow pathnames in the Unsteady Flow Data Editor. Run the HEC-RAS compute in the base watershed to generate outputs, including stored depth maps. Once HEC-RAS outputs are available, complete the model linking for the HEC-FIA alternative.