The Jython environment in which the Scripting Alternative's script is evaluated has the Jython and Java standard libraries available to import modules or packages from.  The Jython 2.7 standard library is documented at jython.org and includes a subset of the modules detailed in the Python 2.7 documentation.  The Java 8 Standard Edition Runtime Environment's JavaDocs are available on the Oracle website.

In addition to these standard libraries, the HEC-WAT Java API can be accessed by the script.  This section details the HEC-WAT Java API most relevant for Scripting Plugin script development, covering primarily the objects passed to functions in the script.

Best Practice

While it is possible, consider alternatives before creating a user interface in a Scripting Plugin script.  These will not be accessible during a distributed compute and will prevent the compute from continuing past this point.  If configuration of the script beyond what is provided in the Scripting Plugin Alternative is necessary, use information (such as the WAT simulation name or lifecycle number) to identify and read parameters from a configuration file in the watershed.

Scripting Alternative (ScriptingPluginAlt) object

The ScriptingPluginAlt object, typically passed into the script as the currentAlternative parameter, contains methods to access information about the scripting alternative used to launch the script, including mapped input and output DataLocations  and OutputVariables .

MethodDescription
currentAlternative.getAbsolutePath(relativePath)returns a string appending the relativePath  string to the full watershed directory.

currentAlternative.addComputeMessage(messageString)

currentAlternative.addComputeWarningMessage(messageString)

currentAlternative.addComputeErrorMessage(messageString)

adds the given string to the compute window's log.  Warning messages and error messages will be in orange or red by default.

currentAlternative.getInputFPart() 

returns a string of the FPart <why is it called input?>
currentAlternative.getScriptFilename()  returns the filename of the script used by this Scripting Alternative.
currentAlternative.getTimeStep() <what does this do?  it is defined with input/output locations, but does the scripting plugin 'timestep' have a meaning?>


Best Practice

When opening files, use the method call currentAlternative.getAbsolutePath() to convert a pathname relative to the watershed to an absolute pathname in the watershed directory (for example, "/shared/script_configuration.json" to "C:/users/me/projects/Example_WAT_Watershed/shared/script_configuration.json").  This will ensure that the script works not just on the developer's computer but also anywhere else the watershed may be run, such as another modeler or in a distributed compute.

Compute Options (ComputeOptions) objects

The ComputeOptions  object, passed into the script as options, contains methods to access information at run-time about the current HEC-WAT compute.  A subclass of the ComputeOptions  class may be provided depending on the compute type, with special functions available in an FRA compute detailed in a section below.

MethodDescription
options.getSimulationName() returns a string of the current simulation name.
options.getRunDirectory() returns a string of the current watershed's runs  directory.

options.getSimulationTimeWindow() 

returns the current simulation's RunTimeWindow object (or for an event in an FRA compute)

options.isFrmCompute() 

returns True if the compute is an FRA compute.

Accessing FRA compute information

In an FRA compute, the ComputeOptions  object called options can be used to access information about the current event and lifecycle.

MethodDescription

options.getCurrentEventNumber()  

options.getNumberEvents() 

returns an int  of the current event within the lifecycle.  This number repeats for each lifecycle, starting at 1.

get the number of events in the lifecycle.

options.getCurrentLifecycleNumber() 

options.getNumberLifecycles() 

returns an int of the current lifecycle number.

returns an int the total number of lifecycles that the FRM simulation is going to compute (<is this total number or per node or per simulation launch (e.g. if starting on LC2?)>)

options.getEventRandom() 

options.getLifeCycleRandom() 

options.getRealizationRandom() 


returns a random value based on the current event number, lifecycle number, or realization number. 

The lifecycle and realization numbers are constant through the same lifecycle or realization.  The sequence during a compute should be maintained from one run of the FRA compute of the simulation to another.  Using the same seeds (set in the Simulation editor), two different simulations can be configured to produce the same sequence of random numbers.


Methods to get the current realization or total number of realizations are not implemented.

Data Locations and Time Series

