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


New Scripting Alternative prompt

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.

Scripting Alternative editor showing example input data locations being defined as time series.


Clicking "Edit Script" opens the HEC-WAT Script Editor, which includes an API reference window to assist the user in writing the script.

Script editor window showing an example script being edited and the API pane open to the Compute Options object

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.

Output Variables tab of the Scripting Plugin editor, showing several example Output Variables defined.

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
PY


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.

Script failure error message as a result of the script returning False.


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.

Script failure error message as a result of an exception raised by the script.


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.

Script failure error message as a result of a syntax error.