BatchRunControl – A Script for HEC-ResSim

Revised Mar 2019 for ResSim 3.5

General

The BatchRunControl script (BatchRunControl.py) provides a graphical interface that allows users to select multiple pre-defined HEC-ResSim simulations and alternatives from a single watershed and execute them in a batch mode.

Set Up

Copy the BATCH_MyWatershed.BAT file and the BatchRunControl.py file into your watershed (or, really, wherever you want, see the TIP paragraph below).


Figure 1. Location of script and batch files

The BatchRunControl.BAT file contains the command line to run ResSim in batch mode using the BatchRunControl.py script. Understanding this command line is quite important to proper operation of the script. Below is an example command line.

D:\MyProgramFiles\HEC-ResSim-3.4.1.67\HEC-ResSim "D:\MyProgramFiles\ResSim Batch Processing\BatchRunControl.py" BatchRunControlLog "D:\CurrentProjects\Example Watersheds\Hayes_Basin"

The command line has four parts:

  1. The first part is the full path to the ResSim executable. You must update this path to match the folder where HEC-ResSim.exe resides on your computer. 
  2. The second part is the name of the script. Update the full path to the BatchRunControl.py file on your computer.
  3. The third part is the base name of the log files that will be generated by the script. You can change this name but you don't have to. The log files will be written to the watershed folder.
  4. The fourth part is the full path to your watershed. You must revise this path to point to the watershed.

NOTE: If any of the paths you enter above includes one or more spaces in a folder name, you must enclose the whole path in double quotes (" ").

TIP:  If you don't want to copy the .bat and .py files into each watershed, consider making a copy of the .BAT file for each watershed you want to run in batch mode and name each .BAT file for the watershed it will execute. That way, you can keep your batch files and the script in just one place on your computer.

User Interface

The user interface consists of two windows: a Log Window and a Main Window.

The Log Window consists of a scrolling text area, a progress bar, and a status bar (Figure 2). The Log Window displays current HEC-ResSim output regardless of which log file is currently in use.


Figure 2. Log Window During Startup

The Main Window consists of a tree pane and a button pane (Figure 3). The tree pane contains a tree with a folder for each simulation in the watershed. Each simulation folder contains nodes for each alternative available with that simulation. The alternative nodes are leaf nodes if no trials are defined. If trials are defined for an alternative, the alternative node is a folder containing leaf nodes for each trial plus one leaf node for the base alternative.

Folder nodes can be expanded or collapsed by clicking on the  icon next to the node or by double-clicking on the folder. All folder nodes can be expanded by clicking the Expand All button or collapsed by clicking the Collapse All button.


Figure 3. Main Window

Execution

Double-click the BatchRunControl.BAT file.

Two console windows will appear – one is for the batch file and one is for ResSim itself (if the HEC-ResSim.config file has "showConsole=true" in it). In addition to the two console windows, a Log Window will appear when the script first starts – this Log Window is essentially a parallel of the ResSim console window – so what appears in one will probably appear in the other (eventually).

The ResSim console and the Log Window will display the progress of reading the simulations from the specified watershed (Figure 2). It may take a few minutes to read all of the simulations. After all the simulations have been read, the Main Window will be displayed (Figure 3).

Individual Simulations and Alternatives can be selected or deselected by clicking the checkbox next to its node. Clicking the checkbox next to a folder node selects or deselects all nodes in the folder. All nodes in the tree can be selected or deselected by clicking the checkbox next to the root (Simulations) folder or by clicking the Select All or Select None buttons. Clicking the Invert Selections button reverses the state of all current selections.

By default only simulation names are displayed at their folder nodes. To see the each simulation's time window, check the Show Times checkbox in the button pane then click the +/- box (once or twice) to the left of the simulation you are interested in. The simulation time window will appear as illustrated in Figure 4. NOTE – if the time window information doesn't appear properly, uncheck the show times box and then re-check it. Then click the +/- button again. This time, the time window will display properly.


Figure 4. Main Window with Show Times Selected

Clicking the Run Selected button starts running the computations for each leaf node selected.

Exiting

To Exit the Script – click the X in the upper right corner of the Main Window or Click the Cancel button. These will exit the script, even if it is currently running computations.

The Cancel button may result in the following message box (Figure 5):


Figure 5. Unexpected Close Message

If you see this message box, there's nothing to worry about, just click the No button.

Log Files

Log files are written to the watershed directory specified on the command line and are named BatchRunControlLog_YYYY-MM-DD_hhmm_id.log, where YYYY-MM-DD_hhmm is the date and time the log file was opened, and id is a descriptive identifier.

The Startup identifier indicates that the log file contains output generated while the watershed was being read. 

The Simulations identifier indicates that the log file contains output generated while running computations. The simulations log file contains output from the script indicating when it started specific computations, as shown below:

2019/03/07-13:25:36 
2019/03/07-13:25:36 ###
2019/03/07-13:25:36 ### Computing simulation 1999.10.18-2400, alternative GC Only
2019/03/07-13:25:36 ###

NOTE: Don't use the Separate Log Files checkbox. It is not currently working as intended…

When checked, the simulation log files will (are supposed to) contain only the script output as shown above plus a small amount of HECResSim output that occurs between simulations. The HEC-ResSim output that occurs during simulations will be contained in log files with identifiers like:

Simulation{Alternative} or Simulation{Alternative{Trial}}.log (Figure 6). 

Figure 6. Log File Location and Names

Cleanup

If you use the BatchRunControl script regularly, your watershed folder is going to fill up with log files, so we recommend that you make it a practice to delete old logs that you don't need before launching the .BAT file.