1.1 CWMS and HEC-RTS Differences

Section 1
Notes

 

This document covers implementing CWMS 3.0 / HEC-RTS 3.0 for a watershed, using the Russian River, California, watershed as an example.  This document includes both importing a CWMS 2.x watershed and creating a new watershed and adding models.

This document does not cover running the Russian River models.  Running the models for Russian River is covered under a separate document.

 

1.1                  CWMS and HEC-RTS Differences

 

CAVI 3.0 (Control And Visualization Interface) and HEC-RTS 3.0 (Real-Time Simulation) are both the same program, except that the CAVI has access to the CWMS Oracle database and HEC-RTS does not.  This is done with a software switch, so both are the same code.  HEC-RTS obtains data stored in HEC-DSS files and CAVI obtains data from HEC-DSS and CWMS Oracle.  Both programs share the same directory structure, so a watershed can be built and used with either program, except HEC-RTS will not be able to access data from CWMS Oracle.

In this document, the term CWMS 3.0 will be used often and represents the use of both CWMS CAVI 3.0 and HEC-RTS 3.0.

In short:

·         HEC-RTS uses only HEC-DSS and does not connect to a server

·         CWMS CAVI connects to the CWMS Oracle database for data.

 

Section 2 Purpose and Concepts

 

The intent of the Russian River CWMS 3.0 implementation is for “short-term” flow and stage forecasting and decision support for reservoir operations for locations within the Russian River watershed.  Offices have used CWMS for longer term forecasting and operations, but this implementation has not been tested in that context.  “Short-term” implies 7-14 days

The Russian River basin is a medium-size watershed, with an area of 1,485 square miles, located near the California coast, north of San Francisco.  The Russian has suffered extensive flood damage over the years, usually resulting from “Atmospheric Rivers” that bring warm moisture in from the mid-Pacific.  There are two reservoirs in the Russian, operated by the US Army Corps of Engineers.  They are Coyote Dam and Lake Mendocino near Ukiah, and Warm Springs Dam and Lake Sonoma in the upper Dry Creek area.

The Russian River basin is a famous wine region.  Sonoma County Water Agency (SCWA) is the primary agency responsible for water supply in the region and uses water from the Corps reservoirs for municipal and agricultural purposes.  Recently, there has controversy and discussions on changing the operations of Lake Mendocino to include weather forecasts, in hopes of retaining additional water supply during the summer dry season.

“Stage forecasting” includes real-time inundation mapping.  Since this would be modeling the actual event, the inundation maps will be much more accurate than static maps (of course, dependent on the accuracy of the precipitation forecasts and skill of the modeler.)  An inundation map computed from CAVI/HEC-RTS can be exported to a server and made available to first responders in the field using smart phones / tablets and Google maps, so that they can take appropriate actions prior to flooding.

Russian River Basin

Section 3 Importing from CWMS 2.1

Before you run CWMS 3.0 for the first time, you need to decide on a CWMS directory that will contain all your watersheds, model files, data, etc.  It is recommended to use the name “CWMS” in an obvious location.  We recommend that it is not in your users directory, but in a location that other users can easily access (such as “C:\CWMS” or “C:\RTS”).  Create that directory using Windows File Explorer.  

3.1            Create a Watershed

Run the CAVI.exe program.  The first time you run this, it will ask for you to agree to the terms and conditions, as well as the modeling programs.  It should ask you if you want to define a watershed location.  You can do this now, or when you create a new watershed or from the options menu.

Before you import a CWMS 2 watershed, you should make a backup of it by copying with Windows Explorer.  Caution – HMS will update files in the original watershed to 4.1, and you cannot back port them.  You can import from either the copy or original, but whichever one you choose, HMS will change the files in that directory.

Select the Setup module tab, then go to the File menu and select New Watershed

In the Directory text box, select the “Browse” (or “,,,”) button and enter in a label name and the name directory of where you will your watersheds.

Type in the name of the Watershed you want to create.  When importing from 2.1, the original name will not be kept, so you must specify a watershed name.  Then select the Import from CWMS2 and browse to the original (or your copy) workspace file (.wksp) in the CWMS 2 watershed.

