Scripting Plugin API
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
.
Method | Description |
---|---|
currentAlternative.getAbsolutePath(relativePath) | returns a string appending the relativePath string to the full watershed directory. |
| adds the given string to the compute window's log. Warning messages and error messages will be in orange or red by default. |
| 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.
Method | Description |
---|---|
options.getSimulationName() | returns a string of the current simulation name. |
options.getRunDirectory() | returns a string of the current watershed's runs directory. |
| returns the current simulation's RunTimeWindow object (or for an event in an FRA compute) |
| 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.
Method | Description |
---|---|
| returns an get the number of events in the lifecycle. |
| 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?)>) |
| 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. |
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.
Method | Description |
---|---|
currentAlternative.getInputDataLocations() | returns a list of the DataLocation objects mapped as input timeseries to the Scripting Alternative. |
currentAlternative.getTimeSeriesForInputDataLocation(dlName, param) | returns a |
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. |
| writes a 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):
#...
Common methods used for dealing with Output Variables are detailed below.
Methods | Description |
---|---|
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)
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.