HMS Calibration Library Script
https://github.com/HydrologicEngineeringCenter/HEC-RTS-scripts/blob/main/HMS_Calibration_Library.py
The HMS calibration library script is designed to 1) export and archive calibrated HMS parameter overrides (saved in the HMS_Alt_Name.forecast file) from an active forecast to a calibration library directory located within the base watershed directory (...watershed/<Watershed_Name>/hms/forecast/calbration_library) or 2) import an existing HMS parameter override file from the calibration library to the active forecast. Using parameter overrides as a starting point in a forecast that has similar conditions can provide time savings.
When the script is run for the first time, it first checks to see if a calibration library exists within the base watershed HMS forecast folder. If it does not exist, the script creates a folder called “calibration_library” under the hms/forecast folder within the base watershed. The script creates a dialog that is comprised of three sections as shown in the figure below.
HMS Calibration Library Tool
The first section describes where the calibration library is located on the local PC and, if defined, where your remote calibration library exists. The remote calibration library is optional and can be left undefined; however, if a remote directory is specified, it allows users to sync between the local calibration library and a remote calibration library on a shared drive. The script only accesses the remote calibration library during the upload or download actions; otherwise, no connection is made with the script and files in the calibration library.
HMS Calibration Library Tool File Transfer Illustration
The second section handles importing of forecast files. For first-time users, there likely will be no forecast files in the calibration library, unless files have been downloaded from the remote calibration library or the watershed was shared with the local calibration library included. This section imports forecast files from the base watershed directory on the local PC into the active forecast directory. The list of available forecast calibration files includes only those files applicable to the selected HMS alternative. For example, a watershed may have both a “Rain” HMS alternative and a “Snowmelt” HMS alternative. Since these alternatives require different forecast calibration files, using one in place of the other would cause issues within your HMS model. Thus, the list is filtered to show only the HMS forecast calibration files applicable to the selected HMS alternative. The selected HMS alternative is the HMS alternative within the selected forecast run alternative, which is the run that is highlighted in the CAVI model tree. In contrast, the upload and download functions in the first section are not filtered by selection and allow you to work with any forecast calibration file between the local calibration library and the remote calibration library. The image below illustrates (red lines) how a HMS alternative from a selected forecast run alternative is used within the HMS calibration library tool to filter the available forecast calibration files from the calibration library.
Selected HMS Alternative with HMS Calibration Library Tool
The third section is for exporting forecast calibration files to the local calibration library. This process exports the current forecast calibration file for the active HMS alternative to the local calibration library. By default, the export name is the forecast date and time (i.e. 10Apr2025_1200), but the user can choose to retain this name or provide a custom one. For instance, a file might be named to reflect an event (i.e. Spring_Flood_2025”) rather than a specific forecast time. The name chosen for the forecast calibration file to be exported will be appended to the forecast calibration file name. For example, an HMS alternative named “Snowmelt” would result in a file called “Snowmelt_10Apr2025_1200.forecast”. The above image illustrates (green lines) how the export name is appended to the HMS alternative name and saved to the calibration library. If a user provides a name that already exists in the calibration library, a message box will alert the user that the name is already in use and will offer the option to overwrite the existing file or cancel and choose a new name. The same checks and prompts on naming apply when downloading and uploading forecast calibration files to and from the remote calibration library.
When selecting an existing calibration file to use within a CAVI forecast you will be prompted that the forecast file is being copied into an active forecast. The CAVI will close the active forecast, and you will see the typical window for a forecast closing (you will see prompts for saving model files). The forecast will automatically close and then re-open. You should notice zonal overrides and element overrides from the selected calibration file in the CAVI forecast.