Creating and Using Scripting Alternatives
The Scripting Alternative is created and edited through the HEC-WAT user interface. The Scripting Alternative editor tells HEC-WAT which script to run when the Scripting Alternative in the program sequence. The Scripting Alternative editor allows the user to define input and output data locations (time series) used in the script, and create output variables for FRA computes.
Creating a Scripting Alternative
The Scripting Alternative is created by the user by right clicking on the Scripting model in the HEC-WAT model list. The user must give the Scripting Alternative a name. A description can be provided now or updated later. Clicking OK creates the Scripting Alternative and opens the Scripting Alternative Editor
Configuring the Scripting Alternative
The Scripting Alternative may be configured by the user by right clicking on the Scripting Alternative in the HEC-WAT model list and selecting Edit... or in the Edit Model menu of a simulation and selecting the desired Scripting Alternative. The Scripting Alternative editor allows the user to update the description or edit the script called by the Scripting Plugin during the compute, as well as define expected input and output data. Data Locations can be defined in this window, representing points where the script requires an input or provides an output, typically as time series data. The HEC-WAT Model Linking editor is used to link the input data locations to the script, and other models can be linked to the output data locations. Output Variables, which are metrics collected by HEC-WAT during a Flood Risk Analysis compute and summarized in the results file, can be defined if required.
The Jython script associated with the Scripting Alternative is stored in a file within the watershed, typically in the \scripts\
directory. When a new Scripting Alternative is created, an example script will be created showing how to write a timeseries and create an Output Variable. The script can be edited by clicking the Edit Script button or in an external editor by opening the script file. If using an external editor, one should be careful to not mix indentation formats (spaces versus tabs) when using an additional editor.
Clicking "Edit Script" opens the HEC-WAT Script Editor, which includes an API reference window to assist the user in writing the script.
Output Variables, computed during an FRA compute as a summarization of the model's output for each event computed, can be produced by the Scripting Plugin if they are defined in the Scripting Alternative editor. The output variables can be computed on an output data location using one of several statistics, or computed by the script itself by defining a function called computeOutputVariable
in the script, which is passed parameters for each Output Variable selected.
Using a Scripting Alternative
The Scripting Alternative can be added to a simulation like other models. First, the Scripting Plugin is added to the Program Order and when creating a simulation, the desired Scripting Alternative is selected. Finally, the Model Linking editor should be used to define inputs to the Scripting Alternative and to link other models to the output from the Scripting Alternative.
Best Practice
When developing a Scripting Plugin script, it is preferable to have one task per script, rather than creating one script that does many tasks. This task may perform the same or similar operation across many locations or inputs. By limiting the script to a single task, it will be easier to debug the script and to adapt to other model runs or other watersheds.
A minimal outline of a Scripting Plugin script is provided here:
Jython Script Example
# import statements go here
# note: code outside of `computeAlternative` will also be evaluated at compute time.
# this function must be named `computeAlternative` to be run by the Scripting Plugin
def computeAlternative(currentAlt, options):
# do stuff here
if failure:
return False # do this to report that the script failed
return True # do this to report that the script was successful
At compute time, the computeAlternative
function defined in the script is called, with two parameters, currentAlt
, which contains the Scripting Alternative object, and options
, the HEC-WAT compute options object. The computeAlternative
function should return True
if the script runs successful, and False
if the script was not successful. If an error occurs during the execution of the script, or the computeAlternative
function returns False
the Scripting Plugin compute will fail.
The first argument, currentAlt
, is the Scripting Alternative object, which gives access to the input and output data locations, which can be linked in the HEC-WAT Model Linking Editor, as well as the output variables. The second argument, options
, is a ComputeOptions object gives access to information about the current HEC-WAT simulation, including the model sequence, analysis period, and if the model is an FRA compute, the event, lifecycle, and realization number.
Important!
The name of the functions called by the scripting plugin must be computeAlternative
, and if output variables are used, computeOutputVariable
, otherwise the Scripting Plugin will not be able to run the script. The arguments may take different names, but the order is important.
For computeAlternative
the first argument will always be the ScriptingPluginAlt
object that contains the information defined in the Scripting Plugin editor, and the second option will always be the ComputeOptions
object that contains information about the time window, simulation file, and FRA event.
Code defined outside of the computeAlternative
function, typically import statements and definitions of constants, will also be run during the compute, prior to the computeAlternative
function is called.
Failed Scripting Plugin computes
If the scripting plugin fails by returning False
(or zero), the Compute Progress window will show a status message informing the user that the "Compute Failed", and an error message in the compute log identifying the name of the Scripting Alternative.
If an exception is raised by the script, (for example: a variable or function used by the script is not defined), the traceback identifying the error and which line it occurred will be printed to the compute log.
If the script has a syntax or indentation error that prevents it from running, the Scripting Plugin will print an error message indicating a "Python Compilation Error" and identify the issue and line it occurs on.