3.1.1   Set a Projection

For CWMS 3, the watershed and all models must be geo-referenced.  Typically, Albers-Equal Area is the coordinate system used.  Press the Edit button on the Coordinate System line, then “Load from File” from the Map Coordinate Information dialog.

Browse to a .prj or projection file, usually associated with shape files generated by Arc.

3.1.2               Import the 2.1 Watershed

Now press the “Browse…” button on the Import CWMS 2.1 Watershed line in the Create New Watershed Dialog.  Browse to the CWMS 2.1 .wksp file from the watershed you wish to import.

 

Press OK to begin the import process.

 

ResSim imports first, as it usually contains the stream alignment, that models use as a reference.

When HMS asks to convert the project to 4.1, select “Convert Project”.  Caution – if you have not made a backup, do so before you select convert!

HMS will write several error messages to the CAVI message window about not being able to find met models.  Ignore these error messages, as the met models are only generated in CWMS 2.1 when making a forecast and you should be importing from the base directory which will not have those met models.

The FIA version used in CWMS 2.1 is incompatible with CWMS 3.0, so it will not be imported by the wizard.

  

FIA requires FIA 3.0 or later.  You cannot import an earlier version.   Import a 3.0 model by right-clicking on the FIA icon, and selecting “Import”.  (Note:  Sometimes this dialog gets covered up by other windows (like the CAVI), so you may need to tab or look for it.)

 

Press the Import Alternatives button after selecting the project.

 

 

3.1.3   Add Background / Internet Maps

 

CWMS 3.0 is setup to load Google and Bing maps from the internet.  These usually are quite valuable when using the CAVI.  Alternatively, geo-reference images (e.g., .MrSid) can be added so that a background map will still show up in case you do not have internet connectivity.  If you add such an image file, use the “Import Image…” menu item from the map layers dialog.

(Usually you will add a image file only once, whereas an internet map might be changed several times; for example going from satellite to streets view.)

To add an internet map, select “Add Internet Map” from the Maps menu of the CAVI (you must be connected to the internet!) and select which map you want.  Normally, a terrain map is best for a larger (zoomed-out) view.  When you zoon-in, the satellite map is often best.

 

Depending on where your watershed is, your map might be fuzzy if the coordinate system is not the same as the background map (no, not a local dyslexia issue!)  Usually, the internet map and watershed coordinate systems are different (internet maps use a variation of UTM).  Since background maps are solid, translating pixels to a different coordinate system can make them off a little and make things fuzzy.  This is more true for the edges of the US continent, than in the middle areas.  Check that your display coordinate system is correct from the Maps menu.  (The display coordinate system has no impact on models or model execution.)

 

If some of your layers disappear, make sure the internet map is the bottom map layer (other things draw on top of it.)

 

Now that the watershed has been imported and maps added, it is time to associate model alternatives and link the models together.  At this time, that step is not done automatically when importing a CWMS 2.1 watershed.

Section 4 Create a New Watershed from Existing Models

 

This section covers creating a new watershed and importing existing models that have not already been included in a CWMS installation

Before you run CWMS 3.0 for the first time, you need to decide on a CWMS directory that will contain all your watersheds, model files, data, etc.  It is recommended to use the name “CWMS” in an obvious location.  We recommend that it is not in your users directory, but in a location that other users can easily access (such as “C:\CWMS” or “C:\RTS”).  Create that directory using Windows File Explorer.

 

4.1            Create a Watershed

 

Run the CAVI.exe program.  The first time you run this, it will ask for you to agree to the terms and conditions, as well as the modeling programs.  Select the Setup module tab, then go to the File menu and select New Watershed.

In the Directory text box, select the “Browse” (or “,,,”) button and enter in a label name and the name directory of where you will your watersheds.

Type in the name of the Watershed you want to create. 

 

4.1.1                 Set a Projection

 

For CWMS 3, the watershed and all models must be geo-referenced.  Typically, Albers-Equal Area is the coordinate system used.  Press the Edit button on the Coordinate System line, then “Load from File” from the Map Coordinate Information dialog.

 

