Definition: A state variable is one of a set of variables used to describe the state of a dynamical system.  Since a watershed is a dynamic system, this definition applies to all the variables that can be computed for an object or a group of objects in the watershed as it varies through time.

ResSim places state variables into three categories:

  • Model Variables—state variables that ResSim computes natively for each element in a ResSim network. Examples include: reservoir pool elevation, release from an outlet, or flow through a diversion. A Model Variable is computed for each timestep of the simulation and stored in a Time Series object.
  • External Variables—variables that have been computed externally (outside of ResSim) and provided as input time series. Examples include: a time-series of forecasted snowmelt inflow volume or water supply demand. An External Variable is also stored in a Time Series object.
  • (User-Defined) State Variables—variables that a user defines by writing a Jython script that will be used to compute the value of the variable for each timestep of the simulation. A State Variable is an object that belongs to a reservoir network and contains a Time Series object that holds the state values computed by the script.

In order to minimize confusion, outside of the descriptions above, the term state variable will only be used in this manual to describe user-defined or scripted State Variables. For the most part, the modifiers: user-defined and scripted will be omitted unless they are needed for clarity.

Since many reservoirs are operated based on the state of the watershed (e.g., dry or wet hydrologic conditions) or some abstract state of a reservoir or system of reservoirs (e.g., a system drought level), State Variables can be developed to compute these watershed conditions.

State Variables can be used wherever a Model Variable or External Variable can be used to control or influence the operation of a reservoir. This includes (but is not limited to):

  • Function-of Rules
  • IF_Block Conditional Expressions
  • Zones
  • Diversions

A State Variable is a special form of a TimeSeries Object. It is defined and computed through the execution of a user-defined Jython script. Jython is a Java implementation of the Python programming language. The script may perform calculations referencing any TimeSeries object in the ResSim network and alternative, including all model variables and other State Variables.

Python and Jython tutorials and references can be found at www.python.org and www.jython.org.