Make sure that the base model functions correctly - either prior or after upgrading to CWMS.    

The HMS project should successfully compute from the setup tab of the CAVI via selecting HMS in the main toolbar (Figure 1).  Guaranteeing that the base HEC-HMS project computes correctly allows for faster debugging in the future.  Make sure all linked DSS files, shapefiles, and grid cell files are local to the HEC-HMS project directory.  Saving all external files within the HEC-HMS project directory will ensure the external files are kept with the HEC-HMS project when the project location is moved. Refer to the Responding to Prompts for Missing DSS Files section below for additional information specific to external DSS files. Another action to optimize the amount of time HEC-HMS takes to open a basin model map is described in the Performance Improvements by GIS Layer Clean-up section below.

HMS Model Tuning Tips

For tuning an HMS model before or after importing it into a CWMS watershed:

  • Keep all the DSS records needed for an HEC-HMS compute inside the HEC-HMS project tree (inside the project folder saved to disk). This will ensure that HEC-HMS can find all the required data when the project is opened and at compute time. And, it avoids prompts for DSS files when the project gets moved.
  • Similarly, keep all the shapefiles and ModClark grid cell files needed by the model inside the HEC-HMS project tree.
  • Minimize the volume of data in the HMS project tree supporting the base model test compute by cleaning up the HEC-HMS model; remove all unnecessary components, remove unnecessary DSS records, and delete old simulation results. The entire HEC-HMS project folder will be copied to each new forecast; therefore, whatever is in the HEC-HMS project folder will be duplicated per each forecast and the more to duplicate, the more time and storage each forecast will consume.

Responding to Prompts for Missing DSS Files.  

If an HEC-HMS project references DSS files that cannot be found when opening a project, one or more prompts will be shown to the user asking that the missing files be identified, as shown in the figure below. This is a common issue when DSS files were used which resided outside of the HEC-HMS project directory and the watershed or forecast is copied to a different folder or shared with a teammate without the external DSS files being provided and then saved in the same location. In some situations, modelers may need to click through many missing file prompts while browsing to the desired files. Making sure all DSS files are saved within the HEC-HMS project directory will prevent the following prompt when opening the HEC-HMS project on a different computer. 

When the Missing File editor does open, do not press the Cancel button or close the dialog by pressing the X in the upper right. If you do press the Cancel or X options, HEC-HMS will automatically reference the project DSS file (default DSS file in the project directory). The HEC-HMS team will modify this behavior for future software releases so that HEC-HMS will not longer automatically switch the DSS path to the project DSS file. The file path will not be updated when clicking Cancel or X.  The user will have to repair the data record path prior to running a simulation. The approach to fix the missing data path is as follows:

  1. Identify the pathname and DSS file referenced in the Missing File editor. See the red box in the figure below. 
  2. Using Window Explorer, find the missing file and place a copy of the file within a "data" folder located within the HEC-HMS project directory. 
  3. Within the Missing File editor, navigate to and select the missing file that has been placed in the HEC-HMS project directory. Click the OK button. Now, all shared data components that referenced the missing file will be updated to point to the new file location. 

In some situations it is possible to have many successive prompts.  As a last resort, you can kill the CAVI processes and investigate and address the file reference, then perform the upgrade again.  

For more comprehensive information, and suggestions for preventing prompts prior to opening a watershed in CWMS 3.2.1, see Additional Details for Advanced Users.

“Path not found” Errors at Runtime.

During a simulation, HEC-HMS will attempt to load external DSS data using the file pathname and DSS pathname defined in the user interface. Missing data commonly occurs if modelers failed to correctly respond to prompts regarding missing DSS files at some time in the history of a CWMS watershed, by choosing the wrong file, or by simply pressing the Cancel button or Escape key to quickly dismiss the prompt(s).   In the latter case, HEC-HMS sets the “DSS File Name” for the specified DSS record as the project DSS file (i.e., the DSS file located in the “hms” folder with the same name as the HMS project), “DSS File Name: NAB_West_Branch_Susquehanna.dss” for example, where NAB_West_Branch_Susquehanna is the name of the HMS project.

One option to quickly localize external DSS records is to use the Save Project As option from the File menu. The Save Current Project As dialog is shown below. There is an option to copy external DSS data to the local project directory. When this option is selected, HEC-HMS will create a separate DSS file for all time-series, paired, and gridded data components and place the DSS files in a "data" folder within the HEC-HMS project folder. HEC-HMS will do this for all DSS components, for those in DSS files outside the project directory and for those saved to DSS files within the project directory. 

 Performance Improvements by GIS Layer Clean-up. 

Sometimes, the rendering performance for the basin model map is slow when there are background shapefiles being displayed. Below are a few suggestions for improving how quickly HEC-HMS can open background maps. 

Background maps can be added to a basin model through the Map Layers editor. Once a basin model map is open, go to the View menu and click the Map Layer... menu option to open the Map Layers editor, as shown below.

  1. Make sure all background maps (all shapefiles) are saved locally within the project directory. The preferred practice is to create a "maps" folder within the HEC-HMS project directory and place all shapefiles in this directory. If you are not sure where a shapefile is located on your computer, remove it from the basin model map layers list and then add it back after you have placed a copy within the project directory. 
  2. Use a more recent version of HEC-HMS, Versions 4.5 or 4.6. Recently, the HEC-HMS software has been optimized for displaying background shapefiles. 
  3. Use tools within ArcGIS to simplify the polygons and lines within the shapefiles. Sometimes the shapefiles contain many, many vertices and it takes a long time for the software to display the GIS feature. Generalizing, or simplifying the features will reduce the number of vertices and imporve draw times. 

An emerging preferred practice is to represent subbasins and reaches using GIS features. The following tutorial shows how to convert subbasins and reaches to GIS elements - Geo-Referencing Existing Basin Model Elements using Shapefile Information. Once subbasin and reach elements have been converted to GIS elements, then the subbasin and reach shapefiles can be removed from the Map Layers list. HEC-HMS uses a different file format, not shapefiles, to draw the subbasin and reach polygons. In addition, you can turn off the subbasin and reach icons and select polygons and polylines when interacting with the basin model.