State Variables and Scripting
Topics
Terminology
Model Variables
State Variables
Creating and Using Scripted State Variables
Creating and Using Scripted Rules
Utility (static) Scripts
Jython
What is a State Variable?
In generic terms, a state variable is an item that represents
the state of an element of a ResSim model at each time step
throughout the simulation period.
By definition, state variables are time-series objects since
they hold time-series data
State variables can be used in rules, IF-THEN-ELSE blocks,
zones, and diversions.
ResSim builds internal state variables for each model
element and parameter that it computes or uses.
reservoir pool elevation, flow leaving a junction, etc
User-defined state variables are built by creating scripts
to set their values.
What is a State Variable?
In HEC-ResSim terminology:
variables
User-defined state variables are called state variables
Internal state variables are called model
Model Variables - Limitations
Model Variables provide the states of single elements
within a ResSim model.
Model Variables cannot represent abstract concepts
that require analysis of more than one element,
such as:
basin wetness
drought level
system storage utilization
depth-area-duration considerations
State Variables vs. Model Variables
Like Model Variables, State Variables are time-series
objects that belong to the Network.
Like Model Variables, State Variables are globally
accessible, so they may be used in multiple rules and
in multiple reservoirs.
Unlike Model Variables, State Variables are not
associated with a specific ResSim element (reservoir
pool, junction, etc). As such, they can represent
complex or abstract concepts.
State Variable Scripts
HEC-ResSim computes a state variable by executing a
Jython script at every time step throughout the
simulation often more than once per time step.
A State Variable script can access Model Variables
and other State Variables
For current or previous time steps.
Script execution order is currently based on the order of
creation. Plan ahead for State Variable scripts that depend
on other State Variables at the same time step
A State Variable script can perform any function
available to Jython
Do not to perform lengthy tasks (e.g. disk or network
access) because of the number of times the script is
executed!
Creating a State Variable
Select State Variables from the main Edit menu.
Select New from the State Variable menu in the Editor.
Enter the desired name in the Name field of the New State
Variable dialog.
Enter a description if you can
Press the OK button.
Identify (name) the State Variables parameter (DSS C Part)
in the Parameter Name field.
Select the parameter type from the Parameter Type list.
Edit the script text as desired in the edit panel.
Press the Compile Script button to check for syntax errors.
The State Variable Editor will open
Fix any errors and repeat this step.
Save the script by selecting Save from the State Variable
menu
Editing Existing State Variables
Select State Variables from the main Edit menu.
Select the desired State Variable from the Name dropdown
list.
Edit the script text as desired.
Press the Compile Script button to check for syntax errors.
Fix any errors and repeat this step.
Save the script by selecting Save from the State Variable
menu.
Creating and Editing State
Variables
The State Variable Editor
Script Tabs
Script Pane
(editor window)
API Pane
(Objects and
Methods window)
API preview &
Cursor Location
Using the State Variable Editors
API Pane
Selecting a node (not a folder) in the API Pane causes the API
insertion text for the selected node to be displayed in the API
preview bar.
Double-clicking on a node in the API Pane causes its API text
to be inserted at the current cursor position in the Editor
Pane.
The same can be accomplished by selecting a node in the API and then
selecting the Insert in Script button under the API Pane.
Dragging a node in the API Pane to some position in the Editor
Pane causes its API text to be inserted at that location in the
Editor Pane.
State Variable Editor API Pane
Example
Creating New Scripted Rules
To create a Scripted Rule:
Open the Reservoir Editor to the Zone-Rules tab of the
Operations tab.
Right-click the desired zone and select Add New Rule
from the context menu.
Enter the desired name and select the desired release
element in the New Operating Rule dialog.
Select Script for the Rule Type.
Press the OK button.
Edit and check syntax as with a State Variable.
Editing Existing Scripted Rules
To edit an existing Scripted Rule:
Select the desired rule in the Zone-Rules tab of the
Operations tab of the Reservoir Editor.
Edit the script as desired. The editor is similar to the State
Variable editor.
Creating Scripted Rule Example
Editing Scripted Rule Example
Scripting in HEC-ResSim
There are two types of Scripts in HEC-ResSim
1. Scripts executed during simulations
These scripts can:
Compute and store the state of some (concrete or abstract)
portion of the model at each simulation time step State
Variable Scripts
Compute a flow limit (minimum, maximum, specified, or free) at
each simulation time step Scripted Rules
These scripts cannot:
Know when they execute in relation to other scripts
Know when they are executed for the last time
However, new capabilities in HEC-ResSim 3.1 handle initialization
and clean-up associated with state variable scripts
Scripting in HEC-ResSim
2. Scripts executed outside simulations
These scripts can:
Pre-process data for simulations
Run simulation (some or all alternatives)
Post-process data from simulations, generate plots, reports,
etc
These scripts cannot:
Interact with a running simulation
Scripts Executed Outside
Simulations
There is only one type of script executed outside simulations,
which we call static or utility scripts.
Static scripts resemble HEC-DSSVue scripts:
They can be executed from the Script Selector, Script Pane, or Script
Editor.
They are edited and tested in the Script Editor.
Their location in the Tree Pane of the Script Editor corresponds to a file
on disk.
Static scripts go beyond HEC-DSSVue scripts:
Script location in the Tree Pane determines script visibility.
Scripts can have knowledge of the current module and current
simulation.
The Script Selector
The Script Selector is accessed by selecting Scripts from
the Tools menu item in any module.
The Script Selector is titled according to the current module.
Execute a script by pressing the Save and Test button in the
script editor or by creating (and using) a button for your
script in the Simulation Control Panel or in the Scripts
panel
The Script Editor
Tree Pane
Script Name
Visibility Switches
File Name
Description Pane
Icon Selector
Pre-Defined Variables
Editor Pane
Edit/Save/Test Buttons
Dismissal Buttons
Location / Mode Indicators
Static Script Visibility
For a static script to be visible
its position in the Tree Pane
must be in the All Watersheds folder
or Current Watershed folder
must be in Modules folder or folder
corresponding to the current module
its Show in Script Selector switch
must be checked to be visible in the
Script Selector
its Display Script to User switch
must be checked to be visible in the
script pane
Creating a New Static Script
From the Scripts tree in the Script
Editor, right-click on one of the
module folders in the All Watersheds
or Current Watershed folder:
Watershed Setup
Reservoir Network
Simulation
Select New Script from the context
menu
Enter a name in the Label field
Enter the script text in the Editor Pane
Press the Save or Save and Test button
Editing Existing Static Scripts
To edit an existing Static Script, do one of the
following:
double-click on the script in the Tree Pane
right-click on the script in the Tree Pane and select Edit
Script from the context menu
select the script in the Tree Pane and do one of the
following:
Select Open from the File menu
Press the Edit button
Testing Existing Static Scripts
To test an existing Static Script from the Script
Editor, select the script in the Tree Pane and do
one of the following:
Select Test from the File menu
Press the Save and Test button
Adding Scripts to the Simulation
Control Panel
To add a script to the
Simulation Control Panel:
Right-click in the scripts area
Select Edit Script List from the
context menu
Use the Edit Scripts dialog to
move the desired scripts to the
Selected list
Static Script Access to ResSim
Information
isWatershedOpened()
getWatershed()
These functions are included in the ResSimUtils
getWatershedName()
openWatershed(watershedName)
module provided with this workshop.
closeWatershed()
getCurrentModule()
selectModule(moduleName)
getTimeWindow()
getTimeWindowString()
getSimulation()
getSimulationName()
openSimulation(simulationName)
getSimulationRun(alternativeName)
getSimulationRuns()
getSelectedSimulationRuns()
getAlternativeNames()
getSelectedAlternativeNames()
extractSimulationData()
computeSimulationRun(simulationRun)
getSimulationDSSFileName()
getFParts()
getFPart(alternativeName)
runSimulation(simulationName, newExtract=False, *alternativeNames)
What is Jython?
[Link]
Jython is a Java-based implementation of the
Python programming language. This means:
You learn the Python language to learn Jython.
Jython code can work seamlessly with Java code.
Anybody programming experience will pick it up
quickly.
Others can quickly become effective by mimicking
examples.
What is Python?
[Link]
Python is a programming language that is
interpreted
open source
object oriented
and has
simple syntax
high level dynamic data types
Some Books Available
Review
Scripts Executed During Simulations
State Variable Scripts
Scripted Rule Scripts
Scripts Executed Outside Simulations
Static Scripts
Jython