Browse to a .prj or projection file, usually associated with shape files generated by Arc.

Select the time zone from the drop down menu.  Note that CWMS runs models in “watershed time”, which is the time zone without any daylight component.  (The models are generally unable to handle the daylight savings time shift.  The CAVI can handle the shift if you set the CAVI’s view time zone correctly.)

Press the OK button

 

 

 

4.2                  Import background shape files 

 

These files are usually generated during building of the HMS model in GeoHMS.  Note:  HMS is not geo-referenced, but the CAVI is.  Be sure your shape files have projection files (.prj) with them.

Go to the Maps menu, and select ”Add Map Layers”

 

Browse to the directory that contains your shape files, usually the HMS “maps” directory.  Select all the maps that you wish to add, be sure the “Create Copy” checkbox is selected, then press Open.  The maps should show up on the main CAVI map panel (although often in odd colors!)

 

You can make the map colors more palatable by changing the map layer properties.  From the Maps menu, select “Map Layers…”

 

From the Map Layers dialog, select the map, right-click and select “Properties…”

 

Uncheck the “Display Fill” (if set) and then select an appropriate border color.  If you are using internet maps (non-white background), lighter colors usually show up better; sometimes yellow works the best.  If you are not adding a map background, then darker colors work better.

    

 

Do a similar operation with the remainder of the layers.

 

4.2.1 Add Background / Internet Maps

 

CWMS 3.0 is setup to load Google and Bing maps from the internet.  These usually are quite valuable when using the CAVI.  Alternatively, geo-reference images (e.g., .MrSid) can be added so that a background map will still show up in case you do not have internet connectivity.  If you add such an image file, use the “Import Image…” menu item from the map layers dialog.

(Usually you will add a image file only once, whereas an internet map might be changed several times; for example going from satellite to streets view.)

To add an internet map, select “Add Internet Map” from the Maps menu of the CAVI (you must be connected to the internet!) and select which map you want.  Normally, a terrain map is best for a larger (zoomed-out) view.  When you zoon-in, the satellite map is often best.

 

Depending on where your watershed is, your map might be fuzzy if the coordinate system is not the same as the background map (no, not a local dyslexia issue!)  Usually, the internet map and watershed coordinate systems are different (internet maps use a variation of UTM).  Since background maps are solid, translating pixels to a different coordinate system can make them off a little and make things fuzzy.  This is more true for the edges of the US continent, than in the middle areas.  Check that your display coordinate system is correct from the Maps menu.  (The display coordinate system has no impact on models or model execution.)

 

If some of your layers disappear, make sure the internet map is the bottom map layer (other things draw on top of it.)

 

 

 

Section 5 Import Models

 

Before importing any models, be sure:

·         Be sure that your models run without errors on your computer.  If the model does not run outside of CWMS, it will not run inside of CWMS.  Fix any problems before import.

·         Where possible, use relative paths to files, not absolute paths.

·         The directory(ies) where you models are located are “clean”.  Backup your original directory and remove all log, output and temporary files.  You should also remove DSS files containing historical data used for calibration.  Keep DSS files that contain model parameters, such as storage-elevation-area curves.  You should have a trim, pristine directory with only those files needed for real-time execution.