Reading an input time series

The input time series defined in the Scripting Plugin editor can be used to define which inputs the script should look for.  This allows for the inputs to the script to be defined in the HEC-WAT interface by the modeler, rather than changing pathnames or parts of pathnames in the script.  In a loop the script can repeat an operation across multiple inputs.

MethodDescription
currentAlternative.getInputDataLocations() returns a list of the DataLocation  objects mapped as input timeseries to the Scripting Alternative.
currentAlternative.getTimeSeriesForInputDataLocation(dlName,  param) 

returns a TimeSeriesContainer containing data for the input data location identified by dlName  and param. These match the name and parameter specified in the Scripting Plugin Alternative editor and model linking editor.

Writing an output time series

Similar to input time series locations, outputs can be defined in the Scripting Plugin editor.  This allows the user to link the output from the Scripting Plugin to later models in the compute sequence.



currentAlternative.getOutputDataLocations() returns a list of DataLocation  objects that the Scripting Plugin alternative is expecting to output.

currentAlternative.writeTimeSeries(tsc) 

writes a TimeSeriesContainer  object containing the output data to the simulation DSS file.

The F-part in the output will be overwritten with the output F-Part for the Scripting Plugin alternative being run.

Best Practice

Using input and output timeseries API detailed here is preferred over accessing the simulation DSS file directly.  The input and output timeseries API allow for the use of the HEC-WAT model linking editor and ensures that other models can access the data output by the Scripting Plugin.

Output Variables

Output variables are computed with an additional function defined in the script, called computeOutputVariable .  This function takes the currentAlternative  object as well as an object about the Output Variable to be computed.  The setValue method of the currentVariable  object is used to provide HEC-WAT the value of the Output Variable.  The computeOutputVariable  function is called for once for each Output Variable selected in the FRA compute, so the script must distinguish between Output Variables provide the correct value for each.  To be computed by the Scripting Plugin, the Output Variable must be defined in the Scripting Alternative editor and selected in the Output Variables for the current FRA compute.

Writing Output Variables

def computeOutputVariable(currentAlternative, currentVariable):
    #...
PY


Common methods used for dealing with Output Variables are detailed below.

MethodsDescription
currentAlternative.hasOutputVariables()  returns True  if output variables are defined for this Scripting Plugin alternative
currentAlternative.getAvailOutputVariables()  returns a list of all output variables for this Scripting Plugin alternative
currentVariable.getName() returns a string containing the name of the currentVariable object passed into computeOutputVariable 
currentVariable.setValue(value) takes a number and sets the value of the currentVariable object passed into computeOutputVariable 

Accessing the simulation file

The simulations output file is accessed by calling options.getDssFilename(), which returns a string containing the filename.  This string can be passed to the standard HEC-DSS libraries to open the file.  The resulting HecDss  file object can be accessed and modified using the API detailed in Chapter 8 of the HEC-DSSVue scripting manual.

Accessing the simulation DSS file

dssFilename = options.getDssFilename()
dssFile = HecDss.open(dssFilename)
#...
hecMathObj = dssFile.read(pathname)
PY

Best Practice

When writing output to or manipulating files with the scripting plugin, it is necessary to close output files and flush the file buffer to ensure that output files are fully written before the next model in the compute sequence launches.   This will likely not be an issue on a user's local machine with the HEC-WAT GUI, but can cause issues in distributed computes where the time between HEC-WAT launching models may be smaller than the time to write updates to the filesystem.

Instead of using the .done() method on HEC-DSS files, use the .close() method if the script is being run at the end of the model sequence.  Not including this method may cause distributed compute failures.

Other types of file output, like text or binary files, may require different methods to ensure the file is closed and buffers are flushed.

Using additional Python modules and Java packages

Additional Python modules and Java packages (contained in .jar files) can be imported by name if the module or package is placed in the watershed's scripts  directory.

Best Practice

Modifying the sys.path  list prior to importing modules is not advised, as the sys.path  list is carried over from one event to the next.