·         Keep blank spaces and dashes out of names and files.  (HMS will change dashes “-“ to underscores “_” without the CAVI knowing it.  Don’t use unnecessary non-alpha characters.

Many errors have arisen due to either messy directories or not checking that models run correctly on the PC environment. Errors are more difficult to track down through CWMS than directly from the models themselves.

Setting up models in the CAVI essentially follows the order of the submenu items in the “Models” menu in the Setup Module.

5.1.1               Program Order

 

First, determine what modeling programs will be run for this watershed.  From the Models menu, select “Program Order”

This dialog identifies which models will be run and their order, for example HMS outputs flows that are read in by ResSim.  You can create a new program order and add or remove programs using options under the Edit menu.

 

The Russian River uses all the models in the default program order, so no change is needed in this case.

5.1.2               Import ResSim

 

Now, we will import the models. Since the program order is already established, you do not need to import them in order.  However, ResSim contains the “stream alignment”, which is used by most of the models, so it’s best to import that first.  Its framework also most closely fits the CAVI, so other components, like time-series icons, can be imported too.

From the Models menu, select Import -> ResSim

Generally, the entire watershed is imported:

 

If you select “ResSim” from the left panel, you should see the alternatives show up in the lower panel. Right click on an alternative and select “Display in Map Window”

 

 

 

5.1.3   Import HMS

 

Next, do the HMS import.  (Note, HMS will upgrade earlier versions in place, so be sure you have a backup of your hms directory.)

5.1.4               Create MFP Alternatives

 

If you are not importing a previous CAVI watershed, then you will need to build MFP alternatives after importing HMS.

 

 

5.1.5               Import RAS

 

Import RAS in the same manner as HMS

 

5.1.6    Import FIA

 

FIA requires FIA 3.0 or later.  You cannot import an earlier version.   (Note:  Sometimes this dialog gets covered up by other windows (like the CAVI), so you may need to tab or look for it.)

 

Press the Import Alternatives button after selecting the project.

 

All the models are now imported.  Next step is to associate alternatives with them and link them together. 

If you did not import a CWMS watershed, you can create time series icons in a separate step after linking the models.

 

 

 

Section 6  

Model Integration

 

Data is exchanged between models in the CAVI using an HEC-DSS database file and DSS pathnames with “F parts” that identify the model and scenario or “alternative”.  Each individual model or model input is called an “alternative”.  An alternative may be different reservoir operations, or a different forecast for precipitation, or different loss or routing parameters.  For example, there are typically at least three (future) precipitation alternatives:  No future precipitation, QPF, user specified.

Each model alternative is assigned an alpha-numeric character, or “key”, to identify that alternative.  Different models may use the same character (e.g., you may have “B” for base HMS and “B” for a ResSim alternative.)  The model alternative keys are concatenated together to form a “Run Key”, which is used in the F part to identify the data set.

For example, you may have a QPF alternative for MFP, the Meteorological Forecast Processor, which combines observed precipitation and future precipitation, in this case QPF.  Let’s assign that alternative the letter “Q”.  HMS reads this precipitation to generate flows, both observed and forecasted.  It would read precipitation with an F part of “Q”.  Suppose our HMS model was calibrated for wet conditions and we assigned that model the alternative key “W”.  HMS would write out flows to DSS with a pathname F part of “QW”.  ResSim would then read in those flows, using the run key “QW”.  Let’s assume this is the standard operation model and we’ll use the key “S”.   It would simulate reservoir operations and write project out flows (and other flows in the watershed) using the run key (F part) of “QWS”.  HEC-RAS would then read in these flows to compute stages and write those stages with a run key of “QWSB” if it had an alternative key of B.  In turn, FIA would read in those stages to compute damages.

Reports, output, log files, etc. all use this convention to identify the complete data set that they represent.  In short, ff a “%” represents a model, then log files and the F parts of the pathnames used will be:

·         %                     - output from MFP

·         %%                 - output from HMS

·         %%%              - output from ResSim

·         %%%%           - output from RAS

·         %%%%%       - output from FIA

You can use these percent signs in the model interface module to identify data sets, especially in time series icons to identify what DSS data sets to use.

Currently, a “trial” number (0) is internally appended to each ID key and will appear in the F part.  We will not address trials at this time.

Assign Model Alternative Keys

From the Model menu, select “Model Alternative Keys”.  In the dialog, assign a single number or letter to each model and model alternative that will be used.  You can use the same character between different models, just not for the same model. 

6.1                  Forecast Runs

 

Once all the model alternative keys have been assigned, the models are concatenated into “Forecast Runs”.  From the Model menu, select “Forecast Runs”.

Press the New button and select an alternative for each model.

Enter in a name for the forecast run, then press OK or Apply (if you will create more forecast runs now.)

 

6.2                  Model Linking

 

Once the forecast runs have been defined, the specific output from each model needs to be linked to the input of the following model.  CAVI 3.0 attempts to do most of this effort for you, however, identical location names must be used for all the models.  Caution: You must check and adjust all linkages, as the automated linking usually is not complete.

To link the models together, go to the Models menu and select “Model Linking”

Go through each of the models in the Drop down selector after “Model Requiring Input” and then check or select the correct linking for that pathname.

 

6.2.1               Linking MFP

 

MFP is pretty straight forwards:

In this case, the CAVI asked MFP what data (DSS pathname) it needed.  MFP provided only one and the CAVI assumed it would be extracted from the observed dataset (database).  The dates in the pathname will be changed when a forecast is run.

 

6.2.2 Linking HMS

 

HMS has a much larger list to link.  In this case, all data, except for the precipitation from MFP will be extracted from the observed data.  Change the Precipitation location parameter to get input from MFP.  Then check / set the remaining observed flows.  You should be able to see right away the advantage of using consistent / identical location names throughout the system.

 

6.2.3 Linking ResSim

 

ResSim obtains most of the flows it uses from HMS computes, and some observed data (such as flows, storage elevations, etct.)  You’ll see that the CAVI doesn’t know if flow is from a model or the observed database, so it assumes extracted from observed.  To change those flows coming from HMS (ResSim calls them “Known Flows”, select (highlight) them in the editor and then press the “Results from Model” button.

Now you must go through each data set and check that the correct location is selected.  The CAVI will do the best it can to match data sets, but it usually is not complete and will guess.  Caution – Not checking this list carefully is often the source of many errors!

The “Browse” button at the bottom of the editor will bring up a selection dialog that is often easier to use than the drop down selection on the right.  You can keep this dialog up and select additional names in the editor and set them, without having to close the editor each time.

 

 

 

6.2.4               Linking HEC-RAS

 

Linking RAS takes some special treatment, because it uses river mile identifiers for locations instead of location names.  If the RAS model has a location name in the “Description” field, then CWMS will try to match that with output from the previous model.

 

For steady flow analysis, you will need to specify total (maximum) flow at RAS junction points.  You should have an HMS or ResSim junction at each handoff point, and use the total flow.  For unsteady flow analysis, you specify incremental (local) flows at each junction, and RAS uses that to route the flow with.

An important point to remember is that HMS and ResSim compute flows at junctions or subbasin outlets, so those flows must be added to the RAS model at that point (a lateral inflow hydrograph), not distributed along the stream (not a uniform lateral inflow hydrograph).  Also, be sure that you add the hydrograph from DSS at the correct location; some hydrographs need to be connected to a storage area, some a lateral inflow.

Hydrographs for RAS may come from ResSim or HMS.  HMS generates “Local Flow”, which is the flow that is generated between the upstream junction and downstream junction, not including stream flow coming into the downstream junction.  (If you have a separate tributary entering a junction, you must be sure to include that flow.  Often that is a separate lateral inflow hydrograph to RAS, as HMS does not compute local and tributary as one dataset.)  Generally, ResSim provides the flow out of reservoirs and HMS provides local flows; HMS computes locals throughout the basin and ResSim usually will only produce locals (copied from HMS) downstream of reservoirs modeled.

If any of the model linking lines are highlighted in purple that indicates the same dataset is being added in more than one location and is usually an error.

You must verify that the correct hydrographs are being added to the RAS model at the correct locations.  Adding the wrong hydrogaph is a substantial source of error, and of course, produces erroneous results.  To check for correct hydrographs, you will need to create a “forecast” for a historic or calibration event and compare local flow hydrographs from HMS to change in the hydrographs on the main stream.

Using historic data, create a forecast for the event time period.  Compute the models through HEC-RAS.  (If this is the first compute, you will need to check the other model links.)  Select the RAS model from the “Forecast” panel on the left side of the CAVI and the press the “Stage and Flow Hydrograph” button from the Reports tab.  After that, select the HMS model from the Forcasts panel and expand it.

In the RAS plot, select only the Plot Flow check box.  Starting at the top most cross section, walk down each cross section plotting the flow and when you get to a latteral inflow hydrograph, check that the increased flow is consistent with the hydrograph plot from HMS at that location.  For example, at Talmage, the RAS hydrograph plot prior to the inlfow is: 

The HMS plot for Talmage Loc is:

And the RAS hydrograph below the latteral inflow is:

 

The peak went from 4,000 CFS to around 6,000 CFS with the addition of the local Talmage inflow of 2,500 CFS, which is consistent with dispersion in an unsteady flow model.

Review the plots for all cross sections in the RAS model making sure the correct latteral inflow hydrographs are used.

6.3                  HMS Graphical Parameter Calibration (Slider Bars) Setup

The soil moisture conditions of a watershed have the greatest impact on runoff, after precipitation.  One of the most important steps in the process is calibrating the HMS model to current (soil moisture) conditions; miss-calibration can lead to huge errors.

HMS has a calibration aid to help adjust the model to current conditions, call the “Graphical adjustment of forecast parameters”, or “slider bars”.  Generally, this function is best used on “gagged headwater” subbasins, or a small group of subbasins, so that you can compare computed verses observed runoff and make adjustments that are not obscured by routing or reservoir issues (e.g., wind changing reservoir elevation.)  Flows from gages downstream of a reservoir or in an area that affects flows (e.g., wetlands) and not as helpful for calibrating soil moisture.  Review the HMS model and select those subbasins to use as calibration points.  Once you’ve adjusted parameters there, those adjustments can be made to other (non-calibration) subbasins.

In the CAVI, adjustments are made using “zones”, a collection of similar subbasins that have similar parameters.  Thus when you make adjustments to parameters for a subbasin, you can apply that adjustment to other subbasins in the same zone.

After you have setup zones, and have a forecast alternative, you can setup the slider bars using the following procedure.

Start the configuration by opening HEC-HMS, and selecting a forecast alternative on the compute tab. Right click on the forecast to display the pop-up menu (Figure 2). Choose “Select Calibration Parameters” to display the Select Forecast Parameters dialog.

 

Figure 3 Pop-up menu for a Forecast Alternative

 

Figure 4 Select Calibration Parameters (nothing selected)

 

The dialog for selecting forecast calibration parameters has one or more tabs. There is a tab for each loss rate, transform, or baseflow method. If a method does not have a zone configuration, the tab is not shown. Choose a method tab; then choose a zone to select parameters (Figure 4). The available parameters will be shown in the right-hand box.

 

Figure 5 Select Calibration Parameters (zone selected)

 

Select one or more parameters, and click on the select button (Figure 5). 

Figure 6 Select Calibration Parameters (ready to select parameters)

 

 

When a zone is selected the lower part of the dialog shows subbasins in the zone. Parameters can be selected for each subbasin by selecting a subbasin, and selecting the parameters for the subbasin (Figure 6). These parameters will override zone parameter values for the subbasin.

Figure 7 Select Calibration Parameters (choose parameters for subbasin overrides)

 

Adjust Slider Limits

The minimum and maximum values for each parameter are set to default values. To change these values, right click on the forecast, and select “Calibration Parameter Settings” in the pop-up menu.

The Parameter Settings Editor can also be displayed for the Graphic Parameter Editor by right-clicking on a slider and choosing Adjust Slider Limits in the pop-up menu.

Figure 8 Parameter Settings (default limits)

 

Enter appropriate values for each parameter, and click on the Apply button.

Figure 9 Parameter Settings (modified limits)

 

Display Calibration Editor

In the CAVI, select the HMS model in a forecast alternative, then click the Combined Parameter Editor Button (Figure 9). This will display the Forecast Parameter Adjustment Table (Figure 10).

Figure 10 HEC-HMS Compute menu

 

Figure 11 Forecast Parameter Adjustment Table

 

Click on the Graphic Editor button in the lower left corner of the Forecast Parameter Adjustment Table (Figure 10) to display the adjustment sliders.

Figure 12 Calibration Editor

A parameter value can by adjusted by moving a slider, or entering a value in the test box to the right of the slider. The forecast simulation is computed when the “Apply” button is pressed. If the “Compute with each slider change” box is checked, the forecast will be computed whenever a slider is moved.